Tailwind CSS on GitHub

升级指南

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本身的对等依赖。.

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

npm install tailwindcss@latest postcss@latest autoprefixer@latest

如果你遇到问题,你可能需要阅读我们的PostCSS 7兼容版本

对ie11的支持已经被取消

在2.0版本之前,我们尽了最大努力确保我们在Tailwind CSS中包含的特性在IE 11中能够正常工作。这增加了相当大的维护负担,也增加了构建大小(甚至在清除未使用的样式时也是如此),所以我们决定从2.0版本开始放弃对ie11的支持。

如果你需要支持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不兼容。

删除未来和实验配置选项

在2.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会被重命名:

Old nameNew name
whitespace-no-wrapwhitespace-nowrap
flex-no-wrapflex-nowrap
col-gap-{n}gap-x-{n}
row-gap-{n}gap-y-{n}

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

更新whitespace-no-wrapflex-no-wrap只能直接替换一个类,至于gap类我们建议使用gap-x-来替换col-gap-以及使用gap-y-来替换row-gap-确保能替换所有的尺寸。

如果需要,为fontWeight启用hover和focus

hoverfocus已经被禁用于fontWeight,因为这样改变字重会导致布局混乱,所以通常不太会这样做。

如果你需要使用到,可以在配置文件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>

重命名字重100和200的类

字重100200的字重在Tailwind CSS v2.0中已经被重命名:

字重老的名字新的名字
100font-hairlinefont-thin
200font-thinfont-extralight

由于' font-thin '在v1和v2中都有不同的权重,我们建议按照以下顺序更新你的类:

  1. 全局查找以及替换font-thinfont-extralight
  2. 全局查找以及替换font-hairlinefont-thin

使用ring工具类来替换shadow-outline和shadow-xs

Tailwind CSS v2.0引入了一套新的ring工具类,让你可以添加shadows/focus轮廓,它将会跟其他的box-shadow类自动组合。

这是一个更好更强大的类,所以我们移除了shadow-outlineshadow-xs

替换shadow-outlinering:

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

替换shadow-xsring-1 ring-black ring-opacity-5:

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

或者,你也可以在配置文件中添加shadow-outlineshadow-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类。如果这影响到你的应用,用你现有的断点覆盖screen配置来删除2xl断点:

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

配置调色板

如果你已经在使用自定义调色板,则不需要进行任何更改,你可以安全地跳过此步骤。

默认调色板在Tailwind CSS v2.0中发生了相当大的变化,它的设计目的不是为了替代包含在v1中的调色板。.

如果你使用默认调色板,你应该显式的配置它,以覆盖新的默认调色板与你的网站已经使用的颜色。

下面的配置文件tailwind.config.js是展示如何配置v1默认调色板:

// 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,那么它将改变你的网站的外观。

解决这个问题的最快方法是明确地配置你的字体大小,像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中,theme下面的default字段意味着:"不添加前缀"。

比如这个配置:

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

...将会生成一个border-radius0.25remrounded类,而不是一个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下的default值会在Tailwind CSS v.2.0中生成一个round-default类。

你应该把配置文件中default的所有用法都更新为DEFAULT,除非你真正想生成{utility}-default类,就像cursor-default一样。

如果你不清楚需要对自己的配置做什么更改,参考完整的默认配置,看看我们现在在哪里使用DEFAULT,以及在哪里任然使用default

配置深度合并

在Tailwind CSS v1.0中,extend下的主题变化被浅合并。所以这个配置将覆盖所有的purple

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

在2.0版本中,配置项会被深度合并。除了自定义的purple-light purple-medium purple-dark,上面的配置仍然会生成默认的purple-100purple-900

在大多数情况下,这是很有用的,但如果你希望浅合并,并想让自定义颜色跟其他颜色一个层级:

const defaultTheme = require('tailwindcss/defaultTheme')

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

你也可能不需要这么做。

需要依赖类的顺序时,更新@apply语句

“@apply”特性在2.0版本中变得更加强大,但需要改变一些用法。

以前,类是按照它们在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中得到的行为相匹配:

<!-- 在这里`pt-5`任然起作用,即使它在第一位 -->
<div class="pt-5 p-4">...</div>

如果你依赖于旧的行为,你可能会看到站点呈现方式的一些差异。为了解决这个问题,可以使用多个' @apply '声明:

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

只要你不去做奇怪的操作,就不会影响到你。

将你配置的前缀添加到任何@apply语句中

在Tailwind CSS v1.0中,你可以@apply无前缀的工具类,即使你已经配置了一个前缀。

This is no longer supported in v2.0, so if you have a prefix (like tw-) configured for your site, you'll need to make sure you include that whenever you use @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工具现在是textOverflow核心插件的一部分,所以如果你已经为wordBreak插件启用了任何额外的变体(如group-hover),以便将它们与truncate类一起使用,那么你现在应该为textOverflow启用它们,或者改为:

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

scrolling-touch和scrolling-auto已经被删除

由于iOS 13不再支持-webkit-overflow-scrolling属性,我们从2.0版本中删除了这两个工具类。

如果你还需要它们,因为你正在为旧的iOS版本创建一些东西,你可以自己添加它们作为自定义工具:

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

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

更新theme方法读取数据的方式

theme方法(CSS中的、或者tailwind.config.js中的、或者插件API中的)在v2.0中更加智能,不再需要你手动拼接数组或者读取第一个索引。

// 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方法代替。

添加hidden到需要忽略的标签

在使用space-x/ydivide-x/y工具类时,我们曾经有一个忽略template元素的特殊规则,这主要是为了方便Alpine.js用户。

我们已经更新了它的工作方式,不再是特殊情况下的template元素,而只是显式地忽略任何有hidden属性的元素。

要更新你的代码,只需添加hidden到你的template标签:

  <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,所以你通过options键传入PurgeCSS的任何原始选项都需要更新,以匹配在PurgeCSS 3.0中暴露的选项

例如,如果你正在使用whitelist,你会想要更新到safelist:

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

如果你之前使用了options配置,你不需要做任何改变。

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

在1.0版中,如果使用自定义提取器,Tailwind会忽略preserveHtmlElements选项。这个选项现在在2.0版本中得到了适当的尊重,所以如果你想禁用它,你需要明确地这样做:

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

如果需要,为任何关键帧引用添加前缀

如果你已经在你的tailwind.config.config中配置了一个前缀。在你的theme中,Tailwind v2.0会自动将这个前缀应用到任何关键帧声明。

如果你在自定义CSS中引用任何配置的关键帧,你需要确保你添加了前缀:

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

只有当你配置了前缀并在自定义CSS文件中引用配置的关键帧时,这才有意义。正常来说这不会影响到地球上两个人以上的人。