函数和指令

指令(Directives)

指令是自定义的 Tailwind 特有 at-规则，你可以在 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:

@import "tailwindcss";

@主题

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

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

@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:

@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:

@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:

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

通过使用变体文档了解更多信息。

🌐 Learn more using variants in the using variants documentation.

@custom-variant

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

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

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

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

🌐 This lets you write utilities theme-midnight:bg-black and theme-midnight:text-white.

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

🌐 Learn more about adding custom variants in the adding custom variants documentation.

@应用

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

🌐 Use the @apply directive to inline any existing utility classes into your own custom 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> 块中使用 @apply 或 @variant，或者在 CSS 模块中使用，你需要导入你的主题变量、自定义工具以及自定义变体，以便在该上下文中使用这些值。

🌐 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:

<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：

🌐 If you’re just using the default theme with no customizations (e.g. by using things like @theme, @custom-variant, @plugin, etc…), you can import tailwindcss directly:

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

子路径导入(Subpath Imports)

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

🌐 When using the CLI, Vite, or PostCSS the directives @import, @reference, @plugin, and @config all support subpath imports which work similarly to bundler and TypeScript path aliases:

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

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

函数(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:

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

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

--间距()

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

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

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

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

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

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

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

兼容性(Compatibility)

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

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

@config 和 @plugin 指令可以与 @theme、@utility 以及其他 CSS 驱动的功能一起使用。这可以用于将你的主题、自定义配置、实用程序、变体和预设逐步迁移到 CSS 中。CSS 中定义的内容将在可能的情况下进行合并，否则将优先于在配置、预设和插件中定义的内容。

🌐 The @config and @plugin directives may be used in conjunction with @theme, @utility, and other CSS-driven features. This can be used to incrementally move over your theme, custom configuration, utilities, variants, and presets to CSS. Things defined in CSS will be merged where possible and otherwise take precedence over those defined in configs, presets, and plugins.

@配置

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

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

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

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

🌐 The corePlugins, safelist, and separator options from the JavaScript-based config are not supported in v4.0. To safelist utilities in v4 use @source inline().

@插件

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

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

@plugin "@tailwindcss/typography";

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

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

主题()

使用 theme() 函数通过点记法访问你的 Tailwind 主题值：

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

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

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

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