tailwindcss-v4

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS v4.1 Core

Tailwind CSS v4.1 核心

Documentation

文档

theme.md - CSS theme variables, design tokens, customization
functions-and-directives.md - @utility, @variant, @theme, @apply
adding-custom-styles.md - Custom utilities and variants
detecting-classes-in-source-files.md - Content detection
upgrade-guide.md - Migration from v3 to v4

theme.md - CSS主题变量、设计令牌、自定义配置
functions-and-directives.md - @utility、@variant、@theme、@apply
adding-custom-styles.md - 自定义工具类与变体
detecting-classes-in-source-files.md - 源文件类名检测
upgrade-guide.md - v3 到 v4 迁移指南

Quick Reference - @theme Namespaces

快速参考 - @theme 命名空间

Namespace	Generated Utilities
`--color-*`	bg-, text-, border-, fill-
`--font-*`	font-*
`--text-*`	text-xs, text-sm, text-base, etc.
`--spacing-*`	p-, m-, gap-, w-, h-*
`--radius-*`	rounded-*
`--shadow-*`	shadow-*
`--breakpoint-*`	sm:, md:, lg:, xl:
`--animate-*`	animate-spin, animate-bounce, etc.
`--ease-*`	ease-in, ease-out, ease-in-out

命名空间	生成的工具类
`--color-*`	bg-, text-, border-, fill-
`--font-*`	font-*
`--text-*`	text-xs, text-sm, text-base, 等
`--spacing-*`	p-, m-, gap-, w-, h-*
`--radius-*`	rounded-*
`--shadow-*`	shadow-*
`--breakpoint-*`	sm:, md:, lg:, xl:
`--animate-*`	animate-spin, animate-bounce, 等
`--ease-*`	ease-in, ease-out, ease-in-out

Configuration CSS-first

CSS优先的配置方式

Before (v3)

旧版本（v3）

javascript

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: { brand: '#3B82F6' }
    }
  }
}

javascript

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: { brand: '#3B82F6' }
    }
  }
}

After (v4)

新版本（v4）

css

@import "tailwindcss";

@theme {
  --color-brand: #3B82F6;
}

css

@import "tailwindcss";

@theme {
  --color-brand: #3B82F6;
}

Directives v4

v4 指令

@utility - Create a utility

@utility - 创建自定义工具类

css

@utility tab-4 {
  tab-size: 4;
}
/* Usage: class="tab-4" */

css

@utility tab-4 {
  tab-size: 4;
}
/* 用法：class="tab-4" */

@variant - Conditional style

@variant - 条件样式

css

.card {
  @variant dark {
    background: #1a1a2e;
  }
}

css

.card {
  @variant dark {
    background: #1a1a2e;
  }
}

@custom-variant - New variant

@custom-variant - 新建变体

css

@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
/* Usage: dark:bg-gray-900 */

css

@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
/* 用法：dark:bg-gray-900 */

v3 → v4 Breaking Changes

v3 → v4 破坏性变更

Removed @tailwind directives

移除@tailwind系列指令

css

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

css

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

Renamed utilities

工具类重命名

v3	v4
`shadow-sm`	`shadow-xs`
`shadow`	`shadow-sm`
`rounded-sm`	`rounded-xs`
`rounded`	`rounded-sm`
`outline-none`	`outline-hidden`
`ring`	`ring-3`

v3	v4
`shadow-sm`	`shadow-xs`
`shadow`	`shadow-sm`
`rounded-sm`	`rounded-xs`
`rounded`	`rounded-sm`
`outline-none`	`outline-hidden`
`ring`	`ring-3`

Removed deprecated utilities

移除已废弃的工具类

```
bg-opacity-*
```
→ use
```
bg-black/50
```
```
text-opacity-*
```
→ use
```
text-black/50
```
```
flex-shrink-*
```
→ use
```
shrink-*
```
```
flex-grow-*
```
→ use
```
grow-*
```

```
bg-opacity-*
```
→ 改用
```
bg-black/50
```
```
text-opacity-*
```
→ 改用
```
text-black/50
```
```
flex-shrink-*
```
→ 改用
```
shrink-*
```
```
flex-grow-*
```
→ 改用
```
grow-*
```

Custom utilities syntax

自定义工具类语法

css

/* v3 */
@layer utilities {
  .tab-4 {
    tab-size: 4;
  }
}

/* v4 */
@utility tab-4 {
  tab-size: 4;
}

css

/* v3 */
@layer utilities {
  .tab-4 {
    tab-size: 4;
  }
}

/* v4 */
@utility tab-4 {
  tab-size: 4;
}

Variables in arbitrary values

任意值中的变量写法

html

<!-- v3 -->
<div class="bg-[--brand-color]"></div>

<!-- v4 -->
<div class="bg-(--brand-color)"></div>

html

<!-- v3 -->
<div class="bg-[--brand-color]"></div>

<!-- v4 -->
<div class="bg-(--brand-color)"></div>

Important modifier position

important修饰符位置

html

<!-- v3 -->
<div class="!bg-red-500">

<!-- v4 -->
<div class="bg-red-500!">

html

<!-- v3 -->
<div class="!bg-red-500">

<!-- v4 -->
<div class="bg-red-500!">

Upgrade Tool

升级工具

bash

npx @tailwindcss/upgrade

Requires Node.js 20+

bash

npx @tailwindcss/upgrade

需要Node.js 20及以上版本

Browser Support

浏览器支持

Safari 16.4+
Chrome 111+
Firefox 128+

Safari 16.4+
Chrome 111+
Firefox 128+

Installation

安装

bash

npm install -D tailwindcss @tailwindcss/postcss

bash

npm install -D tailwindcss @tailwindcss/postcss

or for Vite

Vite 项目使用

npm install -D @tailwindcss/vite

or for CLI

CLI 工具使用

npm install -D @tailwindcss/cli

undefined

npm install -D @tailwindcss/cli

undefined

Core API Functions

核心API函数

--alpha()

Adjust color opacity:

css

color: --alpha(var(--color-lime-300) / 50%);

调整颜色透明度：

css

color: --alpha(var(--color-lime-300) / 50%);

--spacing()

Generate spacing values:

css

margin: --spacing(4);

生成间距值：

css

margin: --spacing(4);

@apply

Inline utility classes:

css

.btn {
  @apply px-4 py-2 rounded-lg font-bold;
}

内联工具类：

css

.btn {
  @apply px-4 py-2 rounded-lg font-bold;
}

Key Resources

核心资源

Official Theme Variables Documentation
@theme Directive Syntax
Content Detection Configuration
Custom Variant Creation
Animation Keyframes Definition
CSS Variables Usage

官方主题变量文档
@theme指令语法
内容检测配置
自定义变体创建
动画关键帧定义
CSS变量使用