核心概念
在 Tailwind 项目中添加自定义样式的最佳实践。
在使用框架时，最大的挑战通常是弄清楚当框架无法满足某个需求时该怎么办。
Tailwind 从一开始就被设计为可扩展和可定制，无论你构建什么项目，都不会让你觉得你在与框架抗衡。
本指南涵盖了自定义设计令牌、在必要时打破这些限制、添加自定义 CSS 以及通过插件扩展框架等主题。
如果你想更改颜色调色板、间距比例、排版比例或断点，可以在 CSS 中使用 @theme 指令添加自定义设置：
@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); /* ... */}详细了解如何自定义主题，请参见 主题变量文档。
通常，你可以使用有限的设计令牌构建大部分精心制作的设计，但偶尔你需要打破这些限制，以实现像素完美的效果。
当你确实需要 top: 117px 来让背景图像恰好位于适当位置时，使用 Tailwind 的方括号表示法动态生成带有任意值的类：
<div class="top-[117px]"> <!-- ... --></div>这基本上像是内联样式，但主要的好处是你可以将其与交互式修饰符（如 hover）和响应式修饰符（如 lg）组合使用：
<div class="top-[117px] lg:top-[344px]"> <!-- ... --></div>这适用于框架中的所有内容，包括背景颜色、字体大小、伪元素内容等：
<div class="bg-[#bada55] text-[22px] before:content-['Festivus']"> <!-- ... --></div>如果你正在引用 CSS 变量作为任意值，可以使用自定义属性语法：
<div class="fill-(--my-brand-color) ..."> <!-- ... --></div>这只是 fill-[var(--my-brand-color)] 的简写，它会自动为你添加 var() 函数。
如果你需要使用 Tailwind 没有提供的 CSS 属性，可以使用方括号表示法编写完全任意的 CSS：
<div class="[mask-type:luminance]"> <!-- ... --></div>这 确实 类似于内联样式，但再次具有你可以使用修饰符的好处：
<div class="[mask-type:luminance] hover:[mask-type:alpha]"> <!-- ... --></div>这在 CSS 变量等内容中也很有用，尤其是在需要在不同条件下更改它们时：
<div class="[--scroll-offset:56px] lg:[--scroll-offset:44px]"> <!-- ... --></div>任意 变体 类似于任意值，但用于动态选择器修改，就像你可以使用内置的伪类变体（例如 hover:{utility}）或响应式变体（例如 md:{utility}）一样，但直接在 HTML 中使用方括号表示法。
<ul role="list"> {#each items as item} <li class="lg:[&:nth-child(-n+3)]:hover:underline">{item}</li> {/each}</ul>在 任意变体 文档中了解更多。
当任意值需要包含空格时，请改用下划线（_），Tailwind 会在构建时自动将其转换为空格：
<div class="grid grid-cols-[1fr_500px_2fr]"> <!-- ... --></div>在下划线常见但空格无效的情况下，Tailwind 会保留下划线而不是将其转换为空格，例如在 URLs 中：
<div class="bg-[url('/what_a_rush.png')]"> <!-- ... --></div>在极少数情况下，如果你确实需要使用下划线，但由于空格也是有效的而导致歧义，请用反斜杠转义下划线，Tailwind 不会将其转换为空格：
<div class="before:content-['hello\_world']"> <!-- ... --></div>如果你正在使用 JSX 等内容，反斜杠在渲染的 HTML 中被剥离，请使用 String.raw()，以便反斜杠不被视为 JavaScript 转义字符：
<div className={String.raw`before:content-['hello\_world']`}> <!-- ... --></div>Tailwind 中许多实用工具共享一个共同的命名空间，但映射到不同的 CSS 属性。例如，text-lg 和 text-black 都共享 text- 命名空间，但一个是用于 font-size，另一个是用于 color。
在使用任意值时，Tailwind 通常可以基于你传入的值自动处理这种歧义：
<!-- 将生成一个字体大小实用工具 --><div class="text-[22px]">...</div><!-- 将生成一个颜色实用工具 --><div class="text-[#bada55]">...</div>有时确实存在歧义，例如在使用 CSS 变量时：
<div class="text-(--my-var)">...</div>在这些情况下，你可以通过在值之前添加 CSS 数据类型 来“提示” Tailwind 基础类型：
<!-- 将生成一个字体大小实用工具 --><div class="text-(length:--my-var)">...</div><!-- 将生成一个颜色实用工具 --><div class="text-(color:--my-var)">...</div>虽然 Tailwind 设计用于处理大部分样式需求，但在需要时完全可以直接编写普通 CSS：
@import "tailwindcss";.my-custom-style { /* ... */}如果你想为页面设置一些默认值（如文本颜色、背景颜色或字体系列），最简单的选项就是向 html 或 body 元素添加一些类：
<!doctype html><html lang="en" class="bg-gray-100 font-serif text-gray-900"> <!-- ... --></html>这样可以将基础样式决策与所有其他样式一起保留在标记中，而不是将其隐藏在单独的文件中。
如果你想为特定 HTML 元素添加自己的默认基础样式，请使用 @layer 指令将这些样式添加到 Tailwind 的 base 层：
@layer base { h1 { font-size: var(--text-2xl); } h2 { font-size: var(--text-xl); }}对于任何你希望能够通过实用类覆盖的更复杂的类，请使用 components 层。
传统上，这些类如 card、btn、badge 等。
@layer components { .card { background-color: var(--color-white); border-radius: var(--rounded-lg); padding: var(--spacing-6); box-shadow: var(--shadow-xl); }}通过在 components 层中定义组件类，你仍然可以在必要时使用实用类覆盖它们：
<!-- 将看起来像一个卡片，但具有方角 --><div class="card rounded-none"> <!-- ... --></div>使用 Tailwind，你可能不需要这些类型的类，正如你想的那样。阅读我们的指南 管理重复 以获取我们的建议。
components 层也是放置你使用的任何第三方组件的自定义样式的好地方：
@layer components { .select2-dropdown { /* ... */ }}使用 @variant 指令在自定义 CSS 中应用 Tailwind 变体：
.my-element { background: white; @variant dark { background: black; }}.my-element { background: white; @media (prefers-color-scheme: dark) { background: black; }}如果你需要同时应用多个变体，请使用嵌套：
.my-element { background: white; @variant dark { @variant hover { background: black; } }}.my-element { background: white; @media (prefers-color-scheme: dark) { &:hover { @media (hover: hover) { background: black; } } }}除了使用 Tailwind 预置的实用类外，您还可以添加自己的自定义实用类。当某个 CSS 特性在 Tailwind 中没有内置实用类时，这非常有用。
使用 @utility 指令向项目添加自定义实用类：
@utility content-auto { content-visibility: auto;}现在你可以在 HTML 中使用这个实用类：
<div class="content-auto"> <!-- ... --></div>该实用类也会与 hover、focus 和 lg 等变体一起工作：
<div class="hover:content-auto"> <!-- ... --></div>自定义实用类会自动插入到与框架中所有内置实用类相同的 utilities 层中。
如果自定义实用类比单个类名更复杂，可以使用嵌套定义该实用类：
@utility scrollbar-hidden { &::-webkit-scrollbar { display: none; }}除了使用 @utility 指令注册简单实用类外，你还可以注册接受参数的功能实用类：
@utility tab-* { tab-size: --value(--tab-size-*);}特殊的 --value() 函数用于解析实用类值。
使用 --value(--theme-key-*) 语法在一组主题键中解析实用类值：
@theme { --tab-size-2: 2; --tab-size-4: 4; --tab-size-github: 8;}@utility tab-* { tab-size: --value(--tab-size-*);}这将匹配像 tab-2、tab-4 和 tab-github 的实用类。
要将值解析为原始值，使用 --value({type}) 语法，其中 {type} 是你想验证原始值的数据类型：
@utility tab-* { tab-size: --value(integer);}这将匹配像 tab-1 和 tab-76 的实用类。
要支持字面值，使用 --value('literal') 语法（注意引号）：
@utility tab-* { tab-size: --value('inherit', 'initial', 'unset');}这将匹配像 tab-inherit、tab-initial 和 tab-unset 这样的工具。
要支持任意值，使用 --value([{type}]) 语法（注意方括号）告诉 Tailwind 允许哪些类型作为任意值：
@utility tab-* { tab-size: --value([integer]);}这将匹配像 tab-[1] 和 tab-[76] 的实用类。如果你希望支持任何数据类型，可以使用 --value([*])。
三种形式的 --value() 函数都可以在一个规则中作为多个声明使用，任何无法解析的声明将在输出中省略：
@theme { --tab-size-github: 8;}@utility tab-* { tab-size: --value([integer]); tab-size: --value(integer); tab-size: --value(--tab-size-*);}这使得在必要时可以在每种情况下以不同的方式对待值，例如将原始整数转换为百分比：
@utility opacity-* { opacity: --value([percentage]); opacity: calc(--value(integer) * 1%); opacity: --value(--opacity-*);}--value() 函数还可以接受多个参数，并从左到右解析它们，如果你不需要在不同情况下以不同的方式对待返回值：
@theme { --tab-size-github: 8;}@utility tab-* { tab-size: --value(--tab-size-*, integer, [integer]);}@utility opacity-* { opacity: calc(--value(integer) * 1%); opacity: --value(--opacity-*, [percentage]);}要支持负值，请将正值和负值实用类分别注册到不同的声明中：
@utility inset-* { inset: calc(var(--spacing) * --value([percentage], [length]));}@utility -inset-* { inset: calc(var(--spacing) * --value([percentage], [length]) * -1);}修饰符使用 --modifier() 函数处理，该函数的工作方式与 --value() 函数完全相同，但操作的是修饰符（如果存在）：
@utility text-* { font-size: --value(--text-*, [length]); line-height: --modifier(--leading-*, [length], [*]);}如果修饰符不存在，任何依赖于修饰符的声明都不会包含在输出中。
为了处理分数，我们依赖于 CSS ratio 数据类型。如果与 --value() 一起使用，它会向 Tailwind 发出信号，表示值和修饰符将作为单个值处理：
@utility aspect-* { aspect-ratio: --value(--aspect-ratio-*, ratio, [ratio]);}这将匹配像 aspect-square、aspect-3/4 和 aspect-[7/9] 的实用类。
除了使用 Tailwind 预置的变体外，你还可以使用 @custom-variant 指令添加自己的自定义变体：
@custom-variant theme-midnight { &:where([data-theme="midnight"] *) { @slot; }}现在你可以在 HTML 中使用 theme-midnight:<utility> 变体：
<html data-theme="midnight"> <button class="theme-midnight:bg-black ..."></button></html>当不需要嵌套时，你可以使用简写语法创建变体：
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));当自定义变体具有多个规则时，可以嵌套在一起：
@custom-variant any-hover { @media (any-hover: hover) { &:hover { @slot; } }}