Tailwind CSS 指令与函数

Tailwind CSS 指令与函数学习笔记

一、总览

Tailwind CSS 的指令与函数分为两大类：

二、指令（Directives）

2.1@tailwind— 注入 Tailwind 各层样式

/* 必须的三行，通常放在主 CSS 文件顶部 */@tailwindbase;/* 注入 Preflight 重置 + base 层样式 */@tailwindcomponents;/* 注入 components 层样式 */@tailwindutilities;/* 注入 utilities 层样式 */

各层内容说明：

Tailwind v4 变化：v4 使用@import "tailwindcss"一行替代三行@tailwind。

/* Tailwind v4 */@import"tailwindcss";

2.2@layer— 声明样式所属层级

/* 将自定义样式归入 Tailwind 的层级体系 */@layerbase{html{-webkit-font-smoothing:antialiased;}:root{--color-primary:#2563eb;}}@layercomponents{.btn{@applyinline-flex items-center justify-center rounded-md px-4 py-2;}}@layerutilities{.text-balance{text-wrap:balance;}}

层级优先级规则：

@layer base < @layer components < @layer utilities < 无 @layer 的样式 最低 中 高 最高

关键要点：

• 同一层级内，后定义的规则覆盖先定义的
• 不在@layer中的样式优先级最高（可覆盖所有层级）
• 一个@layer可以出现多次，同名的层会自动合并

/* 分散定义，自动合并到同一层 */@layercomponents{.btn{/* ... */}}@layercomponents{.card{/* ... */}}/* 等价于在一个 @layer components 中定义 .btn 和 .card */

2.3@apply— 在 CSS 中使用工具类

将 Tailwind 工具类"内联"到自定义 CSS 规则中：

@layercomponents{.btn-primary{@applybg-blue-600 text-white rounded-md px-4 py-2 font-medium transition-colorshover:bg-blue-700focus-visible:ring-2focus-visible:ring-blue-500focus-visible:ring-offset-2disabled:opacity-50;}}

@apply支持的特性：

/* 支持变体修饰符 */.card{@applyrounded-lg bg-white shadow-sm;@applyhover:shadow-md;/* 伪类变体 */@applyfocus-visible:ring-2;/* 焦点变体 */@applydark:bg-gray-800;/* 暗色模式 */@applysm:text-baselg:text-lg;/* 响应式 */@applygroup-hover:scale-105;/* 群组变体 */}/* 支持重要修饰符 */.important-style{@apply!text-red-500 !font-bold;}

@apply不支持的场景：

/* ❌ 不能使用需要 DOM 上下文的变体 */.btn{@applypeer-disabled:opacity-50;/* peer 需要兄弟元素 */}/* ❌ 不能使用任意值中的模板语法 */.btn{@applytext-[var(--my-color)];/* 某些复杂任意值可能不工作 */}/* ❌ 不能 @apply 自身（循环引用） */.circular{@applycircular;/* 无限循环 */}

2.4@variants/@responsive/@screen（已废弃）

Tailwind v3+ 中这些指令已被变体修饰符取代，仅作了解。

/* ❌ 旧写法（v2 及之前） */@responsive{.card{padding:1rem;}}@variantshover,focus{.btn{opacity:0.8;}}@screenmd{.container{max-width:768px;}}/* ✅ 新写法（v3+）— 直接用变体前缀 */@layercomponents{.card{@applyp-4md:p-6;}.btn{@applyhover:opacity-80focus:opacity-80;}}

2.5@source— 控制内容扫描范围（v4）

/* Tailwind v4 新增：指定额外的扫描路径 */@source"../node_modules/my-ui-lib/**/*.js";/* 排除路径 */@source not"../node_modules/some-lib/**/*.js";

2.6@theme— 内联定义主题（v4）

/* Tailwind v4 新增：直接在 CSS 中定义主题 */@theme{--color-brand:#3b82f6;--font-display:"Cal Sans",sans-serif;--breakpoint-xs:475px;}

三、函数（Functions）

3.1theme()— 引用主题配置值

在 CSS 中动态获取tailwind.config.js中定义的主题值：

/* 基本用法：获取单层值 */.card{border-radius:theme('borderRadius.lg');/* 0.5rem */padding:theme('spacing.6');/* 1.5rem */color:theme('colors.gray.900');/* #111827 */font-size:theme('fontSize.xl');/* 1.25rem */box-shadow:theme('boxShadow.md');/* 0 4px 6px -1px ... */}/* 获取带行高的字体大小（返回完整对象值） */h1{font-size:theme('fontSize.2xl');/* 1.5rem */line-height:theme('lineHeight.2xl');/* 2rem *//* 注意：fontSize 的 theme() 只返回字号值，不含行高 */}

在@apply中不能使用theme()：

/* ❌ 错误 */.btn{@applytheme('colors.blue.500');/* @apply 只接受类名 */}/* ✅ 正确 — 用原生 CSS 属性 */.btn{background-color:theme('colors.blue.500');}

theme()支持点号路径：

/* 对应配置结构 */div{/* theme.extend.colors.brand.500 */color:theme('colors.brand.500');/* theme.extend.spacing.128 */width:theme('spacing.128');/* 嵌套路径用 . 连接 */border-color:theme('colors.gray.200');}

theme()带默认值：

/* 如果路径不存在，不会报错，返回空 *//* Tailwind 本身不直接支持 theme() 默认值语法 *//* 但可以用 CSS 自定义属性做 fallback */.card{/* 利用 CSS var 的 fallback */--my-radius:theme('borderRadius.xl');border-radius:var(--my-radius,0.5rem);}

3.2theme()在配置文件中的使用

在tailwind.config.js中，通过函数参数访问主题值：

module.exports={theme:{extend:{// 在 extend 中无法直接引用自身，需要用函数形式boxShadow:{'brand':(theme)=>`0 0 20px${theme('colors.brand.500')}40`,},},},// 插件中通过参数获取 theme 函数plugins:[plugin(function({addUtilities,theme}){addUtilities({'.text-gradient-brand':{backgroundImage:`linear-gradient(to right,${theme('colors.brand.500')},${theme('colors.purple.500')})`,WebkitBackgroundClip:'text',WebkitTextFillColor:'transparent',},});}),],};

3.3screen()— 响应式断点函数（v4）

/* Tailwind v4 新增：在 CSS 中使用断点 */@mediascreen(md){.container{max-width:768px;}}/* 等价于 */@media(min-width:768px){.container{max-width:768px;}}

四、指令与函数的完整速查

指令速查

函数速查

五、实战组合示例

5.1 完整 CSS 入口文件

/* ===== 1. 引入 Tailwind ===== */@tailwindbase;@tailwindcomponents;@tailwindutilities;/* ===== 2. Base 层：全局基础 ===== */@layerbase{html{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;scroll-behavior:smooth;}:root{--color-bg:theme('colors.white');--color-text:theme('colors.gray.900');--color-brand:theme('colors.blue.600');--header-h:theme('spacing.16');}.dark{--color-bg:theme('colors.gray.900');--color-text:theme('colors.gray.100');--color-brand:theme('colors.blue.400');}body{background-color:var(--color-bg);color:var(--color-text);}}/* ===== 3. Components 层：组件样式 ===== */@layercomponents{.btn{@applyinline-flex items-center justify-center rounded-md px-4 py-2 text-sm font-medium transition-colors duration-150focus-visible:outline-nonefocus-visible:ring-2disabled:pointer-events-nonedisabled:opacity-50;}.btn-primary{@applybtn bg-blue-600 text-whitehover:bg-blue-700focus-visible:ring-blue-500;}.btn-ghost{@applybtn bg-transparent text-gray-700hover:bg-gray-100focus-visible:ring-gray-500dark:text-gray-300dark:hover:bg-gray-800;}.card{border-radius:theme('borderRadius.xl');background-color:theme('colors.white');box-shadow:theme('boxShadow.sm');border:1px solidtheme('colors.gray.200');padding:theme('spacing.6');}.dark .card{background-color:theme('colors.gray.800');border-color:theme('colors.gray.700');}}/* ===== 4. Utilities 层：自定义工具类 ===== */@layerutilities{.text-balance{text-wrap:balance;}.scrollbar-hide{-ms-overflow-style:none;scrollbar-width:none;&::-webkit-scrollbar{display:none;}}.mask-fade-bottom{mask-image:linear-gradient(to bottom,black 60%,transparent 100%);}}

5.2 配合配置文件

// tailwind.config.jsconstplugin=require('tailwindcss/plugin');module.exports={content:['./src/**/*.{html,js,jsx,ts,tsx,vue}'],theme:{extend:{colors:{brand:{50:'#eff6ff',500:'#3b82f6',600:'#2563eb',700:'#1d4ed8',},},keyframes:{shimmer:{'100%':{transform:'translateX(100%)'},},},animation:{shimmer:'shimmer 2s infinite',},},},plugins:[plugin(function({addUtilities,theme}){// 使用 theme() 函数引用配置值addUtilities({'.glow-brand':{boxShadow:`0 0 20px${theme('colors.brand.500')}50`,},'.gradient-brand':{backgroundImage:`linear-gradient(135deg,${theme('colors.brand.500')},${theme('colors.purple.500')})`,},});}),],};

六、常见问题与陷阱

七、v3 → v4 迁移对照

v4 的核心变化：配置从 JS 迁移到 CSS，主题值自动暴露为 CSS 变量，减少了对theme()函数的依赖。