將你的 Tailwind CSS 從 v1.x 升級至 v2.0.
Tailwind CSS v2.0 是自從 2019 年 5 月發表 v1.0 以來，第一個新的主要版本，因此它會帶來一些與舊版本相容性上的小型變更。
我們沒有草率地做出相容性的重大變更，並且我們努力確保升級方式盡可能的相對簡單。對於大部分的專案而言，升級都能在 30 分鐘內完成。
如果你的專案有使用 @tailwindcss/ui 此擴充套件的話, 請務必閱讀此教學流程。Tailwind UI for Tailwind CSS v2.0 upgrade guide。
Tailwind CSS v2.0 已經將 PostCSS 更新至最新版本，所以在更新 Tailwind 的同時還需要安裝 postcss 以及 autoprefixer 作為 PostCSS 對應的依賴套件。
使用 npm 更新 Tailwind 以及安裝 PostCSS 和 autoprefixer：
npm install tailwindcss@latest postcss@latest autoprefixer@latest如果你在這裡遇到問題，你可能需要使用 PostCSS 7 相容性版本來取代。 PostCSS 7 compatibility build。
在 2.0 版本之前，我們努力的讓所有 Tailwind 的功能都能在 IE 11 上正常的使用。但這對我們來說，開發及維護上造成相當大的負擔，以及增加了打包之後的總體大小(即使清理了所有未使用的樣式)，所以我們決定 2.0 版本不再支援 IE 11。
如果你還是需要使用 IE 11，推薦你使用 Tailwind CSS v1.9 直到你可以完全脫離 IE 的魔爪再進行升級。
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 版本中，有一小部分的功能性 class 被重新命名：
| 舊的命名 | 新的命名 |
|---|---|
whitespace-no-wrap | whitespace-nowrap |
flex-no-wrap | flex-nowrap |
col-gap-{n} | gap-x-{n} |
row-gap-{n} | gap-y-{n} |
你應該可以在全域尋找到這些功能性 class 並且非常安全取代它們，因為它們是非常不同的文字。
更新 whitespace-no-wrap 和 flex-no-wrap 可以直接的替換文字，但對於 gap 功能性的變更，我們建議你將 col-gap- 取代成 gap-x- 以及 row-gap- 取代成 gap-y- 以便你能一次處理所有的尺寸。
在 fontWeight 預設裡面，是沒有開啟 hover 跟 focus 的，因為隨意變更你的字體粗細，會容易使你的畫面變得奇怪，所以正常來說我們不會這樣使用。
但假如你需要的話，你還是可以在 tailwind.config.js 這個檔案重新開啟它：
// tailwind.config.js
module.exports = {
variants: {
extend: {
+ fontWeight: ['hover', 'focus']
}
}
}clearfix 已經被移除了， 在現在的瀏覽器裡 flow-root 是一個能解決一樣的問題但更簡單使用的功能。
- <div class="clearfix">
+ <div class="flow-root">
<img class="float-left" src="..." alt="..." />
<p>Lorem ipsum...</p>
</div>在 Tailwind CSS v2.0 裡已經修改了 100 和 200 字體粗細的功能名稱：
| 字體粗細 | 舊命名 | 新命名 |
|---|---|---|
| 100 | font-hairline | font-thin |
| 200 | font-thin | font-extralight |
由於 font-thin 在 v1 和 v2 版本中有著不一樣的粗細， 我們建議你根據以下步驟來進行更新：
font-thin 並使用 font-extralight 取代它font-hairline 並使用 font-thin 取代它在 Tailwind CSS v2.0 有一個新的 ring 功能，能讓你與其它 Tailwind 的陰影功能相結合的方式來達到聚焦的新功能。
這些是比起 shadow-outline 和 shadow-xs 更加強大的功能，於此同時我們也刪除了 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 功能。如果這功能影響了你，請移除 2xl 這個頁面斷點，並將下列的 screens 覆寫到你已經擁有的螢幕斷點：
// tailwind.config.js
module.exports = {
purge: [
// ...
],
theme: {
+ screens: {
+ sm: '640px',
+ md: '768px',
+ lg: '1024px',
+ xl: '1280px',
+ }
// ...
},
variants: {
// ...
}
}如果你已經有自己的調色盤，可以放心地跳過這個步驟，不用做任何修改。
在 Tailwind CSS v2.0 中，我們修改了新的預設顏色，但並不是為了要取代 v1 版本中的配色。
如果你正在使用 v1 版本中的預設調色盤，那你應該將以下的預設顏色，覆蓋到你現在用的設定文件。
以下是 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',
},
}
}
}我們真的不建議現有的網站，直接使用新版的調色盤 所有的數字不代表可以直接轉移，打個比方 bg-red-600 在 v2 版本中，不單單只是 v1 版本上 bg-red-600 更好的版本，它也代表著不同的對比度，如果你現在的網站顏色很好看！你真的沒有理由花上幾個小時去修改你所有的配色。舊的顏色也很好看！
如果你已經有自己的字體大小，可以放心地跳過這個步驟，不用做任何修改
在 v2.0 版本中，字體大小都預設了字體行高，打個比方 text-sm 就自動的將行高設定成 1.25rem。
如果你沒有在字體大小旁邊增加 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',
},
}
}另外，你也可以在每個你有使用到行高 (line-height) 的部分，新增 leading 這項功能。
- <p class="text-lg">...</p>
+ <p class="text-lg leading-normal">...</p>在 Tailwind CSS v1.x 中，default 這個關鍵字，被用在 tailwind.config.js 裡 theme 的每一個預設大小，代表你不需要在後綴增加其他大小來調整。
打個比方，以下是 v1.x 的範例
// tailwind.config.js
module.exports = {
theme: {
borderRadius: {
none: '0',
sm: '0.125rem',
default: '0.25rem',
md: '0.375rem',
lg: '0.5rem',
},
}
}…這將會產生一個 rounded 的功能，並且它的 border-radius 為 0.25rem，並不是一個 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',
},
}
}在 Tailwind CSS v.2.0 中，小寫的 default 會被當成一般字串來看到，所以在 borderRadius 的 default 將會創造一個 rounded-default。
你應該在你的設定文件中更新 default 讓他成為 DEFAULT，除非你真的需要 {utility}-default 這樣的功能，例如 cursor-default。
如果你不清楚你的設定文件需要做哪些改變，請參考 default 完全攻略手冊 看看現在哪裡使用了 DEFAULT，還有哪些地方是使用 default 。
在 Tailwind CSS v1.0 中，theme 的 extend 結構是會淺層合併的，因此下列的設定會覆蓋掉所有的紫色。
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
purple: {
light: '#E9D8FD',
medium: '#9F7AEA',
dark: '#553C9A',
}
}
}
}
}在 Tailwind CSS v2.0 中，結構是深層合併的，所以根據上面這個設定產生出預設的 purple-100 到 purple-900 以及你新增的 purple-light、purple-medium 以及 purple-dark 色調。
這在大部分的狀況是有用的，但如果你的顏色的結構是需要淺層合併的話，還是會有問題，所以你可能要自己手動修改你所新增的，將它往上跟預設的顏色合併在一起。
const defaultTheme = require('tailwindcss/defaultTheme')
module.exports = {
theme: {
colors: {
...defaultTheme.colors,
purple: {
light: '#E9D8FD',
medium: '#9F7AEA',
dark: '#553C9A',
}
}
}
}你也可能不需要做這個調整。
@apply 在 v2.0 中，他變得更強了, 所以可能需要調整一下原本使用的方法。
以前, class 是照你在 CSS 裡面所寫的順序來出現的。
/* Input */
.my-class {
@apply pt-5 p-4;
}
/* Output */
.my-class {
padding-top: 1.25rem;
padding: 1rem;
}現在, class 會照它在原生 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;
}這基本上不會影響一般的專案，除非有人拿他來幹很奇怪的事情。
在 Tailwind CSS v1.0 版本中，你可以 @apply 不帶有自訂前綴詞的功能 class。
在 v2.0 版本中不再支援這個方式, 如果你有自訂的前綴詞 (像是 tw-)，你需要確保在使用 @apply 時有使用這個前綴詞。
.my-class {
@apply tw-p-4 tw-bg-red-500;
}我們曾經支援在 @apply 裡，讓所有 class 加入前導 .：
.my-class {
@apply .p-4 .bg-red-500;
}但是現在不再支援在 @apply 加入前導 .，所以請刪除你在 @apply 中所加入前導的 .：
.my-class {
@apply p-4 bg-red-500;
}你可以利用這個正則表達式來快速找到所有 @apply 中所出現的前導 . 並且刪除它。
(?<=@apply.*)\.truncate 現在已經是 textOverflow 的一部分核心，所以你可能為了使用 wordBreak 變化模式而打開的 (像是 group-hover) 因為他們裡面包含 truncate 功能性 class。現在你也需要為 textOverflow 而打開：
// tailwind.config.js
module.exports = {
variants: {
wordBreak: ['responsive', 'group-hover'],
+ textOverflow: ['responsive', 'group-hover'],
}
}由於 iOS 13 已經不支援 -webkit-overflow-scrolling 這個屬性，所以我們將這兩個功能從 v2.0 中移除。
如果你還是需要他們，就是那些會需要在舊版本的 iOS 上執行的專案，你可以在自訂的 utilities 上增加。
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer utilities {
@responsive {
.scrolling-touch {
-webkit-overflow-scrolling: touch;
}
.scrolling-auto {
-webkit-overflow-scrolling: auto;
}
}
}theme 功能在 v2.0 版本，讀取方式更聰明了，(在 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 功能來替代。
我們曾經有一個特別的規則，我們會在 template 忽略掉 space-x/y 以及 divide-x/y 功能，這樣的目的是為了方便 Alpine.js 的使用者。
我們已經更新了新的作業方式，不再對 template 做特殊處理，只是需要在有 hidden 屬性裡加入。
更新你的 code ，就在 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 的部分，你會需要更新 options 裡的設定。
打個比方，如果你有用到 whitelist 你必須要改成 safelist：
// tailwind.config.js
module.exports = {
purge: {
content: [
// ...
],
options: {
- whitelist: ['my-class']
+ safelist: ['my-class']
}
}
}如果你沒有用到 options，你不需要做任何的更新。
在 v1.0 版本裡，如果你使用了自訂的萃取器，Tailwind 會忽略 preserveHtmlElements 這個選項設定。現在這個選項在 v2.0 版本裡，不會再被忽略，只是你如果不需要，記得在選項裡取消。
// tailwind.config.js
module.exports = {
purge: {
content: [
// ...
],
+ preserveHtmlElements: false,
options: {
defaultExtractor: () => {
// ...
}
}
}
}如果你在 tailwind.config.js 裡有自訂前綴詞，Tailwind v2.0 會自動將這些前綴詞加到你在 theme 所使用的 keyframes 之中。
但是如果你有任何自訂的 CSS 裡用到 keyframes，請記得加入你的自訂前綴詞：
.my-class {
- animation: spin 1s infinite;
+ animation: tw-spin 1s infinite;
}這只會發生在你使用自訂前綴詞 並且 引用在自訂 CSS 中的 keyframes 時才會受影響，如果這會影響到這個星球上兩個人以上，我絕對會嚇死。