「及時」模式:全新世代的 Tailwind CSS
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 upgrade guide


安裝 Tailwind CSS v2.0 以及 PostCSS 8

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

不再支援 IE 11

在 2.0 版本之前,我們努力的讓所有 Tailwind 的功能都能在 IE 11 上正常的使用。但這對我們來說,開發及維護上造成相當大的負擔,以及增加了打包之後的總體大小(即使清理了所有未使用的樣式),所以我們決定 2.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 裡使用。

移除了 future 以及 experimental 的設定選項

在 v2.0 版本中將不再提供 futureexperimental 選項,所以你可以從你的 tailwind.config.js 文件裡刪除有關任何這樣的設定:

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

未來我們有可能會繼續使用 experimental 選項來實現我們新的功能想法,但就不會繼續使用 future 這個選項。

功能性 class 的重新命名

在 v2.0 版本中,有一小部分的功能性 class 被重新命名:

舊的命名新的命名
whitespace-no-wrapwhitespace-nowrap
flex-no-wrapflex-nowrap
col-gap-{n}gap-x-{n}
row-gap-{n}gap-y-{n}

你應該可以在全域尋找到這些功能性 class 並且非常安全取代它們,因為它們是非常不同的文字。

更新 whitespace-no-wrapflex-no-wrap 可以直接的替換文字,但對於 gap 功能性的變更,我們建議你將 col-gap- 取代成 gap-x- 以及 row-gap- 取代成 gap-y- 以便你能一次處理所有的尺寸。

如果你有需要的話,請為了你的 fontWeight 開啟 hover 及 foucs

fontWeight 預設裡面,是沒有開啟 hoverfocus 的,因為隨意變更你的字體粗細,會容易使你的畫面變得奇怪,所以正常來說我們不會這樣使用。

但假如你需要的話,你還是可以在 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 字體粗細的功能名稱

在 Tailwind CSS v2.0 裡已經修改了 100200 字體粗細的功能名稱:

字體粗細舊命名新命名
100font-hairlinefont-thin
200font-thinfont-extralight

由於 font-thin 在 v1 和 v2 版本中有著不一樣的粗細, 我們建議你根據以下步驟來進行更新:

  1. 全域的搜尋 font-thin 並使用 font-extralight 取代它
  2. 全域的搜尋 font-hairline 並使用 font-thin 取代它

使用 ring 來取代 shadow-outline 和 shadow-xs

在 Tailwind CSS v2.0 有一個新的 ring 功能,能讓你與其它 Tailwind 的陰影功能相結合的方式來達到聚焦的新功能。

這些是比起 shadow-outlineshadow-xs 更加強大的功能,於此同時我們也刪除了 shadow-outlineshadow-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-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)',
      }
    }
  }
}

你可以調整你所需要的頁面斷點 (Breakpoint)

在 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>

在 theme 裡把 default 換成 DEFAULT

在 Tailwind CSS v1.x 中,default 這個關鍵字,被用在 tailwind.config.jstheme 的每一個預設大小,代表你不需要在後綴增加其他大小來調整。

打個比方,以下是 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-radius0.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 會被當成一般字串來看到,所以在 borderRadiusdefault 將會創造一個 rounded-default

你應該在你的設定文件中更新 default 讓他成為 DEFAULT,除非你真的需要 {utility}-default 這樣的功能,例如 cursor-default

如果你不清楚你的設定文件需要做哪些改變,請參考 default 完全攻略手冊 看看現在哪裡使用了 DEFAULT,還有哪些地方是使用 default

記得將 extend 移到上層

在 Tailwind CSS v1.0 中,themeextend 結構是會淺層合併的,因此下列的設定會覆蓋掉所有的紫色。

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

在 Tailwind CSS v2.0 中,結構是深層合併的,所以根據上面這個設定產生出預設的 purple-100purple-900 以及你新增的 purple-lightpurple-medium 以及 purple-dark 色調。

這在大部分的狀況是有用的,但如果你的顏色的結構是需要淺層合併的話,還是會有問題,所以你可能要自己手動修改你所新增的,將它往上跟預設的顏色合併在一起。

const defaultTheme = require('tailwindcss/defaultTheme')

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

你也可能不需要做這個調整。

更新加入 @apply 的 class 順序

@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;
}

這基本上不會影響一般的專案,除非有人拿他來幹很奇怪的事情。

請記得在每一個 @apply 加入你自己自訂前綴詞

在 Tailwind CSS v1.0 版本中,你可以 @apply 不帶有自訂前綴詞的功能 class。

在 v2.0 版本中不再支援這個方式, 如果你有自訂的前綴詞 (像是 tw-),你需要確保在使用 @apply 時有使用這個前綴詞。

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

請刪除在 @apply 中的所有前導小數點 (dot)

我們曾經支援在 @apply 裡,讓所有 class 加入前導 .

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

但是現在不再支援在 @apply 加入前導 .,所以請刪除你在 @apply 中所加入前導的 .

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

你可以利用這個正則表達式來快速找到所有 @apply 中所出現的前導 . 並且刪除它。

(?<=@apply.*)\.

在 textOverflow 底下打開 truncate 變化模式

truncate 現在已經是 textOverflow 的一部分核心,所以你可能為了使用 wordBreak 變化模式而打開的 (像是 group-hover) 因為他們裡面包含 truncate 功能性 class。現在你也需要為 textOverflow 而打開:

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

移除了 scrolling-touch 和 scrolling-auto

由於 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 在陣列內的讀取方式

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 功能來替代。

在任何一個有使用到 space 或 divide 元素 template 標籤新增 hidden

我們曾經有一個特別的規則,我們會在 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>

更新 purge 選項來搭配 PurgeCSS 3.0

因為我們已經更新了 PurgeCSS 3.0

如果你在設定檔中有使用到 PurgeCSS 的部分,你會需要更新 options 裡的設定。

打個比方,如果你有用到 whitelist 你必須要改成 safelist

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

如果你沒有用到 options,你不需要做任何的更新。

如果你有自訂 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 會自動將這些前綴詞加到你在 theme 所使用的 keyframes 之中。

但是如果你有任何自訂的 CSS 裡用到 keyframes,請記得加入你的自訂前綴詞:

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

這只會發生在你使用自訂前綴詞 並且 引用在自訂 CSS 中的 keyframes 時才會受影響,如果這會影響到這個星球上兩個人以上,我絕對會嚇死。