十四、Tailwind CSS——定制与扩展（v4 核心）

一、入口文件与配置思路v4 最大的变化是“配置进 CSS”不再必须维护tailwind.config.js。1. import “tailwindcss” 入口作用说明在项目主 CSS 文件顶部引入import tailwindcss;即可加载 Tailwind 的全部功能。/* 主样式文件例如 input.css */importtailwindcss;/* 这里可以继续写自定义样式 */2. CSS 优先配置的理念作用说明v4 推荐把主题、变体、工具类等都写在 CSS 里而不是 JS 配置中。这样配置更贴近 CSS 本身也更容易被构建工具处理。对比项v3JS 配置v4CSS 优先配置文件tailwind.config.js主 CSS 文件定义令牌theme.extendtheme定义插件pluginsplugin扫描范围content自动检测 source/* v4所有定制集中在 CSS */importtailwindcss;theme{--color-brand:#ff6600;}二、用 theme 定义设计令牌1. theme 基础用法作用说明theme用来定义设计令牌变量Tailwind 会根据命名自动生成对应的工具类。theme{/* 定义一个品牌色自动生成 bg-brand、text-brand 等 */--color-brand:#ff6600;}divclassbg-brand text-white使用自定义品牌色/div2. 常用令牌颜色、字体、间距、断点作用说明令牌的命名前缀决定了它生成哪类工具类。令牌前缀生成的工具类示例--color-*--color-bg-brand、text-brand--font-*--font-font-display--text-*--text-text-body--spacing单一值p-*、m-*、w-*等间距刻度--breakpoint-*--breakpoint-3xl:断点--animate-*--animate-animate-wiggle--shadow-*--shadow-shadow-softtheme{--color-brand:#ff6600;--font-display:Inter,sans-serif;--text-body:1rem;--spacing:0.25rem;/* 动态间距的基准1 0.25rem */--breakpoint-3xl:120rem;--shadow-soft:0 8px 24pxrgb(0 0 0 / 0.08);}divclassfont-display text-body bg-brand p-4 3xl:bg-black shadow-soft综合使用自定义令牌/div使用指南--spacing是 v4 的“动态间距”基准修改它即可整体缩放间距刻度p-4会自动变成4 * --spacing。三、theme 的变体1. theme inline作用说明theme inline不把变量输出到:root而是把值直接内联进生成的工具类适合变量引用其他变量、希望最终值被解析的场景。themeinline{--font-sans:var(--font-inter);}2. theme static作用说明theme static始终把变量输出到:root即使没有被任何工具类使用方便你在自定义 CSS 或 JS 中读取这些变量。themestatic{--color-brand:#ff6600;}3. 三者的区别用表格写法变量是否输出到:root工具类是否用var()引用适用场景theme仅输出用到的变量是常规设计令牌theme inline不输出否值直接内联变量引用变量、需要解析theme static全部输出无论是否使用是需要在 CSS/JS 中读取变量/* 默认用到的变量才输出 */theme{--color-brand:#ff6600;}四、自定义变体与工具类1. custom-variant作用说明custom-variant用来定义自定义变体最常见的是配置 class 方式的深色模式。/* 定义 dark 变体html 有 .dark 类时生效 */custom-variantdark(:where(.dark,.dark *));divclassbg-white dark:bg-black深色模式样式/div2. utility作用说明utility用来注册自定义工具类之后就能像内置类一样使用且支持响应式、状态变体。/* 定义一个简单工具类 */utilitytab-4{tab-size:4;}preclasstab-4缩进为 4 个空格/pre/* 功能型工具类带参数 */utilitycontent-*{content:--value(integer);}divclasscontent-3.../div五、插件与层级管理1. plugin 加载插件作用说明plugin直接在 CSS 中加载 Tailwind 插件。importtailwindcss;plugintailwindcss/typography;plugindaisyui;2. layer 管理层级作用说明layer把自定义样式放到正确的级联层级中。v4 的层级从低到高为theme、base、components、utilities。层级作用layer base基础样式如重置layer components组件类如.btnlayer utilities工具类优先级更高layercomponents{.btn{applyrounded-lg px-4 py-2;}}使用指南把可复用的组件样式放进layer components这样工具类可以覆盖它们保持可预期性。六、apply 复用样式1. apply 用法作用说明apply把一组工具类内联到自定义 CSS 中适合抽取重复样式同时保留工具类体系。layercomponents{.btn-primary{applyrounded-lg bg-blue-500 px-4 py-2 text-white transitionhover:bg-blue-600;}}buttonclassbtn-primary提交/button2. 注意事项与适用场景作用说明apply适合高频复用的按钮、卡片等不适合逻辑复杂或需要大量动态变化的样式。场景建议多处重复的按钮/卡片用apply抽成组件类简单一次性样式直接写工具类复杂、需 JS 控制的样式用组件库或普通 CSS避坑指南别过度用apply把一堆工具类堆成“伪组件”这会失去工具类的可读性同时apply生成的是静态 CSS无法享受按需生成的部分优势。七、兼容旧配置与扫描范围1. config 兼容 tailwind.config.js作用说明如果项目还依赖旧版 JS 配置如某些插件、safelist可用config指向它。importtailwindcss;config../tailwind.config.js;使用指南新建项目优先用 CSS 配置仅在确实需要 JS 配置能力时引入config。2. source 指定扫描范围作用说明v4 会自动检测源码文件source用来补充扫描范围、排除目录或加入内联内容。importtailwindcss;/* 额外扫描第三方组件库 */source../node_modules/my-company/ui-lib;/* 排除不需要扫描的目录 */sourcenot../node_modules;/* 把字符串加入扫描起到 safelist 作用 */sourceinline(bg-red-500);使用指南自动检测通常够用只有当类名来自扫描不到的依赖、或需要手动保底时才用source。