入门
将您的 Tailwind CSS 项目从 v3 升级到 v4。
Tailwind CSS v4.0 是该框架的一个新的主要版本,因此,尽管我们非常努力地尽量减少破坏性更改,但仍然需要进行一些更新。本指南概述了将您的项目从 v3 升级到 v4 所需的所有步骤。
为了简化该过程,我们开发了一个迁移工具,可以自动处理典型项目中大部分的这些更改。
如果您想尝试将项目从 v3 升级到 v4,可以使用我们的升级工具为您完成绝大部分繁重的工作
$ npx @tailwindcss/upgrade@next
对于大多数项目,升级工具将自动化整个迁移过程,包括更新您的依赖项、将您的配置文件迁移到 CSS,以及处理对模板文件的任何更改。
升级工具需要 Node.js 20 或更高版本,因此请确保您的环境在运行之前已更新。
我们建议在新分支中运行升级工具,然后仔细检查差异并在浏览器中测试您的项目,以确保所有更改看起来都正确。在复杂的项目中,您可能需要手动调整一些内容,但无论如何,该工具都会为您节省大量时间。
最好还浏览一下 v4 中的所有破坏性更改,并很好地了解更改的内容,以防您需要在项目中更新升级工具未捕获的其他内容。
在 v3 中,tailwindcss
包是一个 PostCSS 插件,但在 v4 中,PostCSS 插件位于一个专用的 @tailwindcss/postcss
包中。
此外,在 v4 中,导入和供应商前缀现在会自动为您处理,因此如果您的项目中存在 postcss-import
和 autoprefixer
,则可以将其删除
export default { plugins: { "postcss-import": {}, tailwindcss: {}, autoprefixer: {}, "@tailwindcss/postcss": {}, },};
如果您正在使用 Vite,我们建议从 PostCSS 插件迁移到我们新的专用 Vite 插件,以提高性能并获得最佳的开发人员体验
import { defineConfig } from "vite";import tailwindcss from "@tailwindcss/vite";export default defineConfig({ plugins: [ tailwindcss(), ],});
在 v4 中,Tailwind CLI 位于一个专用的 @tailwindcss/cli
包中。更新您的任何构建命令以使用新的包
npx tailwindcss -i input.css -o output.cssnpx @tailwindcss/cli -i input.css -o output.css
以下是 Tailwind CSS v4.0 中所有破坏性更改的完整列表。
我们的 升级工具 将为您自动处理大多数这些更改,因此我们强烈建议您在可以的情况下使用它。
在 v4 中,您使用常规 CSS @import
语句导入 Tailwind,而不是使用您在 v3 中使用的 @tailwind
指令
@tailwind base;@tailwind components;@tailwind utilities;@import "tailwindcss";
我们移除了 v3 中已弃用且多年来未记录的任何实用程序。以下是已删除的内容以及现代替代方案的列表
已弃用 | 替代方案 |
---|---|
bg-opacity-* | 使用不透明度修饰符,如 bg-black/50 |
text-opacity-* | 使用不透明度修饰符,如 text-black/50 |
border-opacity-* | 使用不透明度修饰符,如 border-black/50 |
divide-opacity-* | 使用不透明度修饰符,如 divide-black/50 |
ring-opacity-* | 使用不透明度修饰符,如 ring-black/50 |
placeholder-opacity-* | 使用不透明度修饰符,如 placeholder-black/50 |
flex-shrink-* | shrink-* |
flex-grow-* | grow-* |
overflow-ellipsis | text-ellipsis |
decoration-slice | box-decoration-slice |
decoration-clone | box-decoration-clone |
我们在 v4 中重命名了以下实用程序,以使其更加一致和可预测
v3 | v4 |
---|---|
shadow-sm | shadow-xs |
shadow | shadow-sm |
drop-shadow-sm | drop-shadow-xs |
drop-shadow | drop-shadow-sm |
blur-sm | blur-xs |
blur | blur-sm |
rounded-sm | rounded-xs |
rounded | rounded-sm |
outline-none | outline-hidden |
ring | ring-3 |
我们重命名了默认的阴影、半径和模糊刻度,以确保每个实用程序都有一个命名值。“裸”版本仍然适用于向后兼容性,但是 <utility>-sm
实用程序的外观会有所不同,除非更新为其各自的 <utility>-xs
版本。
要为这些更改更新您的项目,请将所有 v3 实用程序替换为其 v4 版本
<input class="shadow-sm" /><input class="shadow-xs" /><input class="shadow" /><input class="shadow-sm" />
以前的 outline-none
实用程序实际上并未设置 outline-style: none
,而是设置了一个不可见的轮廓,出于可访问性原因,它仍然会在强制颜色模式下显示。
为了更清楚地说明这一点,我们将此实用程序重命名为 outline-hidden
,并添加了一个新的 outline-none
实用程序,该实用程序实际上设置了 outline-style: none
。
要为这项更改更新您的项目,请将所有 outline-none
的用法替换为 outline-hidden
<input class="focus:outline-none" /><input class="focus:outline-hidden" />
在 v3 中,ring
实用程序添加了一个 3px
的环。我们在 v4 中将其更改为 1px
,使其与边框和轮廓保持一致。
要更新您的项目以适应此更改,请将所有 ring
的用法替换为 ring-3
<input class="ring ring-blue-500" /><input class="ring-3 ring-blue-500" />
在 v3 中,container
实用程序有几个配置选项,如 center
和 padding
,这些在 v4 中已不再存在。
要在 v4 中自定义 container
实用程序,请使用 @utility
指令进行扩展
@utility container { margin-inline: auto; padding-inline: 2rem;}
我们在 v4 中对 Preflight 的基础样式进行了一些小的更改
在 v3 中,边框默认使用您配置的 gray-200
颜色。 我们在 v4 中将其更新为仅使用 currentColor
,这与所有浏览器的默认行为一致。
要更新您的项目以适应此更改,请确保您在使用 border
实用程序的任何地方都使用边框颜色实用程序,或者将以下 CSS 行添加到您的项目以保留 v3 的行为
@layer base { *, ::after, ::before, ::backdrop, ::file-selector-button { border-color: var(--color-gray-200, currentColor); }}
在 v3 中,占位符文本默认使用您配置的 gray-400
颜色。 我们在 v4 中将其简化为仅使用当前文本颜色,透明度为 50%。
您可能甚至不会注意到此更改(它甚至可能使您的项目看起来更好),但是如果您想保留 v3 的行为,请将此 CSS 添加到您的项目中
@layer base { input::placeholder, textarea::placeholder { color: theme(--color-gray-400); }}
在 v3 中,您在 @layer utilities
中定义的任何自定义类都会被 Tailwind 视为真正的实用程序类,并且会自动与 hover
、focus
或 lg
等变体一起使用。
在 v4 中,我们使用原生级联层,不再劫持 @layer
at-rule,因此我们引入了 @utility
API 作为替代
@layer utilities { .tab-4 { tab-size: 4; }}@utility tab-4 { tab-size: 4;}
在添加自定义实用程序文档中了解有关注册自定义实用程序的更多信息。
在 v3 中,堆叠的变体从右向左应用,但在 v4 中,我们已将其更新为从左向右应用,使其看起来更像 CSS 语法。
要更新您的项目以适应此更改,请反转项目中任何对顺序敏感的堆叠变体的顺序
<ul class="py-4 first:*:pt-0 last:*:pb-0"><ul class="py-4 *:first:pt-0 *:last:pb-0"> <li>One</li> <li>Two</li> <li>Three</li></ul>
您可能很少有这些(如果有的话)——直接子元素变体 (*
) 和任何排版插件变体 (prose-headings
) 是您最有可能使用的变体,即使这样也仅当您将它们与其他变体堆叠在一起时才会出现。
在 v3 中,您可以使用 CSS 变量作为任意值而无需 var()
,但最近 CSS 的更新意味着这通常可能模棱两可,因此我们在 v4 中更改了此语法以使用括号而不是方括号。
要更新您的项目以适应此更改,请使用新的变量简写语法替换旧的变量简写语法的用法
<div class="bg-[--brand-color]"></div><div class="bg-(--brand-color)"></div>
在 v4 中,我们已将 hover
变体更新为仅在主输入设备支持悬停时应用
@media (hover: hover) { .hover\:underline:hover { text-decoration: underline; }}
如果您以一种依赖于触摸设备在点击时触发悬停的方式构建了您的网站,这可能会产生问题。 如果这对您来说是一个问题,您可以使用您自己的使用旧实现的变体来覆盖 hover
变体
@custom-variant hover (&:hover);
但总的来说,我们建议将悬停功能视为增强功能,而不是依赖它来使您的网站正常工作,因为触摸设备实际上不具备悬停的能力。
在 v3 中,您可以使用 corePlugins
选项来完全禁用框架中的某些实用程序。 这在 v4 中不再支持。
由于 v4 为您的所有主题值都包含 CSS 变量,因此我们建议尽可能使用这些变量而不是 theme()
函数
.my-class { background-color: theme(colors.red.500); background-color: var(--color-red-500);}
对于您仍然需要使用 theme()
函数的情况(例如,在不支持 CSS 变量的媒体查询中),您应该使用 CSS 变量名称而不是旧的点表示法
@media (width >= theme(screens.xl)) {@media (width >= theme(--breakpoint-xl)) { /* ... */}
JavaScript 配置文件仍然支持向后兼容性,但在 v4 中不再自动检测到它们。
如果您仍然需要使用 JavaScript 配置文件,可以使用 @config
指令显式加载它
@config "../../tailwind.config.js";
在 v3 中,我们导出了一个 resolveConfig
函数,您可以使用该函数将基于 JavaScript 的配置转换为一个扁平对象,以便在您的其他 JavaScript 中使用。
我们已经在 v4 中删除了它,希望人们可以直接使用我们生成的 CSS 变量,这样更简单,并且可以显着减小您的包大小。
例如,流行的 React Motion 库允许您在 CSS 变量值之间进行动画处理
<motion.div animate={{ backgroundColor: "var(--color-blue-500)" }} />
如果您需要在 JS 中访问已解析的 CSS 变量值,您可以使用 getComputedStyle
获取文档根上主题变量的值
let styles = getComputedStyle(document.documentElement);let shadow = styles.getPropertyValue("--shadow-xl");