升级指南 - Tailwind CSS 中文

Tailwind CSS v3.0 是该框架的一个重大更新，它拥有全新的内部引擎，因此包括少量重大更改。

我们非常重视稳定性，并努力让任何重大更改尽可能地无痛。对于大多数项目，升级到 Tailwind CSS v3.0 应该不到 30 分钟。

要详细了解 Tailwind CSS v3.0 的新增功能，请阅读我们博客上的Tailwind CSS v3.0 公告。

升级包

使用 npm 更新 Tailwind 以及 PostCSS 和 autoprefixer

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

请注意，Tailwind CSS v3.0 需要 PostCSS 8，不再支持 PostCSS 7。如果你无法升级到 PostCSS 8，我们建议使用Tailwind CLI，而不是将 Tailwind 安装为 PostCSS 插件。

如果你在自定义 CSS 中使用嵌套（结合 PostCSS 嵌套插件），你应该还在你的 PostCSS 配置中配置 tailwindcss/nesting 插件，以确保与 Tailwind CSS v3.0 兼容。

官方插件

我们的所有第一方插件都已更新，以兼容 v3.0。

如果你正在使用我们的任何插件，请确保同时将它们全部更新到最新版本，以避免版本约束错误。

npm install -D tailwindcss@latest \
  @tailwindcss/typography@latest \
  @tailwindcss/forms@latest \
  @tailwindcss/aspect-ratio@latest \
  @tailwindcss/line-clamp@latest \
  postcss@latest \
  autoprefixer@latest

播放 CDN

对于 Tailwind CSS v3.0，我们过去提供的基于 CSS 的 CDN 构建已被新的 Play CDN 取代，它让你无需构建步骤即可直接在浏览器中充分利用新引擎。

要试用它，请将此 <script> 标签添加到你的 <head>

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example</title>
    <script src="https://cdn.tailwindcss.com"></script>
  </head>
  <body>
    <!-- -->
  </body>
</html>

Play CDN 仅设计用于开发目的——在生产中编译你自己的静态 CSS 构建是一个更好的选择。

迁移到 JIT 引擎

我们在 3 月份发布的新即时引擎已在 Tailwind CSS v3.0 中取代了经典引擎。

新引擎会按需生成项目所需样式，并且可能需要对项目进行一些小的更改，具体取决于你配置 Tailwind 的方式。

如果你已经在 Tailwind CSS v2.x 中选择加入 mode: 'jit'，则可以在 v3.0 中安全地从配置中将其删除

tailwind.config.js

module.exports = {
  mode: 'jit',
  // ...
}

配置内容源

由于 Tailwind 不再在底层使用 PurgeCSS，我们已将 purge 选项重命名为 content 以更好地反映其用途

tailwind.config.js

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

如果您尚未在项目中使用 purge 选项，那么现在配置模板路径至关重要，否则编译后的 CSS 将为空。

由于我们不再在后台使用 PurgeCSS，因此一些高级清除选项已发生更改。有关高级选项的更多信息，请参阅新的内容配置文档。

移除暗模式配置

现在默认情况下使用 media 策略启用暗模式功能，因此您可以从 tailwind.config.js 文件中完全删除此键，除非您正在使用 class 策略。

tailwind.config.js

module.exports = {
  darkMode: 'media',
  // ...
}

如果当前将其设置为 false，您也可以安全地删除此键

tailwind.config.js

module.exports = {
  darkMode: false,
  // ...
}

移除变体配置

在 Tailwind CSS v3.0 中，默认情况下每个变体都自动适用于每个实用程序，因此您可以从 tailwind.config.js 文件中删除 variants 部分

tailwind.config.js

module.exports = {
  // ...
  variants: {
    extend: {
      padding: ['hover'],
    }
  },
}

使用 @layer 替换 @variants

由于现在默认启用所有变体，因此您不再需要使用 @variants 或 @responsive 指令显式为自定义 CSS 启用这些变体。

相反，使用 @layer 指令将任何自定义 CSS 添加到适当的“层”

 @variants hover, focus {
 @layer utilities {
   .content-auto {
     content-visibility: auto;
   }
 }

添加到 Tailwind 的某个层中的任何自定义 CSS 都将自动支持变体。

有关使用 CSS 和 @layer 添加自定义样式的更多信息，请参阅添加自定义样式文档。

自动变换和滤镜

在 Tailwind CSS v3.0 中，变换和滤镜实用工具（如 scale-50 和 brightness-75）将自动生效，而无需添加 transform、filter 或 backdrop-filter 类

<div class="transform scale-50 filter grayscale backdrop-filter backdrop-blur-sm">
<div class="scale-50 grayscale backdrop-blur-sm">

虽然将它们留在 HTML 中并无害处，但可以安全地删除它们——除了一个例外。如果你依赖 transform 来创建新的堆叠上下文，你可能希望保留它，否则你可能会遇到 z 轴次序问题。或者，用 relative 或 isolate 替换它以强制执行新的堆叠上下文。

新的不透明度修改器语法

新引擎引入了一种新语法，用于更改颜色实用工具的不透明度，我们建议从 bg-opacity-{value} 等实用工具迁移到此语法

<div class="bg-black bg-opacity-25">
<div class="bg-black/25">

旧方法在所有情况下仍然有效，但当使用带有默认 border 类的 border-opacity-* 实用工具时除外——在 v3 中，你需要明确指定你的边框颜色

<div class="border border-opacity-25">
<div class="border border-gray-200/25">

其他所有情况的行为都相同，因此除了该更改之外，你的项目将完全按照之前的行为工作。不过，我们建议以后使用新语法，并计划在 v4 中默认禁用 border-opacity-* 和 bg-opacity-* 等实用工具，但你仍然可以在需要时启用它们。

这种新语法适用于所有颜色实用工具，即使是过去无法更改不透明度的实用工具，如 from-red-500/75。

调色板变更

默认情况下，Tailwind CSS v3.0 现在包含扩展调色板中的每种颜色，包括以前禁用的颜色，如青色、玫瑰色、紫红色和酸橙色，以及五种灰色变体。

移除颜色别名

在 v2.0 中，一些默认颜色实际上是扩展颜色的别名

v2 默认	v2 扩展
`绿色`	`祖母绿`
`黄色`	`琥珀色`
`紫色`	`紫罗兰色`

在 v3.0 中，这些颜色默认使用其扩展名称，因此以前为 bg-green-500 的现在为 bg-emerald-500，而 bg-green-500 现在指扩展调色板中的绿色。

如果您在项目中使用这些颜色，最简单的升级方法是在 tailwind.config.js 文件中将它们别名回其之前的名称

tailwind.config.js

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extend: {
      colors: {
        green: colors.emerald,
        yellow: colors.amber,
        purple: colors.violet,
      }
    },
  },
  // ...
}

如果您已经在使用自定义调色板，此更改完全不会影响您。

重命名灰色色阶

作为默认启用所有扩展颜色的部分，我们为不同的灰色色调赋予了更短的单字名称，以使其更实用，并且在同时存在时不那么别扭。

v2 默认	v2 扩展	v3 统一
N/A	`蓝灰色`	`石板色`
`灰色`	`冷灰色`	`灰色`
N/A	`灰色`	`锌色`
N/A	`真灰色`	`中性色`
N/A	`暖灰色`	`石头色`

如果您引用了任何扩展灰色，则应将引用更新为新名称，例如

tailwind.config.js

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extend: {
      colors: {
        gray: colors.trueGray,
        gray: colors.neutral,
      }
    },
  },
  // ...
}

如果您没有引用扩展调色板中的任何灰色，则此更改完全不会影响您。

类名更改

Tailwind CSS v3.0 中的一些类名已更改，以避免命名冲突、改善开发者体验或支持新功能。

在可能的情况下，我们保留了旧名称，因此其中许多更改不会中断，但我们建议您更新为新类名。

overflow-clip/省略号

那些该死的浏览器开发者添加了一个真正的 overflow: clip 属性，因此现在将 overflow-clip 用于 text-overflow: clip 是一个非常糟糕的主意。

我们已将 overflow-clip 重命名为 text-clip，并将 overflow-ellipsis 重命名为 text-ellipsis 以避免命名冲突

<div class="overflow-clip overflow-ellipsis">
<div class="text-clip text-ellipsis">

这极不可能影响任何人，因为 text-clip 的用例很少，而且它只是为了完整性而包含的。

flex-grow/shrink

我们已添加 grow-* 和 shrink-* 作为 flex-grow-* 和 flex-shrink-* 的别名

<div class="flex-grow-0 flex-shrink">
<div class="grow-0 shrink">

旧类名将始终有效，但我们建议您更新为新类名。

outline-black/white

由于浏览器终于开始在呈现轮廓时尊重边框半径，我们为 outline-style、outline-color、outline-width 和 outline-offset 属性添加了单独的实用工具。

这意味着 outline-white 和 outline-black 现在仅设置轮廓颜色，而在 v2 中，它们设置颜色、宽度、样式和偏移量。

如果您在项目中使用 outline-white 或 outline-black，可以通过将以下自定义 CSS 添加到项目中来恢复旧样式

@layer utilities {
  .outline-black {
    outline: 2px dotted black;
    outline-offset: 2px;
  }

  .outline-white {
    outline: 2px dotted white;
    outline-offset: 2px;
  }
}

或者，您可以使用以下类更新 CSS 中的任何用法

<div class="outline-black">
<div class="outline-black outline-2 outline-dotted outline-offset-2">

<div class="outline-white">
<div class="outline-white outline-2 outline-dotted outline-offset-2">

decoration-clone/slice

我们添加了 box-decoration-clone 和 box-decoration-slice 作为 decoration-clone 和 decoration-slice 的别名，以避免与所有使用 decoration- 命名空间的新 text-decoration 实用工具混淆

<div class="decoration-clone"></div>
<div class="box-decoration-clone"></div>

<div class="decoration-slice"></div>
<div class="box-decoration-slice"></div>

旧类名将始终有效，但我们建议您更新为新类名。

其他小改动

Tailwind CSS v3.0 需要一些其他小的破坏性更改，这些更改不太可能影响很多人，但已在此处记录。

分隔符不能是破折号

破折号 (-) 字符不能用作 v3.0 中的自定义分隔符，因为它会在引擎中引入解析歧义。

您必须改用其他字符，例如 _

tailwind.config.js

module.exports = {
  // ...
  separator: '-',
  separator: '_',
}

前缀不能是函数

在 Tailwind CSS v3.0 之前，可以将类前缀定义为函数

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  prefix(selector) {
    // ...
  },
}

新引擎中无法实现这一点，我们不得不移除对该功能的支持。

相反，使用静态前缀，该前缀对于 Tailwind 生成的每个类都是相同的

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  prefix: 'tw-',
}

文件修饰符顺序颠倒

自引入 file 修饰符的 v3.0.0-alpha.2 以来，超级小的更改 — 如果您将其与 hover 或 focus 等其他修饰符结合使用，则需要翻转修饰符顺序

<input class="file:hover:bg-blue-600 ...">
<input class="hover:file:bg-blue-600 ...">

在排序堆叠修饰符文档中了解更多信息。

填充和描边使用调色板

默认情况下，fill-{color} 和 stroke-{color} 实用程序现在会镜像您的 theme.colors 键。如果您尚未自定义调色板，则这不是重大更改，但如果您已经自定义，则如果您自己的自定义调色板中不包含 current，则 fill-current 和 stroke-current 类可能无法正常工作。

将 current 添加到自定义颜色调色板中以解决此问题

tailwind.config.js

module.exports = {
  // ...
  theme: {
    colors: {
      current: 'currentColor',
      // ...
    }
  }
}

已移除负值

现在，Tailwind 中的 -mx-4 等实用工具中的负前缀是一项一级特性，而不是由主题驱动的，因此您可以在支持负值的任何实用工具前添加 -，它就会起作用。

负值已从默认主题中移除，因此如果您使用 theme() 引用它们，则在尝试编译 CSS 时会看到错误。

使用 calc() 函数来更新受影响的代码

.my-class {
  top: theme('top.-4')
  top: calc(theme('top.4') * -1)
}

必须存在基础层

在 Tailwind CSS v3.0 中，必须存在 @tailwind base 指令，才能使变换、滤镜和阴影等实用工具按预期工作。

如果您之前通过不包含此指令来禁用 Tailwind 的基础样式，则应将其添加回来，而应在 corePlugins 配置中禁用 preflight

main.css

 @tailwind base;
 @tailwind components;
 @tailwind utilities;

tailwind.config.js

module.exports = {
  // ...
  corePlugins: {
    preflight: false,
  },
}

这将禁用 Tailwind 的全局基础样式，而不会影响依赖于添加自己的基础样式才能正常工作的实用工具。

屏幕层已重命名

@tailwind screens 层已重命名为 @tailwind variants

main.css

 /* ... */
 @tailwind screens;
 @tailwind variants;

我认为您在办公桌前被鲨鱼攻击的可能性比受到此更改影响的可能性更大。

在此页面上