指令

指令是你在输入 CSS 中编写的、以 @ 为前缀的 at-rule，用于组合、扩展并控制 Tailwind 的输出。本页介绍 @apply、@utility、@variant、@custom-variant 和 @layer。@theme 详见 主题；@plugin 详见 插件；@source 详见 @source。

@apply

@apply 会将现有工具类的声明内联到你自己的选择器中。你可以用它将工具类样式附加到语义化类中，包括嵌套选择器和媒体查询内部。

use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');

变体可以放在 @apply 列表中——@apply bg-blue-500 hover:bg-blue-600; 会展开 :hover 状态，@apply px-4 md:px-6 lg:px-8; 这样的响应式前缀则会生成相应的 @media 规则。重要修饰符也同样有效（@apply !flex;）。同时支持嵌套选择器，因此类似 .card { h2 { @apply text-xl font-bold; } } 的规则会将工具类应用于嵌套的 h2。

@apply 是一条语句：@apply px-4 { … } 带有主体时会报错。只列出带连字符标识符（@apply --my-mixin;）的 @apply，是 CSS mixins 草案中的 CSS 混入，而非工具类列表，因此 TailwindPHP 无法解析它；在同一个 @apply 中混用混入和工具类也会报错（You cannot use @apply with both mixins and utilities…）。目前，混入规则会从输出中丢弃，而不会原样传递（#12）。

@utility

@utility 会注册一个自定义工具类，使其参与 Tailwind 的引擎处理——它会被排序到 utilities 层，并且像内置工具类一样支持变体。静态工具类采用固定的主体：

@utility content-auto {
    content-visibility: auto;
}

由于它是一个真正的工具类，变体会自动组合（hover:content-auto、md:content-auto）。主体本身也可以使用 @apply 和嵌套选择器：

@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}

函数式工具类的名称使用 -* 后缀，并通过 --value() 读取匹配到的值：

@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}

--value() 会依次尝试使用各来源解析候选项的值：主题命名空间（--gutter-*）、带数据类型的任意值（[length]），或未指定类型的值（integer、number、percentage、ratio）。无法解析其 --value() 的声明会被丢弃，因此可以叠加多个声明作为回退链：

--modifier() 对 / 之后部分的解析方式相同：主体中包含 line-height: --modifier(integer); 时，gutter-4/7 也会生成 line-height: 7。工具类名称遵循 TailwindCSS v4.3.3 规则：最多一个 /，% 只能在末尾且前面必须是数字，小数点只能出现在数字之间。

@variant

@variant 会将变体应用于你自己的 CSS 内部声明，而无需定义工具类：

.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}

.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}

变体可以叠加（@variant hover:focus）、用逗号列出、相互嵌套，也可以指定你自己的 @custom-variant。为保持向后兼容，顶层 @variant 没有主体或带有 @slot 时，会被视为 @custom-variant。

@custom-variant

@custom-variant 会定义一个新变体，你可以将它作为前缀加到任意工具类上。简写形式会命名变体，并在括号中指定选择器或 at-rule。

选择器列表变体使用 & 代表该元素：

@custom-variant hocus (&:hover, &:focus);

hocus:bg-blue-500 随后会同时生成 :hover 和 :focus 规则。属性形式的写法也相同：

@custom-variant loading (&[data-loading="true"]);

at-rule 变体会将匹配的工具类包裹在该 at-rule 中：

@custom-variant tablet (@media (min-width: 600px));

自定义变体可以与内置变体叠加——sm:hocus:bg-blue-500 会将 hocus 选择器嵌套在 sm 媒体查询中。更复杂的情况可以使用块形式，并用 @slot 标记工具类声明的注入位置：

@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}

@layer

@layer 使用原生的 CSS 层来控制层叠顺序。单独的 @layer 语句会声明各层的顺序；无论选择器的优先级如何，后面的层都优先。Tailwind 的标准顺序为：

@layer theme, base, components, utilities;

这正是 @import "tailwindcss" 在内部设置的顺序。你可以声明自己的顺序，也可以拆分成多条语句（先写 @layer reset, base;，再写 @layer components, utilities;），还可以通过块将规则分配到指定层：

use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');

通过 @layer base 添加基础样式，可以让它们排在 components 和 utilities 之下，因此工具类始终会覆盖元素的默认样式。@layer components { … } 也适用相同原则，可用于将组件类置于工具类之下。匿名层和 @import 上的 layer() 修饰符详见 导入。

后续步骤

• 主题 — @theme 设计令牌和主题函数。
• 导入 — @import、虚拟模块和 layer() 修饰符。
• 插件 — @plugin 指令和插件 API。
• @source — 控制要扫描哪些文件和类名。