Tailwind CSS 升級(jí)指南

升級(jí)指南

從 v1.x 升級(jí)到 v2.0

Tailwind CSS v2.0 是自2019年5月發(fā)布 v1.0 以來的第一個(gè)新的主要版本，因此它包括一些小的不兼容性變更。

我們不會(huì)輕易作出不兼容性的變更，并努力確保升級(jí)路徑盡可能簡(jiǎn)單。對(duì)于大多數(shù)項(xiàng)目來說，升級(jí)應(yīng)該在30分鐘內(nèi)完成。

如果您的項(xiàng)目使用 ?@tailwindcss/ui? 插件，請(qǐng)務(wù)必閱讀 Tailwind UI for Tailwind CSS v2.0 升級(jí)指南。

安裝 Tailwind CSS v2.0 和 PostCSS 8

Tailwind CSS v2.0 已經(jīng)更新為最新的 PostCSS 版本，這需要安裝 ?postcss ?和 ?autoprefixer ?作為其依賴，同時(shí)安裝 Tailwind 本身。

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

npm install tailwindcss@latest postcss@latest autoprefixer@latest

如果您遇到問題，您可能需要使用我們的 PostCSS 7兼容性版本。

已取消對(duì)IE 11 的支持

在v2.0之前，我們盡力確保我們?cè)?nbsp;Tailwind 中包含的功能盡可能在 IE 11 中工作。這增加了相當(dāng)大的維護(hù)負(fù)擔(dān)，以及增加了構(gòu)建的大?。词乖谇謇砦词褂玫臉邮剑晕覀儧Q定從v2.0開始放棄對(duì)IE 11的支持。

如果您需要支持 IE 11，我們建議繼續(xù)使用 Tailwind CSS v1.9，直到您不再需要支持 IE。

升級(jí)到Node.js 12.13或更高版本

Tailwind CSS v2.0 不再支持 Node.js 8或10。要建立您的 CSS，您需要確保您在本地和 CI 環(huán)境中運(yùn)行 Node.js 12.13.0或更高版本。

更新排版和表單插件

如果您正在使用 ?@tailwindcss/typography?，您需要升級(jí)到 v0.3.0，它增加了 Tailwind CSS v2.0 的支持。

如果您正在使用 ?@tailwindcss/custom-forms?，您將需要遷移到 ?@tailwindcss/forms? 來取代它。

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

刪除未來和實(shí)驗(yàn)性的配置選項(xiàng)

從 v2.0 開始，就沒有 ?future ?或 ?experimental ?選項(xiàng)了，所以您可以從您的 tailwind.config.js 文件中刪除任何這樣的配置。

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

未來我們會(huì)繼續(xù)使用 ?experimental ?選項(xiàng)來實(shí)現(xiàn)新的功能想法，但 ?future ?可能不會(huì)使用該選項(xiàng)。

更新重命名的功能類

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

您應(yīng)該能夠在整個(gè)項(xiàng)目中非常安全地全局查找和替換這些類，因?yàn)樗鼈兪欠浅２煌淖址?/p>

更新 ?whitespace-no-wrap? 和 ?flex-no-wrap? 只是直接替換，對(duì)于 gap 功能類，我們建議將 ?col-gap-? 替換為 ?gap-x-?，將 ?row-gap-? 替換為 ?gap-y-?，以便一次性處理所有尺寸。

如果需要的話，為 fontWeight 啟用 hover 和 focus 功能。

fontWeight 插件的 ?hover ?和 ?focus ?變體已經(jīng)被默認(rèn)禁用，因?yàn)橄襁@樣改變字體重量往往會(huì)導(dǎo)致布局混亂，所以無(wú)論如何都不會(huì)真正這么做。

如果您在項(xiàng)目中需要這些，請(qǐng)?jiān)谀?nbsp;tailwind.config.js 文件中重新啟用它們：

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

用 flow-root 代替 clearfix

?clearfix ?類已被刪除，因?yàn)?nbsp;?flow-root? 是現(xiàn)代瀏覽器中相同問題的更簡(jiǎn)單解決方案。

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

更新 font-wight 類的 100 和 200 權(quán)重

在 Tailwind CSS v2.0中，100 和 200 字體權(quán)重的類名已經(jīng)改變。

由于 ?font-thin? 在 v1 和 v2 中出現(xiàn)的權(quán)重不同，我們建議按以下順序更新您的類：

1. 在全局范圍內(nèi)用 ?font-extralight? 替換 ?font-thin ?
2. 在全局范圍內(nèi)用 ?font-thin? 替換 ?font-hairline?

用 ring 功能類替換 shadow-outline 和 shadow-xs

Tailwind CSS v2.0 引入了一套新的 ?ring ?功能類，讓您以一種自動(dòng)與 Tailwind 的其他箱形陰影功能類相結(jié)合的方式添加輪廓陰影/焦點(diǎn)環(huán)。

這些都是比 ?shadow-outline? 和 ?shadow-xs? 類更好更強(qiáng)大的選擇，所以我們已經(jīng)刪除了這些類。

用 ?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)',
      }
    }
  }
}

顯式配置斷點(diǎn)

Tailwind CSS v2.0 添加了一個(gè)新的 ?2xl ?斷點(diǎn)，它將影響您使用 ?container ?類的任何情況。如果這對(duì)您有影響，請(qǐng)通過使用現(xiàn)有斷點(diǎn)覆蓋 ?screens ?來刪除 ?2xl ?斷點(diǎn)：

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

明確配置您的調(diào)色板

如果您已經(jīng)在使用自定義調(diào)色板，則無(wú)需更改，您可以安全地跳過此步驟。

Tailwind CSS v2.0 中的默認(rèn)調(diào)色板發(fā)生了很大變化，并且并非旨在替代 v1.0 中包含的調(diào)色板。

如果您使用的是默認(rèn)調(diào)色板，您應(yīng)該明確配置它以使用您的網(wǎng)站已經(jīng)使用的顏色覆蓋新的默認(rèn)調(diào)色板。

下面是一個(gè)包含v1版默認(rèn)顏色的 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',
      },
    }
  }
}

我們不建議更新現(xiàn)有網(wǎng)站以使用新的默認(rèn)調(diào)色板。這些數(shù)字并不意味著可以轉(zhuǎn)移，所以例如 v2 中的 bg-red-600 并不僅僅是 v1 中的 bg-red-600 的 “更好 “版本—它有不同的對(duì)比特性。如果您對(duì)您的網(wǎng)站的外觀很滿意，就沒有必要花上幾個(gè)小時(shí)來更新您的 HTML。舊的顏色也很好

顯式配置您的 font-size

如果您已經(jīng)使用了自定義的排版比例，則無(wú)需更改，您可以安全地跳過這一步。

在v2.0中，每個(gè)字體大小功能類默認(rèn)都包含一個(gè)合理的特定行高，例如 ?text-sm? 會(huì)自動(dòng)設(shè)置 ?1.25rem? 的行高。

如果您沒有在 ?font-size? 功能類旁明確添加 ?leading ?功能類，這將會(huì)改變您的網(wǎng)站在任何地方的外觀。

解決這個(gè)問題的最快方法是顯式配置您的 ?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，并在任何依賴?yán)^承行高的地方明確添加一個(gè) ?leading ?功能類。

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

更新默認(rèn)主題鍵為 DEFAULT

在Tailwind CSS v1.x中， tailwind.config.js的各個(gè)主題部分的 ?default ?關(guān)鍵字有時(shí)意味著 “不要給類名添加后綴”。

例如，這個(gè)配置：

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

會(huì)生成一個(gè) ?border-radius? 為 ?0.25rem? 的 ?rounded ?類，而不是一個(gè) ?rounded-default? 類。

在 Tailwind CSS v2.0 中，我們已經(jīng)更新了所有對(duì) ?default ?的特殊用法，改為大寫的 ?DEFAULT?。

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

小寫的 ?default ?會(huì)像其他字符串一樣被處理，所以在 ?borderRadius ?下的默認(rèn)值會(huì)在 Tailwind CSS v.2.0 中生成一個(gè)四舍五入的 ?default ?類，您應(yīng)該更新配置文件中所有 ?default ?的用法，除非您真的想生成一個(gè) ?{utility}-default? 類。

您應(yīng)該把配置文件中所有 ?default ?的用法都更新為 ?DEFAULT?，除非您真的想生成一個(gè) ?{utility}-default? 類，比如 ?cursor-default?。

如果您不清楚您自己的配置需要做哪些改變，請(qǐng)參考完整的 default 配置，看看我們現(xiàn)在在哪些地方使用了 ?DEFAULT?，哪些地方還在使用 ?default?。

特意將淺層擴(kuò)展移到頂層

在 Tailwind CSS v1.0 中，?extend ?下的主題變化被淺層次合并。所以這個(gè)配置會(huì)覆蓋所有的紫色。

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

在 v2.0 中，這些都是深度合并的，所以上面的配置仍然會(huì)生成默認(rèn)的紫色-100到紫色-900色調(diào)，此外還有自定義的紫色-淺色、紫色-中色和紫色-深色。

在大多數(shù)情況下，這很有用，但如果您是依靠淺層合并，您會(huì)希望將您的自定義移動(dòng)到頂層，并手動(dòng)合并其他頂層顏色。

const defaultTheme = require('tailwindcss/defaultTheme')

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

您可能不需要這樣做。

更新依賴類順序的 @apply 語(yǔ)句

在 v2.0 中，?@apply? 功能變得更加強(qiáng)大，但需要改變一些行為才能實(shí)現(xiàn)。

以前，類是按照它們?cè)?nbsp;CSS 中出現(xiàn)的順序來應(yīng)用的。

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

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

現(xiàn)在，類將按照它們?cè)谠?nbsp;CSS 中出現(xiàn)的順序被應(yīng)用。

/* 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>

如果您是依賴舊的行為，您可能會(huì)看到您的網(wǎng)站的渲染方式有一些差異。要解決這個(gè)問題，請(qǐng)使用多個(gè) ?@apply? 聲明。

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

這幾乎不會(huì)影響那些不會(huì)去做奇怪事情的人。

在任何 @apply 語(yǔ)句中添加您配置的前綴

在 Tailwind CSS v1.0 中，即使您配置了一個(gè)前綴，您也可以 @apply 無(wú)前綴的功能類。

這在 v2.0 中不再支持，所以如果您為您的網(wǎng)站配置了一個(gè)前綴（如 ?tw-? ），您需要確保在您使用 ?@apply? 時(shí)包含這個(gè)前綴。

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

刪除 @apply 語(yǔ)句中的前導(dǎo)點(diǎn)

我們?cè)?jīng)支持用可選的 ?.? 字符來編寫 ?@apply? 語(yǔ)句。

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

我們不再支持這個(gè)了，所以更新任何 ?@apply? 語(yǔ)句并刪除點(diǎn)。

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

以下正則表達(dá)式可用于查找和刪除 ?@apply? 語(yǔ)句中的前導(dǎo)點(diǎn)：

(?<=@apply.*)\.

在 textOverflow 下啟用任何 truncate variants

truncate 功能類現(xiàn)在是 textOverflow 核心插件的一部分，所以如果您為了使用 truncate 類而為 wordBreak 插件啟用了任何額外的變體（比如 group-hover），您現(xiàn)在也要為 textOverflow 啟用這些變體。

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

滾動(dòng)觸摸和自動(dòng)滾動(dòng)功能已移除

由于 iOS 13 不再支持 ?-webkit-overflow-scrolling? 屬性，我們已經(jīng)從 v2.0 中刪除了這兩個(gè)功能。

如果您仍然需要它們，因?yàn)槟跒槔习姹镜?nbsp;iOS 構(gòu)建一些東西，您可以自己將它們添加為自定義功能。

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

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

更新從數(shù)組中讀取的 theme 函數(shù)引用

在 v2.0 中，?theme ?功能（在 CSS、tailwind.config.js文件和插件 API 中）更加智能，不再需要您手動(dòng)加入數(shù)組或明確訪問第一個(gè)索引。

// 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'),
        }
      })
    })
  ]
}

如果出于任何原因您想訪問原始數(shù)據(jù)結(jié)構(gòu)，您可以使用 ?config? 函數(shù)來代替。

在空格或分割元素內(nèi)的任何模板標(biāo)簽中添加隱藏功能

我們?cè)?jīng)有一個(gè)特殊的規(guī)則，在使用 ?space-x/y? 和 ?divide-x/y? 功能類時(shí)忽略模板元素，主要是為了讓 Alpine.js 用戶更加方便。

我們已經(jīng)更新了工作方式，不再對(duì)模板元素進(jìn)行特殊處理，而是明確地忽略任何具有隱藏屬性的元素。

要更新您的代碼以適應(yīng)這一變化，只需在您的 ?template ?標(biāo)簽中添加 ?hidden ?即可：

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

更新清除選項(xiàng)以匹配 PurgeCSS 3.0

在內(nèi)部，我們已經(jīng)升級(jí)到了 PurgeCSS 3.0，所以您通過選項(xiàng)鍵傳遞到 PurgeCSS 的任何原始選項(xiàng)都需要更新，以匹配 PurgeCSS 3.0 中的選項(xiàng)。

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

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

如果您沒有使用 ?option ?鍵，您不需要做任何事情。

如果使用自定義的 PurgeCSS 提取器，則禁用 preserveHtmlElements

在 v1.0 中，如果您使用一個(gè)自定義的提取器，Tailwind 忽略了 ?preserveHtmlElements ?選項(xiàng)。這個(gè)選項(xiàng)現(xiàn)在在 v2.0 中得到了適當(dāng)?shù)淖鹬?，所以如果您想禁用它，您需要顯式地這樣做：

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

如有需要，請(qǐng)?jiān)谌魏?nbsp;keyframe 引用前加上前綴

如果您已經(jīng)在您的 ?tailwind.config.js? 文件中配置了一個(gè)前綴，Tailwind v2.0 將自動(dòng)應(yīng)用該前綴到您的主題中的任何 ?keyframes ?聲明。

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

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

這僅在您配置了前綴并且在自定義 CSS 文件中引用配置的關(guān)鍵幀時(shí)才重要。