Tailwind-函数和指令

Tailwind 向您的 CSS 公开的自定义函数和指令的参考。

指令

指令是自定义的 Tailwind 特有 at-rules，您可以在 CSS 中使用它们，为 Tailwind CSS 项目提供特殊功能。

@import

使用 @import 指令内联导入 CSS 文件，包括 Tailwind 本身

css

@import "tailwindcss";
它默认等价于：

@tailwind base;
@tailwind components;
@tailwind utilities;

@theme

用 @theme 来写你项目里要用的一套“设计基础值”，比如：

颜色（品牌色、背景色）
字体（主字体、副字体）
断点（响应式布局的屏幕宽度）

这些东西相当于你项目的“设计字典”，以后所有样式都能引用它们，方便统一管理和修改。

css

@theme {
  --font-display: "Satoshi", "sans-serif";

  --breakpoint-3xl: 120rem;

  --color-avocado-100: oklch(0.99 0 0);
  --color-avocado-200: oklch(0.98 0.04 113.22);
  --color-avocado-300: oklch(0.94 0.11 115.03);
  --color-avocado-400: oklch(0.92 0.19 114.08);
  --color-avocado-500: oklch(0.84 0.18 117.33);
  --color-avocado-600: oklch(0.53 0.12 118.34);

  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);

  /* ... */
}

在主题变量文档中了解有关自定义主题的更多信息。

@source

使用 @source 指令显式指定 Tailwind 自动内容检测未拾取的源文件

Tailwind 会自动扫描你的项目文件（HTML、JSX、Vue 等）找出用到的类名，只生成这些类对应的 CSS。如果有些文件没被它自动识别到，你可以用 @source 手动告诉 Tailwind： “这些文件里也有要用的类名，别漏掉！”

css

@source "../node_modules/@my-company/ui-lib";

在检测源文件中的类名文档中了解有关自动内容检测的更多信息。

@utility

使用 @utility 指令将自定义实用程序添加到您的项目，这些实用程序可与 hover、focus 和 lg 等变体一起使用

css

@utility tab-4 {
  tab-size: 4;
}

在添加自定义实用程序文档中了解有关注册自定义实用程序的更多信息。

@variant

你可以用 @variant 在自定义 CSS 里套用 Tailwind 的变体（hover, focus, dark, md 等），不用手写选择器。

css

.my-element {
  background: white;

  @variant dark {
    background: black;
  }
}

在使用变体文档中了解更多关于使用变体的信息。

@custom-variant

使用 @custom-variant 指令在您的项目中添加自定义变体

css

@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
/* 选中所有祖先元素含有 data-theme="midnight" 的元素 */

这使您可以编写实用程序 theme-midnight:bg-black 和 theme-midnight:text-white。

在添加自定义变体文档中了解有关添加自定义变体的更多信息。

@apply

使用 @apply 指令将任何现有的 uility 内联到您自己的自定义 CSS 中

css

.select2-dropdown {
  @apply rounded-b-lg shadow-md;
}

.select2-search {
  @apply rounded border border-gray-300;
}

.select2-results__group {
  @apply text-lg font-bold text-gray-900;
}

当您需要编写自定义 CSS（例如覆盖第三方库中的样式）但仍希望使用您的设计令牌并使用与在 HTML 中使用的相同语法时，这非常有用。

@reference

当你在 Vue、Svelte 这种单文件组件的 <style> 里写自定义 CSS，如果要用 Tailwind 的 @apply（复用工具类）或 @variant（写变体），必须先让 Tailwind 知道主题变量、工具类和变体在哪里定义的。

你可以用 @reference 指令引用你的主样式文件（通常是 app.css），这样 Tailwind 就能“看见”这些值，但不会真的把主样式再打包一份进这个文件里，避免重复。

vue

<template>
  <h1>Hello world!</h1>
</template>

<style>
  @reference "../../app.css";/* 告诉 Tailwind: 用 app.css 的主题和工具类，但不要重复导入 */

  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

编译后不会多生成一份 app.css 的样式

如果你用 @import "../../app.css";，那么 app.css 的所有样式都会再打包一遍 → CSS 文件变大，可能重复。 @reference 就是专门为这种情况优化的，只引用元数据，不重复生成 CSS。

如果您只是使用默认主题，您可以直接导入 tailwindcss

vue

<template>
  <h1>Hello world!</h1>
</template>

<style>
  @reference "tailwindcss";

  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

函数

Tailwind 提供了以下构建时函数，以简化颜色和间距比例的使用。

—alpha()

使用 --alpha() 函数调整颜色的不透明度

css

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

编译后的 CSS

css

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

—spacing()

使用 --spacing() 函数根据您的主题生成间距值

css

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

编译后的 CSS

css

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

这在任意值中也很有用，尤其是在与 calc() 结合使用时

css

<div class="py-[calc(--spacing(4)-1px)]">
  <!-- ... -->
</div>

兼容性

以下指令和函数仅用于与 Tailwind CSS v3.x 的兼容性。

@config

使用 @config 指令加载基于旧版 JavaScript 的配置文件

css

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

v4.0 中不支持基于 JavaScript 的配置中的 corePlugins、safelist 和 separator 选项。

@plugin

使用 @plugin 指令加载基于旧版 JavaScript 的插件

css

@plugin "@tailwindcss/typography";

@plugin 指令接受包名称或本地路径。

指令