函数与指令

A reference for the custom functions and directives Tailwind exposes to your CSS.

指令

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

@import

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

CSS

@import "tailwindcss";

@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 自动内容检测没有扫到的源文件：

CSS

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

更多自动内容检测的内容，见在源文件中检测类名文档。

@utility

用 @utility 指令向项目添加自定义工具类，它们可与 hover、focus 和 lg 等变体一起使用：

CSS

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

更多注册自定义工具类的内容，见添加自定义工具类文档。

@variant

用 @variant 指令把 Tailwind 变体应用到 CSS 中的样式：

CSS

.my-element {
  background: white;

  @variant dark {
    background: black;
  }
}

更多使用变体的内容，见使用变体文档。

@custom-variant

用 @custom-variant 指令向项目添加自定义变体：

CSS

@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

这样就可以写 theme-midnight:bg-black 和 theme-midnight:text-white 这类工具类。

更多添加自定义变体的内容，见添加自定义变体文档。

@apply

用 @apply 指令把已有工具类内联到自己的自定义 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 modules 里使用 @apply 或 @variant，需要导入主题变量、自定义工具类和自定义变体，才能在该上下文中使用这些值。

为了不在输出中重复任何 CSS，用 @reference 指令引用主样式表，而不会真正把样式包含进去：

Vue

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

<style>
  @reference "../../app.css";

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

如果只用默认主题、没有任何自定义（例如没有使用 @theme、@custom-variant、@plugin 等），可以直接导入 tailwindcss：

Vue

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

<style>
  @reference "tailwindcss";

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

子路径导入

使用 CLI、Vite 或 PostCSS 时，@import、@reference、@plugin 和 @config 指令都支持子路径导入，工作方式类似打包器和 TypeScript 的路径别名：

package.json

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

Vue

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

<style>
  @reference "#app.css";

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

函数

Tailwind 提供以下构建时函数，让处理颜色和间距比例更轻松。

--alpha()

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

Input CSS

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

Compiled CSS

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

--spacing()

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

Input CSS

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

Compiled CSS

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

这在任意值中也很有用，尤其是和 calc() 组合时：

HTML

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

兼容性

以下指令和函数仅为与 Tailwind CSS v3.x 兼容而存在。

@config 和 @plugin 指令可以与 @theme、@utility 以及其他 CSS 驱动的功能一起使用。这样可以把主题、自定义配置、工具类、变体和预设逐步迁移到 CSS。CSS 中定义的内容会在可能时合并，否则优先于配置、预设和插件中的定义。

@config

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

CSS

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

基于 JavaScript 的配置中的 corePlugins、safelist 和 separator 选项在 v4.0 中不受支持。要在 v4 中 safelist 工具类，请使用 @source inline()。

@plugin

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

CSS

@plugin "@tailwindcss/typography";

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

theme()

用 theme() 函数以点记法访问 Tailwind 主题值：

CSS

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

此函数已弃用，建议改用 CSS 主题变量。