函数和指令

指令(Directives)

¥Directives

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

¥Directives are custom Tailwind-specific at-rules you can use in your CSS that offer special functionality for Tailwind CSS projects.

@import

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

¥Use the @import directive to inline import CSS files, including Tailwind itself:

CSS

@import "tailwindcss";

@theme

使用 @theme 指令定义项目的自定义设计标记，如字体、颜色和断点：

¥Use the @theme directive to define your project's custom design tokens, like fonts, colors, and breakpoints:

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);
  /* ... */
}

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

¥Learn more about customizing your theme in the theme variables documentation.

@source

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

¥Use the @source directive to explicitly specify source files that aren't picked up by Tailwind's automatic content detection:

CSS

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

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

¥Learn more about automatic content detection in the detecting classes in source files documentation.

@utility

使用 @utility 指令将自定义工具添加到你的项目，这些工具可与 hover、focus 和 lg 等变体一起使用：

¥Use the @utility directive to add custom utilities to your project that work with variants like hover, focus and lg:

CSS

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

了解有关在添加自定义工具文档中注册自定义工具的更多信息。

¥Learn more about registering custom utilities in the adding custom utilities documentation.

@variant

使用 @variant 指令将 Tailwind 变体应用于 CSS 中的样式：

¥Use the @variant directive to apply a Tailwind variant to styles in your CSS:

CSS

.my-element {
  background: white;
  @variant dark {
    background: black;
  }
}

如果你需要同时应用多个变体，请使用嵌套：

¥If you need to apply multiple variants at the same time, use nesting:

CSS

.my-element {
  background: white;
  @variant dark {
    @variant hover {
      background: black;
    }
  }
}

了解有关在悬停、聚焦和其他状态文档中变体的更多信息。

¥Learn more about variants in the hover, focus, and other states documentation.

@custom-variant

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

¥Use the @custom-variant directive to add a custom variant in your project:

CSS

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

这让你可以编写像 pointer-coarse:size-48 和 theme-midnight:bg-slate-900 这样的工具。

¥This lets you write utilities like pointer-coarse:size-48 and theme-midnight:bg-slate-900.

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

¥Learn more about adding custom variants in the registering a custom variant documentation.

@apply

使用 @apply 指令将任何现有工具类内联到你自己的自定义 CSS 中：

¥Use the @apply directive to inline any existing utility classes into your own custom 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 中习惯使用的相同语法时，这将非常有用。

¥This is useful when you need to write custom CSS (like to override the styles in a third-party library) but still want to work with your design tokens and use the same syntax you’re used to using in your HTML.

@reference

如果你想在 Vue 或 Svelte 组件的 <style> 块中或在 CSS 模块中使用 @apply 或 @variant，你将需要导入主题变量、自定义工具和自定义变体以使这些值在该上下文中可用。

¥If you want to use @apply or @variant in the <style> block of a Vue or Svelte component, or within CSS modules, you will need to import your theme variables, custom utilities, and custom variants to make those values available in that context.

要做到这一点而不在输出中重复任何 CSS，请使用 @reference 指令导入主样式表以供参考，而无需实际包含样式：

¥To do this without duplicating any CSS in your output, use the @reference directive to import your main stylesheet for reference without actually including the styles:

Vue

<template>
  <h1>Hello world!</h1>
</template>
<style>
  @reference "../../app.css";
  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

如果你只是使用默认主题而没有自定义，你可以直接导入 tailwindcss：

¥If you’re just using the default theme with no customizations, you can import tailwindcss directly:

Vue

<template>
  <h1>Hello world!</h1>
</template>
<style>
  @reference "tailwindcss";
  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

函数(Functions)

¥Functions

Tailwind 提供以下构建时函数，使使用颜色和间距比例更加容易。

¥Tailwind provides the following build-time functions to make working with colors and the spacing scale easier.

--alpha()

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

¥Use the --alpha() function to adjust the opacity of a color:

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() 函数根据你的主题生成间距值：

¥Use the --spacing() function to generate a spacing value based on your theme:

Input CSS

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

Compiled CSS

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

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

¥This can also be useful in arbitrary values, especially in combination with calc():

HTML

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

兼容性(Compatibility)

¥Compatibility

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

¥The following directives and functions exist solely for compatibility with Tailwind CSS v3.x.

@config

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

¥Use the @config directive to load a legacy JavaScript-based configuration file:

CSS

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

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

¥The corePlugins, safelist, and separator options from the JavaScript-based config are not supported in v4.0.

@plugin

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

¥Use the @plugin directive to load a legacy JavaScript-based plugin:

CSS

@plugin "@tailwindcss/typography";

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

¥The @plugin directive accepts either a package name or a local path.

theme()

使用 theme() 函数使用点符号访问你的 Tailwind 主题值：

¥Use the theme() function to access your Tailwind theme values using dot notation:

CSS

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

此功能已弃用，我们建议改用使用 CSS 主题变量。

¥This function is deprecated, and we recommend using CSS theme variables instead.