TailwindCSS 任意值语法如何使用？常见场景和坑有哪些？

TailwindCSS 的任意值语法（Arbitrary Values）适合处理“只出现一次、但默认工具类没有覆盖”的样式。核心写法是把具体值放进方括号里，比如 w-[372px]、text-[#1f2937]、mt-[18px]。这样不用临时写 CSS，也不用为了一个特殊尺寸去改 tailwind.config.js。

不过它不是“想写什么都往方括号里塞”。用得好，代码更快落地；用得乱，项目里会到处都是魔法值，后面维护很难受。

基本写法是什么？

html
<div class="w-[372px] bg-[#f5f5f5] text-[15px] p-[18px]"></div>

方括号里的内容会被 Tailwind 编译成对应 CSS。常见场景包括宽高、颜色、间距、字体、边框和布局。

宽高、颜色、间距和文本

html
<div class="w-[320px] h-[48px] max-w-[calc(100%-2rem)]"></div>
<button class="bg-[#1677ff] text-[#fff] border-[#d9d9d9]"></button>
<section class="mt-[18px] px-[22px] gap-[14px]"></section>
<p class="text-[13px] leading-[1.65] tracking-[0.02em]"></p>

calc() 可以放进去，不过表达式里不能随便写空格，通常写成 w-[calc(100%-2rem)]。如果值里有空格，Tailwind 会把下划线 _ 转成空格。

阴影和 Grid

html
<div class="border-[1.5px] rounded-[10px] shadow-[0_8px_30px_rgba(0,0,0,0.12)]"></div>
<div class="grid grid-cols-[minmax(180px,240px)_1fr]"></div>

像 box-shadow、grid-template-columns 这种本来就有空格的值，可以用 _ 代替空格。

CSS 变量怎么配合使用？

html
<div class="bg-[var(--card-bg)] text-[var(--text-primary)]"></div>
<div class="w-[calc(100%-var(--sidebar-width))]"></div>

如果项目里已经有设计 token，CSS 变量配合任意值会比硬编码更稳。比如主题切换、品牌换肤、暗色模式，都可以只改变量，不改 class。

类型提示是什么？

有些值 Tailwind 可能判断不出应该生成哪类 CSS。比如 CSS 变量既可能是颜色，也可能是长度：

html
<div class="text-[color:var(--brand-color)]"></div>
<div class="text-[length:var(--font-size-title)]"></div>
<div class="bg-[color:var(--brand-bg)]"></div>

类型提示的作用不是改变值，而是告诉 Tailwind：这个任意值应该生成哪一类工具样式。

任意属性和任意变体怎么写？

如果 Tailwind 没有对应工具类，可以用任意属性：

html
<div class="[mask-image:linear-gradient(to_bottom,black,transparent)]"></div>
<div class="[scrollbar-gutter:stable] [text-wrap:balance]"></div>

任意变体可以写自定义选择器：

html
<ul class="[&>li]:mb-[8px] [&>li:first-child]:font-bold"></ul>
<button class="[&:not(:disabled)]:hover:bg-[#1677ff]"></button>
<div class="[&_strong]:text-[#111] [&_a]:underline"></div>

& 表示当前元素，_ 会被当作空格。

伪元素和动画可以用任意值吗？

html
<span class="before:content-['New'] before:mr-[6px]"></span>
<span class="after:content-['Read_more']"></span>
<span data-label="Beta" class="before:content-[attr(data-label)]"></span>

伪元素内容适合小标签、装饰文本，不建议承载真正重要的正文内容。动画也可以写：

html
<div class="animate-[spin_1.5s_linear_infinite]"></div>
<div class="animate-[fade-in_300ms_ease-out_forwards]"></div>

但 animate-[fade-in...] 只是在使用某个 animation 声明，关键帧 @keyframes fade-in 仍然需要存在。常用动画最好写进 Tailwind 配置或全局 CSS。

JIT 和 content scanning 要注意什么？

Tailwind v3 以后 JIT 已经是默认机制，不需要再写旧版的 mode: 'jit'。v3+ 正常配置 content 即可：

js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx,vue,html}'],
  theme: { extend: {} }
}

Tailwind 只能识别静态、完整的 class 字符串。不要这样写：

jsx
<div className={`w-[${width}px]`}></div>

更稳的写法是提前列出完整 class，或对真正动态的值使用 style：

jsx
const widthClass = size === 'large' ? 'w-[320px]' : 'w-[240px]'
return <div className={widthClass}></div>

什么时候用任意值，什么时候写进配置？

适合用任意值的情况：一次性特殊尺寸、某个页面独有布局、临时活动页颜色、特殊 CSS 函数、新 CSS 属性。更适合写进主题配置的情况：品牌色、通用字号、圆角、阴影、多处复用的间距值、统一断点、常用动画。

如果同一个值出现三次以上，就考虑写进配置。任意值的价值，是让少量特殊样式留在 class 里快速表达；项目越大，越要克制：一次性值用方括号，稳定规范进配置，动态值交给 style 或 CSS 变量。