43. 函数与指令大全

Tailwind v4 提供了一套 CSS 指令和函数，配置和扩展都能在 CSS 里搞定，不需要再写 JS 配置文件。

指令（Directives）

指令是特殊的 CSS at-rules，以 @ 开头，提供 Tailwind 特有的功能。

@import

导入 CSS 文件，包括 Tailwind 本身：

/* 导入 Tailwind（必须在文件顶部） */
@import "tailwindcss";

/* 导入其他 CSS 文件 */
@import "./typography.css";
@import "./components.css";

@import 支持子路径导入（通过 package.json 的 imports 字段）：

{
  "imports": {
    "#app.css": "./src/css/app.css"
  }
}

@import "#app.css";

@theme

定义项目的设计令牌（主题变量）：

@theme {
  --color-brand: oklch(0.72 0.11 178);
  --font-display: "Satoshi", sans-serif;
  --breakpoint-3xl: 120rem;
}

支持几种变体：

/* inline：使用变量值而非引用 */
@theme inline {
  --font-sans: var(--font-inter);
}

/* static：始终生成所有 CSS 变量 */
@theme static {
  --color-primary: var(--color-red-500);
}

@source

显式指定源文件路径：

/* 扫描指定目录 */
@source "../node_modules/@acmecorp/ui-lib";

/* 设置基础路径 */
@import "tailwindcss" source("../src");

/* 排除指定路径 */
@source not "../src/components/legacy";

/* 禁用自动检测，手动指定所有源 */
@import "tailwindcss" source(none);
@source "../admin";
@source "../shared";

@source 还可以用于强制生成特定工具类：

/* 强制生成 underline 类 */
@source inline("underline");

/* 生成带变体的类 */
@source inline("{hover:,focus:,}underline");

/* 使用范围生成多个类 */
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");

@utility

注册自定义工具类：

/* 简单工具类 */
@utility content-auto {
  content-visibility: auto;
}

/* 复杂工具类（支持嵌套） */
@utility scrollbar-hidden {
  &::-webkit-scrollbar {
    display: none;
  }
}

/* 函数式工具类（接受参数） */
@utility tab-* {
  tab-size: --value(--tab-size-*);
}

自定义工具类自动支持变体：

<div class="hover:content-auto">悬停时启用内容可见性</div>

@variant

在 CSS 中应用 Tailwind 变体：

.my-element {
  background: white;
  
  /* 暗色模式 */
  @variant dark {
    background: black;
  }
  
  /* 组合变体 */
  @variant hover:focus {
    background: gray;
  }
  
  /* 多个变体共享样式 */
  @variant hover, focus {
    outline: 2px solid blue;
  }
}

编译后：

.my-element {
  background: white;
}
@media (prefers-color-scheme: dark) {
  .my-element {
    background: black;
  }
}

@custom-variant

创建自定义变体：

/* 完整语法 */
@custom-variant theme-midnight {
  &:where([data-theme="midnight"] *) {
    @slot;
  }
}

/* 简写语法 */
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

@apply

将工具类内联到自定义 CSS 中：

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

@reference

导入主题变量和工具类定义，不重复输出 CSS：

/* 导入项目样式 */
@reference "../../app.css";

/* 或导入默认主题 */
@reference "tailwindcss";

主要用于 Vue/Svelte 组件的 <style> 块。

@config（兼容指令）

加载 v3 风格的 JavaScript 配置文件：

@config "../../tailwind.config.js";

仅用于渐进迁移，新项目不需要。

@plugin（兼容指令）

加载 v3 风格的 JavaScript 插件：

@plugin "@tailwindcss/typography";

函数（Functions）

函数在 CSS 值中使用，提供计算能力。

—alpha()

调整颜色透明度：

.my-element {
  color: --alpha(var(--color-lime-300) / 50%);
}

编译为：

.my-element {
  color: color-mix(in oklab, var(--color-lime-300) 50%, transparent);
}

—spacing()

基于间距比例生成值：

.my-element {
  margin: --spacing(4);
}

编译为：

.my-element {
  margin: calc(var(--spacing) * 4);
}

在任意值中也很有用：

<div class="py-[calc(--spacing(4)-1px)]">
  精确计算的间距
</div>

—value()

解析工具类参数值（在 @utility 中使用）：

@utility tab-* {
  /* 匹配主题值 */
  tab-size: --value(--tab-size-*);
  
  /* 匹配裸值 */
  tab-size: --value(integer);
  
  /* 匹配字面量 */
  tab-size: --value("inherit", "initial", "unset");
  
  /* 匹配任意值 */
  tab-size: --value([integer]);
}

—default()

为工具类提供默认值：

@utility tab-* {
  tab-size: --value(integer, --default(4));
}

<!-- 使用默认值 4 -->
<pre class="tab"><code>代码</code></pre>

<!-- 指定值 -->
<pre class="tab-2"><code>代码</code></pre>

—modifier()

解析修饰符（类似 --value() 但用于变体部分）：

@utility text-* {
  font-size: --value(--text-*, [length]);
  line-height: --modifier(--leading-*, [length], [*]);
}

<p class="text-xl/relaxed">字号 xl，行高 relaxed</p>

theme()（已废弃）

访问主题值，不推荐使用：

/* 旧写法（不推荐） */
.my-element {
  margin: theme(spacing.12);
}

/* 新写法（推荐） */
.my-element {
  margin: --spacing(12);
}

指令速查表

指令	用途	示例
@import	导入 CSS 文件	@import "tailwindcss";
@theme	定义设计令牌	@theme { --color-brand: oklch(...); }
@source	指定源文件	@source "../node_modules/lib";
@utility	注册自定义工具类	@utility content-auto { ... }
@variant	应用变体到 CSS	@variant dark { ... }
@custom-variant	创建自定义变体	@custom-variant dark (&:where(.dark *));
@apply	内联工具类	.btn { @apply px-4 py-2; }
@reference	导入样式引用	@reference "../app.css";
@config	加载 JS 配置（兼容）	@config "../../tailwind.config.js";
@plugin	加载 JS 插件（兼容）	@plugin "@tailwindcss/typography";

函数速查表

函数	用途	示例
--alpha()	调整颜色透明度	color: --alpha(var(--color-red-500) / 50%);
--spacing()	基于间距比例生成值	margin: --spacing(4);
--value()	解析工具类参数	tab-size: --value(integer);
--default()	提供默认值	--value(integer, --default(4));
--modifier()	解析修饰符	line-height: --modifier(--leading-*);
theme()	访问主题值（废弃）	margin: theme(spacing.12);