Tailwind CSS 升级指南

升级指南

从 v1.x 升级到 v2.0

Tailwind CSS v2.0 是自2019年5月发布 v1.0 以来的第一个新的主要版本，因此它包括一些小的不兼容性变更。

我们不会轻易作出不兼容性的变更，并努力确保升级路径尽可能简单。对于大多数项目来说，升级应该在30分钟内完成。

如果您的项目使用 ​@tailwindcss/ui​ 插件，请务必阅读 Tailwind UI for Tailwind CSS v2.0 升级指南。

安装 Tailwind CSS v2.0 和 PostCSS 8

Tailwind CSS v2.0 已经更新为最新的 PostCSS 版本，这需要安装 ​postcss ​和 ​autoprefixer ​作为其依赖，同时安装 Tailwind 本身。

更新 Tailwind 并使用 npm 安装 PostCSS 和 autoprefixer。

npm install tailwindcss@latest postcss@latest autoprefixer@latest

如果您遇到问题，您可能需要使用我们的 PostCSS 7兼容性版本。

已取消对IE 11 的支持

在v2.0之前，我们尽力确保我们在 Tailwind 中包含的功能尽可能在 IE 11 中工作。这增加了相当大的维护负担，以及增加了构建的大小（即使在清理未使用的样式），所以我们决定从v2.0开始放弃对IE 11的支持。

如果您需要支持 IE 11，我们建议继续使用 Tailwind CSS v1.9，直到您不再需要支持 IE。

升级到Node.js 12.13或更高版本

Tailwind CSS v2.0 不再支持 Node.js 8或10。要建立您的 CSS，您需要确保您在本地和 CI 环境中运行 Node.js 12.13.0或更高版本。

更新排版和表单插件

如果您正在使用 ​@tailwindcss/typography​，您需要升级到 v0.3.0，它增加了 Tailwind CSS v2.0 的支持。

如果您正在使用 ​@tailwindcss/custom-forms​，您将需要迁移到 ​@tailwindcss/forms​ 来取代它。

​@tailwindcss/custom-forms​ 插件与 Tailwind CSS v2.0不兼容。

删除未来和实验性的配置选项

从 v2.0 开始，就没有 ​future ​或 ​experimental ​选项了，所以您可以从您的 tailwind.config.js 文件中删除任何这样的配置。

  module.exports = {
   future: {
     defaultLineHeights: true,
     purgeLayersByDefault: true,
     removeDeprecatedGapUtilities: true,
   },
   experimental: {
       additionalBreakpoint: true,
       extendedFontSizeScale: true,
       extendedSpacingScale: true,
   },
    // ...
  }

未来我们会继续使用 ​experimental ​选项来实现新的功能想法，但 ​future ​可能不会使用该选项。

更新重命名的功能类

在 v2.0 中，有一小部分功能类被重新命名。

您应该能够在整个项目中非常安全地全局查找和替换这些类，因为它们是非常不同的字符串。

更新 ​whitespace-no-wrap​ 和 ​flex-no-wrap​ 只是直接替换，对于 gap 功能类，我们建议将 ​col-gap-​ 替换为 ​gap-x-​，将 ​row-gap-​ 替换为 ​gap-y-​，以便一次性处理所有尺寸。

如果需要的话，为 fontWeight 启用 hover 和 focus 功能。

fontWeight 插件的 ​hover ​和 ​focus ​变体已经被默认禁用，因为像这样改变字体重量往往会导致布局混乱，所以无论如何都不会真正这么做。

如果您在项目中需要这些，请在您的 tailwind.config.js 文件中重新启用它们：

  // tailwind.config.js
  module.exports = {
    variants: {
      extend: {
       fontWeight: ['hover', 'focus']
      }
    }
  }

用 flow-root 代替 clearfix

​clearfix ​类已被删除，因为 ​flow-root​ 是现代浏览器中相同问题的更简单解决方案。

 <div class="clearfix">
 <div class="flow-root">
    <img class="float-left" src="..." alt="..." />
    <p>Lorem ipsum...</p>
  </div>

更新 font-wight 类的 100 和 200 权重

在 Tailwind CSS v2.0中，100 和 200 字体权重的类名已经改变。

由于 ​font-thin​ 在 v1 和 v2 中出现的权重不同，我们建议按以下顺序更新您的类：

1. 在全局范围内用 ​font-extralight​ 替换 ​font-thin ​
2. 在全局范围内用 ​font-thin​ 替换 ​font-hairline​

用 ring 功能类替换 shadow-outline 和 shadow-xs

Tailwind CSS v2.0 引入了一套新的 ​ring ​功能类，让您以一种自动与 Tailwind 的其他箱形阴影功能类相结合的方式添加轮廓阴影/焦点环。

这些都是比 ​shadow-outline​ 和 ​shadow-xs​ 类更好更强大的选择，所以我们已经删除了这些类。

用 ​ring ​替换 ​shadow-outline​：

 <div class="... focus:shadow-outline">
 <div class="... focus:ring">

用 ​ring-1 ring-black ring-opacity-5​ 替换 ​shadow-xs​：

 <div class="... shadow-xs">
 <div class="... ring-1 ring-black ring-opacity-5">

另外，您也可以将 ​shadow-outline​ 和 ​shadow-xs​ 添加到您的配置文件中，而不影响您的 HTML。

module.exports = {
  theme: {
    extend: {
      boxShadow: {
        xs: '0 0 0 1px rgba(0, 0, 0, 0.05)',
        outline: '0 0 0 3px rgba(66, 153, 225, 0.5)',
      }
    }
  }
}

显式配置断点

Tailwind CSS v2.0 添加了一个新的 ​2xl ​断点，它将影响您使用 ​container ​类的任何情况。如果这对您有影响，请通过使用现有断点覆盖 ​screens ​来删除 ​2xl ​断点：

// tailwind.config.js
module.exports = {
  purge: [
  // ...
  ],
  theme: {
    screens: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
    }
    // ...
   },
  variants: {
    // ...
  }
}

明确配置您的调色板

如果您已经在使用自定义调色板，则无需更改，您可以安全地跳过此步骤。

Tailwind CSS v2.0 中的默认调色板发生了很大变化，并且并非旨在替代 v1.0 中包含的调色板。

如果您使用的是默认调色板，您应该明确配置它以使用您的网站已经使用的颜色覆盖新的默认调色板。

下面是一个包含v1版默认颜色的 tailwind.config.js 文件的例子：

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      transparent: 'transparent',
      current: 'currentColor',

      black: '#000',
      white: '#fff',

      gray: {
        100: '#f7fafc',
        200: '#edf2f7',
        300: '#e2e8f0',
        400: '#cbd5e0',
        500: '#a0aec0',
        600: '#718096',
        700: '#4a5568',
        800: '#2d3748',
        900: '#1a202c',
      },
      red: {
        100: '#fff5f5',
        200: '#fed7d7',
        300: '#feb2b2',
        400: '#fc8181',
        500: '#f56565',
        600: '#e53e3e',
        700: '#c53030',
        800: '#9b2c2c',
        900: '#742a2a',
      },
      orange: {
        100: '#fffaf0',
        200: '#feebc8',
        300: '#fbd38d',
        400: '#f6ad55',
        500: '#ed8936',
        600: '#dd6b20',
        700: '#c05621',
        800: '#9c4221',
        900: '#7b341e',
      },
      yellow: {
        100: '#fffff0',
        200: '#fefcbf',
        300: '#faf089',
        400: '#f6e05e',
        500: '#ecc94b',
        600: '#d69e2e',
        700: '#b7791f',
        800: '#975a16',
        900: '#744210',
      },
      green: {
        100: '#f0fff4',
        200: '#c6f6d5',
        300: '#9ae6b4',
        400: '#68d391',
        500: '#48bb78',
        600: '#38a169',
        700: '#2f855a',
        800: '#276749',
        900: '#22543d',
      },
      teal: {
        100: '#e6fffa',
        200: '#b2f5ea',
        300: '#81e6d9',
        400: '#4fd1c5',
        500: '#38b2ac',
        600: '#319795',
        700: '#2c7a7b',
        800: '#285e61',
        900: '#234e52',
      },
      blue: {
        100: '#ebf8ff',
        200: '#bee3f8',
        300: '#90cdf4',
        400: '#63b3ed',
        500: '#4299e1',
        600: '#3182ce',
        700: '#2b6cb0',
        800: '#2c5282',
        900: '#2a4365',
      },
      indigo: {
        100: '#ebf4ff',
        200: '#c3dafe',
        300: '#a3bffa',
        400: '#7f9cf5',
        500: '#667eea',
        600: '#5a67d8',
        700: '#4c51bf',
        800: '#434190',
        900: '#3c366b',
      },
      purple: {
        100: '#faf5ff',
        200: '#e9d8fd',
        300: '#d6bcfa',
        400: '#b794f4',
        500: '#9f7aea',
        600: '#805ad5',
        700: '#6b46c1',
        800: '#553c9a',
        900: '#44337a',
      },
      pink: {
        100: '#fff5f7',
        200: '#fed7e2',
        300: '#fbb6ce',
        400: '#f687b3',
        500: '#ed64a6',
        600: '#d53f8c',
        700: '#b83280',
        800: '#97266d',
        900: '#702459',
      },
    }
  }
}

我们不建议更新现有网站以使用新的默认调色板。这些数字并不意味着可以转移，所以例如 v2 中的 bg-red-600 并不仅仅是 v1 中的 bg-red-600 的 “更好 “版本—它有不同的对比特性。如果您对您的网站的外观很满意，就没有必要花上几个小时来更新您的 HTML。旧的颜色也很好

显式配置您的 font-size

如果您已经使用了自定义的排版比例，则无需更改，您可以安全地跳过这一步。

在v2.0中，每个字体大小功能类默认都包含一个合理的特定行高，例如 ​text-sm​ 会自动设置 ​1.25rem​ 的行高。

如果您没有在 ​font-size​ 功能类旁明确添加 ​leading ​功能类，这将会改变您的网站在任何地方的外观。

解决这个问题的最快方法是显式配置您的 ​font-size​ 比例，使用 v1 的比例：

// tailwind.config.js
module.exports = {
  theme: {
    fontSize: {
      xs: '0.75rem',
      sm: '0.875rem',
      base: '1rem',
      lg: '1.125rem',
      xl: '1.25rem',
      '2xl': '1.5rem',
      '3xl': '1.875rem',
      '4xl': '2.25rem',
      '5xl': '3rem',
      '6xl': '4rem',
    },
  }
}

另外，您也可以检查您的 HTML，并在任何依赖继承行高的地方明确添加一个 ​leading ​功能类。

 <p class="text-lg">...</p>
 <p class="text-lg leading-normal">...</p>

更新默认主题键为 DEFAULT

在Tailwind CSS v1.x中， tailwind.config.js的各个主题部分的 ​default ​关键字有时意味着 “不要给类名添加后缀”。

例如，这个配置：

// tailwind.config.js
module.exports = {
  theme: {
    borderRadius: {
      none: '0',
      sm: '0.125rem',
      default: '0.25rem',
      md: '0.375rem',
      lg: '0.5rem',
    },
  }
}

会生成一个 ​border-radius​ 为 ​0.25rem​ 的 ​rounded ​类，而不是一个 ​rounded-default​ 类。

在 Tailwind CSS v2.0 中，我们已经更新了所有对 ​default ​的特殊用法，改为大写的 ​DEFAULT​。

// tailwind.config.js
module.exports = {
  theme: {
    borderRadius: {
      none: '0',
      sm: '0.125rem',
      DEFAULT: '0.25rem',
      md: '0.375rem',
      lg: '0.5rem',
    },
  }
}

小写的 ​default ​会像其他字符串一样被处理，所以在 ​borderRadius ​下的默认值会在 Tailwind CSS v.2.0 中生成一个四舍五入的 ​default ​类，您应该更新配置文件中所有 ​default ​的用法，除非您真的想生成一个 ​{utility}-default​ 类。

您应该把配置文件中所有 ​default ​的用法都更新为 ​DEFAULT​，除非您真的想生成一个 ​{utility}-default​ 类，比如 ​cursor-default​。

如果您不清楚您自己的配置需要做哪些改变，请参考完整的 default 配置，看看我们现在在哪些地方使用了 ​DEFAULT​，哪些地方还在使用 ​default​。

特意将浅层扩展移到顶层

在 Tailwind CSS v1.0 中，​extend ​下的主题变化被浅层次合并。所以这个配置会覆盖所有的紫色。

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        purple: {
          light: '#E9D8FD',
          medium: '#9F7AEA',
          dark: '#553C9A',
        }
      }
    }
  }
}

在 v2.0 中，这些都是深度合并的，所以上面的配置仍然会生成默认的紫色-100到紫色-900色调，此外还有自定义的紫色-浅色、紫色-中色和紫色-深色。

在大多数情况下，这很有用，但如果您是依靠浅层合并，您会希望将您的自定义移动到顶层，并手动合并其他顶层颜色。

const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
  theme: {
    colors: {
      ...defaultTheme.colors,
      purple: {
        light: '#E9D8FD',
        medium: '#9F7AEA',
        dark: '#553C9A',
      }
    }
  }
}

您可能不需要这样做。

更新依赖类顺序的 @apply 语句

在 v2.0 中，​@apply​ 功能变得更加强大，但需要改变一些行为才能实现。

以前，类是按照它们在 CSS 中出现的顺序来应用的。

/* Input */
.my-class {
  @apply pt-5 p-4;
}

/* Output */
.my-class {
  padding-top: 1.25rem;
  padding: 1rem;
}

现在，类将按照它们在原始 CSS 中出现的顺序被应用。

/* Input */
.my-class {
  @apply pt-5 p-4;
}

/* Output */
.my-class {
  padding: 1rem;
  padding-top: 1.25rem;
}

这是为了确保行为与 HTML 中的行为一致。

<!-- Here `pt-5` still takes precedence even though it appears first. -->
<div class="pt-5 p-4">...</div>

如果您是依赖旧的行为，您可能会看到您的网站的渲染方式有一些差异。要解决这个问题，请使用多个 ​@apply​ 声明。

.my-class {
  @apply pt-5;
  @apply p-4;
}

这几乎不会影响那些不会去做奇怪事情的人。

在任何 @apply 语句中添加您配置的前缀

在 Tailwind CSS v1.0 中，即使您配置了一个前缀，您也可以 @apply 无前缀的功能类。

这在 v2.0 中不再支持，所以如果您为您的网站配置了一个前缀（如 ​tw-​ ），您需要确保在您使用 ​@apply​ 时包含这个前缀。

.my-class {
  @apply tw-p-4 tw-bg-red-500;
}

删除 @apply 语句中的前导点

我们曾经支持用可选的 ​.​ 字符来编写 ​@apply​ 语句。

.my-class {
  @apply .p-4 .bg-red-500;
}

我们不再支持这个了，所以更新任何 ​@apply​ 语句并删除点。

.my-class {
  @apply p-4 bg-red-500;
}

以下正则表达式可用于查找和删除 ​@apply​ 语句中的前导点：

(?<=@apply.*)\.

在 textOverflow 下启用任何 truncate variants

truncate 功能类现在是 textOverflow 核心插件的一部分，所以如果您为了使用 truncate 类而为 wordBreak 插件启用了任何额外的变体（比如 group-hover），您现在也要为 textOverflow 启用这些变体。

  // tailwind.config.js
  module.exports = {
    variants: {
      wordBreak: ['responsive', 'group-hover'],
     textOverflow: ['responsive', 'group-hover'],
    }
  }

滚动触摸和自动滚动功能已移除

由于 iOS 13 不再支持 ​-webkit-overflow-scrolling​ 属性，我们已经从 v2.0 中删除了这两个功能。

如果您仍然需要它们，因为您正在为老版本的 iOS 构建一些东西，您可以自己将它们添加为自定义功能。

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

@layer utilities {
  @responsive {
    .scrolling-touch {
      -webkit-overflow-scrolling: touch;
    }
    .scrolling-auto {
      -webkit-overflow-scrolling: auto;
    }
  }
}

更新从数组中读取的 theme 函数引用

在 v2.0 中，​theme ​功能（在 CSS、tailwind.config.js文件和插件 API 中）更加智能，不再需要您手动加入数组或明确访问第一个索引。

// tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  theme: {
    fontSize: {
      // ...
      xl: ['20px', { lineHeight: '28px' }]
    }
  },
  plugins: [
    plugin(({ addBase, theme }) => {
      addBase({
        h1: {
          // Before
          fontSize: theme('fontSize.xl')[0],
          fontFamily: theme('fontFamily.sans').join(','),

          // Now
          fontSize: theme('fontSize.xl'),
          fontFamily: theme('fontFamily.sans'),
        }
      })
    })
  ]
}

如果出于任何原因您想访问原始数据结构，您可以使用 ​config​ 函数来代替。

在空格或分割元素内的任何模板标签中添加隐藏功能

我们曾经有一个特殊的规则，在使用 ​space-x/y​ 和 ​divide-x/y​ 功能类时忽略模板元素，主要是为了让 Alpine.js 用户更加方便。

我们已经更新了工作方式，不再对模板元素进行特殊处理，而是明确地忽略任何具有隐藏属性的元素。

要更新您的代码以适应这一变化，只需在您的 ​template ​标签中添加 ​hidden ​即可：

  <div class="space-y-4">
   <template x-for="item in items">
   <template x-for="item in items" hidden>
      <!-- ... -->
    </template>
  </div>

更新清除选项以匹配 PurgeCSS 3.0

在内部，我们已经升级到了 PurgeCSS 3.0，所以您通过选项键传递到 PurgeCSS 的任何原始选项都需要更新，以匹配 PurgeCSS 3.0 中的选项。

例如，如果您使用的是 ​whitelist​，您就需要更新为 ​safelist​：

  // tailwind.config.js
  module.exports = {
    purge: {
      content: [
        // ...
      ],
      options: {
       whitelist: ['my-class']
       safelist: ['my-class']
      }
    }
  }

如果您没有使用 ​option ​键，您不需要做任何事情。

如果使用自定义的 PurgeCSS 提取器，则禁用 preserveHtmlElements

在 v1.0 中，如果您使用一个自定义的提取器，Tailwind 忽略了 ​preserveHtmlElements ​选项。这个选项现在在 v2.0 中得到了适当的尊重，所以如果您想禁用它，您需要显式地这样做：

  // tailwind.config.js
  module.exports = {
    purge: {
      content: [
        // ...
      ],
     preserveHtmlElements: false,
      options: {
        defaultExtractor: () => {
          // ...
        }
      }
    }
  }

如有需要，请在任何 keyframe 引用前加上前缀

如果您已经在您的 ​tailwind.config.js​ 文件中配置了一个前缀，Tailwind v2.0 将自动应用该前缀到您的主题中的任何 ​keyframes ​声明。

如果您在自定义 CSS 中引用任何配置的 keyframes，您需要确保添加您的前缀。

  .my-class {
   animation: spin 1s infinite;
   animation: tw-spin 1s infinite;
  }

这仅在您配置了前缀并且在自定义 CSS 文件中引用配置的关键帧时才重要。