Обновление с Tailwind CSS v1.x до v2.0.
Tailwind CSS v2.0 - первая новая основная версия с момента выпуска v1.0 в мае 2019 года, и поэтому она включает несколько небольших критических изменений.
Мы не берем на отличия легко и упорно трудились, чтобы убедиться, что обновление путь как можно более простой. Для большинства проектов обновление занимает менее 30 минут.
Если в Вашем проекте используется плагин @tailwindcss/ui, обязательно прочтите также Tailwind UI для Tailwind CSS v2.0 руководство по обновлению.
Tailwind CSS v2.0 был обновлен для последней версии PostCSS, которая требует установки postcss и autoprefixer в качестве зависимостей между узлами вместе с самим Tailwind.
Обновите Tailwind и установите PostCSS и autoprefixer с помощью npm:
npm install tailwindcss@latest postcss@latest autoprefixer@latestЕсли у вас возникнут проблемы, возможно, вам придется использовать нашу сборку совместимости с PostCSS 7.
До версии 2.0 мы изо всех сил старались, чтобы функции, включенные в Tailwind, работали в IE 11, когда это возможно. Это добавило значительных затрат на обслуживание, а также увеличило размеры сборки (даже при удалении неиспользуемых стилей), поэтому мы решили отказаться от поддержки IE 11 начиная с версии 2.0.
Если вам нужна поддержка IE 11, мы рекомендуем продолжать использовать Tailwind CSS v1.9 до тех пор, пока вам больше не понадобится поддержка IE.
Tailwind CSS v2.0 больше не поддерживает Node.js 8 или 10. Чтобы создать свой CSS, вам необходимо убедиться, что вы используете Node.js 12.13.0 или выше как в локальной среде, так и в среде CI.
Если вы используете @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, вероятно, не будет использоваться.
В версии 2.0 было переименовано небольшое количество утилит:
| Старое имя | Новое имя |
|---|---|
whitespace-no-wrap | whitespace-nowrap |
flex-no-wrap | flex-nowrap |
col-gap-{n} | gap-x-{n} |
row-gap-{n} | gap-y-{n} |
Вы должны иметь возможность глобально находить и заменять эти классы во всем проекте очень безопасно, поскольку они представляют собой очень разные строки.
Обновление whitespace-no-wrap и flex-no-wrap- это просто прямая замена, а для утилит пробелов мы рекомендуем заменить col-gap- с gap-x- и row-gap- с gap-y- для обработки всех размеров сразу.
Варианты hover и focus были отключены для плагина fontWeight по умолчанию, так как изменение веса шрифта, как это, как правило, приводит к сбою макета, поэтому в любом случае это бывает редко.
Если они вам нужны в Вашем проекте, повторно включите их в файле 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-extralightfont-hairline на font-thinTailwind CSS v2.0 представляет новый набор утилит ring, которые позволяют добавлять контурные тени/кольца фокусировки таким образом, который автоматически совпадает с другими утилитами Tailwind box-shadow.
Это гораздо лучшая и более мощная альтернатива классам shadow-outline и shadow-xs, поэтому мы удалили эти классы.
Замените shadow-outline на ring:
- <div class="... focus:shadow-outline">
+ <div class="... focus:ring">Замените shadow-xs на ring-1 ring-black ring-opacity-5:
- <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.
Если вы используете цветовую палитру по умолчанию, вам следует явно настроить ее так, чтобы заменить новую палитру по умолчанию цветами, которые уже используются на Вашем сайте.
Вот пример файла 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',
},
}
}
}Мы не рекомендуем обновлять существующие сайты для использования новой цветовой палитры по умолчанию. Цифры не предназначены для передачи, поэтому, например, bg-red-600 в v2 - это не просто «лучшая» версия bg-red-600 от v1 - имеет разные контрастные характеристики. Если вам нравится, как выглядит ваш сайт, нет причин тратить часы своей жизни на обновление HTML. Старые цвета тоже отличные!
Если вы уже используете настраиваемую шкалу типографики, никаких изменений не требуется, и вы можете спокойно пропустить этот шаг.
В v2.0 каждая утилита font-size по умолчанию включает разумную высоту строки, зависящую от размера, поэтому, например, 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',
},
}
}В качестве альтернативы, вы можете просмотреть свой HTML и явно добавить leading в любом месте, где вы были, в зависимости от унаследованной высоты строки:
- <p class="text-lg">...</p>
+ <p class="text-lg leading-normal">...</p>В Tailwind CSS v1.x ключевое слово default в различных разделах theme раздела tailwind.config.js иногда означало «не добавляйте суффикс к имени класса».
Например, такая конфигурация:
// 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',
},
}
}Строчные default будут обрабатываться как любая другая строка, поэтому значение default в borderRadius будет генерировать класс rounded-default в Tailwind CSS v.2.0.
Вы должны обновить все использование default в Вашем конфигурационном файле на DEFAULT, за исключением, где вы действительно хотите сгенерировать класс {utility}-default, например, для cursor-default.
Ссылка полная конфигурация по умолчанию, чтобы узнать, где мы теперь используем DEFAULT, а где мы все еще используем default, если вы не знаете, какие изменения нужно внести в свою конфигурацию.
В Tailwind CSS v1.0 изменения темы в разделе extend были объединены неглубоко. Таким образом, эта конфигурация переопределит все фиолетовые цвета:
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
purple: {
light: '#E9D8FD',
medium: '#9F7AEA',
dark: '#553C9A',
}
}
}
}
}В версии 2.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 стала намного более мощной в версии 2.0, но для того, чтобы это стало возможным, необходимо изменить несколько вариантов поведения.
Раньше классы применялись в том порядке, в котором они появлялись в Вашем CSS:
/* Ввод */
.my-class {
@apply pt-5 p-4;
}
/* Вывод */
.my-class {
padding-top: 1.25rem;
padding: 1rem;
}Теперь классы применяются в том порядке, в котором они появляются в исходном CSS:
/* Ввод */
.my-class {
@apply pt-5 p-4;
}
/* Вывод */
.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, даже если вы настроили префикс.
Это больше не поддерживается в версии 2.0, поэтому, если у вас есть префикс (например, tw-), настроенный для Вашего сайта, вам нужно обязательно включать его всякий раз, когда вы используете @apply:
.my-class {
@apply tw-p-4 tw-bg-red-500;
}Раньше мы поддерживали запись операторов @apply с необязательным ведущим символом .:
.my-class {
@apply .p-4 .bg-red-500;
}Мы больше не поддерживаем это, поэтому обновите все операторы @apply и удалите точку:
.my-class {
@apply p-4 bg-red-500;
}Следующее регулярное выражение может быть полезно для поиска и удаления начальных точек в операторах @apply:
(?<=@apply.*)\.Утилита truncate теперь является частью основного плагина textOverflow, поэтому, если вы включили какие-либо дополнительные варианты (например, group-hover) для плагина wordBreak, чтобы использовать их с классом truncate, вы захотите включить их для textOverflow прямо сейчас или вместо этого:
// tailwind.config.js
module.exports = {
variants: {
wordBreak: ['responsive', 'group-hover'],
+ textOverflow: ['responsive', 'group-hover'],
}
}Поскольку 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 (в CSS, файл tailwind.config.js и в API плагина) более интеллектуальна в версии 2.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.
Раньше у нас было специальное правило для игнорирования элементов шаблона template при использовании утилит space-x/y и divide-x/y, в основном для того, чтобы облегчить жизнь пользователям 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 через ключ options, должны быть обновлено, чтобы соответствовать параметрам, представленным в PurgeCSS 3.0.
Например, если вы использовали whitelist, вы захотите обновить его до safelist:
// tailwind.config.js
module.exports = {
purge: {
content: [
// ...
],
options: {
- whitelist: ['my-class']
+ safelist: ['my-class']
}
}
}Если вы не использовали клавишу options, вам не нужно ничего делать.
В версии 1.0 Tailwind игнорировал параметр preserveHtmlElements, если вы использовали собственный экстрактор. Этот параметр теперь должным образом соблюдается в версии 2.0, поэтому, если вы хотите отключить его, вам нужно сделать это явно:
// tailwind.config.js
module.exports = {
purge: {
content: [
// ...
],
+ preserveHtmlElements: false,
options: {
defaultExtractor: () => {
// ...
}
}
}
}Если вы настроили префикс в файле tailwind.config.js, Tailwind v2.0 автоматически применит этот префикс к любым объявлениям ключевых кадров в Вашей theme.
Если вы ссылаетесь на какие-либо настроенные ключевые кадры в настраиваемом CSS, обязательно добавьте свой префикс:
.my-class {
- animation: spin 1s infinite;
+ animation: tw-spin 1s infinite;
}Это имеет значение только в том случае, если вы настроили префикс и вы ссылаетесь на настроенные ключевые кадры в пользовательских файлах CSS. Если это затронет более двух человек на всей планете, я буду просто поражен.