函数和指令

​指令(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.

​@tailwind

使用 @tailwind 指令将 Tailwind 的 base、components、utilities 和 variants 样式插入到你的 CSS 中。

🌐 Use the @tailwind directive to insert Tailwind’s base, components, utilities and variants styles into your CSS.

/**
 * This injects Tailwind's base styles and any base styles registered by
 * plugins.
 */
@tailwind base;

/**
 * This injects Tailwind's component classes and any component classes
 * registered by plugins.
 */
@tailwind components;

/**
 * This injects Tailwind's utility classes and any utility classes registered
 * by plugins.
 */
@tailwind utilities;

/**
 * Use this directive to control where Tailwind injects the hover, focus,
 * responsive, dark mode, and other variants of each class.
 *
 * If omitted, Tailwind will append these classes to the very end of
 * your stylesheet by default.
 */
@tailwind variants;

​@layer

使用 @layer 指令来告诉 Tailwind 一组自定义样式属于哪个“层级”。有效的层级有 base、components 和 utilities。

🌐 Use the @layer directive to tell Tailwind which “bucket” a set of custom styles belong to. Valid layers are base, components, and utilities.

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

@layer base {
  h1 {
    @apply text-2xl;
  }
  h2 {
    @apply text-xl;
  }
}

@layer components {
  .btn-blue {
    @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded;
  }
}

@layer utilities {
  .filter-none {
    filter: none;
  }
  .filter-grayscale {
    filter: grayscale(100%);
  }
}

Tailwind 会自动将任何 @layer 指令中的 CSS 移动到与相应 @tailwind 规则相同的位置，因此你不必担心为了避免特异性问题而按特定顺序编写 CSS。

🌐 Tailwind will automatically move the CSS within any @layer directive to the same place as the corresponding @tailwind rule, so you don’t have to worry about authoring your CSS in a specific order to avoid specificity issues.

添加到图层的任何自定义 CSS 只有在你的 HTML 实际使用了该 CSS 时，才会包含在最终构建中，就像 Tailwind 默认内置的所有类一样。

🌐 Any custom CSS added to a layer will only be included in the final build if that CSS is actually used in your HTML, just like all of the classes built in to Tailwind by default.

将任何自定义 CSS 用 @layer 封装起来，也可以对这些规则使用修饰符，例如 hover: 和 focus:，或者像 md: 和 lg: 这样的响应式修饰符。

🌐 Wrapping any custom CSS with @layer also makes it possible to use modifiers with those rules, like hover: and focus: or responsive modifiers like md: and lg:.

​@apply

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

🌐 Use @apply to inline any existing utility classes into your own custom CSS.

当你需要编写自定义 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.

.select2-dropdown {
  @apply rounded-b-lg shadow-md;
}
.select2-search {
  @apply border border-gray-300 rounded;
}
.select2-results__group {
  @apply text-lg font-bold text-gray-900;
}

任何与 @apply 内联的规则默认会移除 !important，以避免特异性问题：

🌐 Any rules inlined with @apply will have !important removed by default to avoid specificity issues:

/* Input */
.foo {
  color: blue !important;
}

.bar {
  @apply foo;
}

/* Output */
.foo {
  color: blue !important;
}

.bar {
  color: blue;
}

如果你想要对现有类进行 @apply 并使其成为 !important，只需在声明的末尾添加 !important:

🌐 If you’d like to @apply an existing class and make it !important, simply add !important to the end of the declaration:

/* Input */
.btn {
  @apply font-bold py-2 px-4 rounded !important;
}

/* Output */
.btn {
  font-weight: 700 !important;
  padding-top: .5rem !important;
  padding-bottom: .5rem !important;
  padding-right: 1rem !important;
  padding-left: 1rem !important;
  border-radius: .25rem !important;
}

请注意，如果你使用的是 Sass/SCSS，你需要使用 Sass 的插值功能才能让它工作：

🌐 Note that if you’re using Sass/SCSS, you’ll need to use Sass’ interpolation feature to get this to work:

.btn {
  @apply font-bold py-2 px-4 rounded #{!important};
}

​将 @apply 与每个组件的 CSS 一起使用(Using @apply with per-component CSS)

像 Vue 和 Svelte 这样的组件框架支持在每个组件文件中通过 <style> 块添加每个组件的样式。

🌐 Component frameworks like Vue and Svelte support adding per-component styles within a <style> block that lives in each component file.

如果你尝试在这些每组件的 <style> 块中对你在全局 CSS 中定义的自定义类进行 @apply，你会收到关于该类不存在的错误:

🌐 If you try to @apply a custom class you’ve defined in your global CSS in one of these per-component <style> blocks, you’ll get an error about the class not existing:

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

@layer components {
  .card {
    background-color: theme(colors.white);
    border-radius: theme(borderRadius.lg);
    padding: theme(spacing.6);
    box-shadow: theme(boxShadow.xl);
  }
}

<div>
  <slot></slot>
</div>

<style>
  div {
    /* Won't work because this file and main.css are processed separately */
    @apply card;
  }
</style>

这是因为在底层，像 Vue 和 Svelte 这样的框架会独立处理每一个 <style> 块，并对每一个块单独运行你的 PostCSS 插件链。

🌐 This is because under-the-hood, frameworks like Vue and Svelte are processing every single <style> block independently, and running your PostCSS plugin chain against each one in isolation.

这意味着如果你有 10 个组件，每个组件都有一个 <style> 块，Tailwind 会被运行 10 次，每次运行都对其他运行一无所知。因为这个原因，当你在 Card.svelte 中尝试 @apply card 时会失败，因为 Tailwind 根本不知道 card 类存在，因为 Svelte 是在完全隔离的情况下处理 Card.svelte 和 main.css 的。

🌐 That means if you have 10 components that each have a <style> block, Tailwind is being run 10 separate times, and each run has zero knowledge about the other runs. Because of this, when you try to @apply card in Card.svelte it fails, because Tailwind has no idea that the card class exists since Svelte processed Card.svelte and main.css in total isolation from each other.

解决此问题的方法是在组件中使用 插件系统 将你希望的任何自定义样式定义在 @apply 中:

🌐 The solution to this problem is to define any custom styles you want to @apply in your components using the plugin system instead:

const plugin = require('tailwindcss/plugin')

module.exports = {
  // ...
  plugins: [
    plugin(function ({ addComponents, theme }) {
      addComponents({
        '.card': {
          backgroundColor: theme('colors.white'),
          borderRadius: theme('borderRadius.lg'),
          padding: theme('spacing.6'),
          boxShadow: theme('boxShadow.xl'),
        }
      })
    })
  ]
}

这样，任何使用该配置文件处理的 Tailwind 文件都可以使用这些样式。

🌐 This way any file processed by Tailwind that uses this config file will have access to those styles.

说实话，最好的解决办法就是根本不要做这种奇怪的事情。直接在你的标记中按预期使用 Tailwind 的工具类，不要滥用 @apply 功能来做这种事情，这样你的体验会好得多。

🌐 Honestly though the best solution is to just not do weird stuff like this at all. Use Tailwind’s utilities directly in your markup the way they are intended to be used, and don’t abuse the @apply feature to do things like this and you will have a much better experience.

​@config

使用 @config 指令来指定 Tailwind 在编译该 CSS 文件时应使用的配置文件。这对于需要为不同 CSS 入口点使用不同配置文件的项目非常有用。

🌐 Use the @config directive to specify which config file Tailwind should use when compiling that CSS file. This is useful for projects that need to use different configuration files for different CSS entry points.

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

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

你提供给 @config 指令的路径是相对于该 CSS 文件的，并且会优先于在你的 PostCSS 配置或 Tailwind CLI 中定义的路径。

🌐 The path you provide to the @config directive is relative to that CSS file, and will take precedence over a path defined in your PostCSS configuration or in the Tailwind CLI.

请注意，如果你正在使用 postcss-import，你的 @import 语句需要放在 @config 之前，这样才能正常工作，因为 postcss-import 对遵循 CSS 规范非常严格，而规范要求 @import 语句必须在文件中的其他规则之前。

🌐 Note that if you’re using postcss-import, your @import statements need to come before @config for things to work correctly, as postcss-import is strict about following the CSS spec which requires @import statements to precede any other rules in the file.

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

@import "tailwindcss/base";
@import "./custom-base.css";
@import "tailwindcss/components";
@import "./custom-components.css";
@import "tailwindcss/utilities";

@import "tailwindcss/base";
@import "./custom-base.css";
@import "tailwindcss/components";
@import "./custom-components.css";
@import "tailwindcss/utilities";

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

​函数(Functions)

Tailwind 增加了一些自定义函数，你可以在 CSS 中使用它们来访问 Tailwind 特定的值。这些函数在构建时进行计算，并在最终的 CSS 中被替换为静态值。

🌐 Tailwind adds a few custom functions you can use in your CSS to access Tailwind-specific values. These functions are evaluated at build-time, and are replaced by static values in your final CSS.

​theme()

使用 theme() 函数通过点记法访问你的 Tailwind 配置值。

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

.content-area {
  height: calc(100vh - theme(spacing.12));
}

如果你需要访问包含点的值（例如间距刻度中的 2.5 值），你可以使用方括号表示法：

🌐 If you need to access a value that contains a dot (like the 2.5 value in the spacing scale), you can use square bracket notation:

.content-area {
  height: calc(100vh - theme(spacing[2.5]));
}

由于 Tailwind 使用 嵌套对象语法 来定义其默认颜色调色板，请确保使用点符号来访问嵌套颜色。

🌐 Since Tailwind uses a nested object syntax to define its default color palette, make sure to use dot notation to access the nested colors.

.btn-blue {
  background-color: theme(colors.blue-500);
}

.btn-blue {
  background-color: theme(colors.blue.500);
}

要调整使用 theme 获取的颜色的不透明度，请在后面加上斜杠，然后写上你想使用的不透明度值：

🌐 To adjust the opacity of a color retrieved with theme, use a slash followed by the opacity value you want to use:

.btn-blue {
  background-color: theme(colors.blue.500 / 75%);
}

​screen()

screen 函数允许你创建媒体查询，通过名称引用断点，而不是在自己的 CSS 中重复断点的数值。

🌐 The screen function allows you to create media queries that reference your breakpoints by name instead of duplicating their values in your own CSS.

@media screen(sm) {
  /* ... */
}

这将在构建时解析为基础的屏幕值，生成一个匹配指定断点的常规媒体查询：

🌐 This will resolve to the underlying screen value at build-time, generating a regular media query that matches specified breakpoint:

@media (min-width: 640px) {
  /* ... */
}