Руководство по обновлению

Tailwind CSS v3.0 - это крупное обновление фреймворка с совершенно новым внутренним движком и, как таковое, включает небольшое количество критических изменений.

Мы очень серьезно относимся к стабильности и приложили все усилия, чтобы любые критические изменения были максимально безболезненными. Для большинства проектов обновление до Tailwind CSS v3.0 должно занять менее 30 минут.

Чтобы узнать больше о новых возможностях Tailwind CSS v3.0, прочитайте анонс Tailwind CSS v3.0 в нашем блоге.

Обновление пакетов

Обновите Tailwind, а также PostCSS и autoprefixer, используя npm:

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

Обратите внимание, что Tailwind CSS v3.0 требует PostCSS 8 и больше не поддерживает PostCSS 7. Если вы не можете выполнить обновление до PostCSS 8, мы рекомендуем использовать Tailwind CLI вместо установки Tailwind в качестве плагина PostCSS.

Если вы используете вложение в своем пользовательском CSS (в сочетании с плагином вложения PostCSS), вам также следует настроить плагин tailwindcss/nesting в вашей конфигурации PostCSS, чтобы гарантировать совместимость с Tailwind CSS v3.0.

Официальные плагины

Все наши собственные плагины были обновлены для совместимости с v3.0.

Если вы используете какой-либо из наших подключаемых модулей, не забудьте обновить их все до последней версии одновременно, чтобы избежать ошибок ограничения версии.

npm install -D tailwindcss@latest \
  @tailwindcss/typography@latest \
  @tailwindcss/forms@latest \
  @tailwindcss/aspect-ratio@latest \
  @tailwindcss/line-clamp@latest \
  postcss@latest \
  autoprefixer@latest

Play CDN

Для Tailwind CSS v3.0 построенная нами ранее CDN на основе CSS была заменена новой Play CDN, которая дает вам полную мощность нового движок прямо в браузере без этапа сборки.

Чтобы попробовать, добавьте этот тег <script> в свой <head>:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example</title>
    <script src="https://cdn.tailwindcss.com"></script>
  </head>
  <body>
    <!-- -->
  </body>
</html>

Play CDN предназначен только для целей разработки - компиляция собственной статической сборки CSS - гораздо лучший выбор для продакшена.

Переход на JIT-движок

Новый движок Just-in-Time, о котором мы объявили в марте, заменил классический движок в Tailwind CSS v3.0.

Новый движок генерирует стили, необходимые для вашего проекта, по запросу, и может потребовать некоторых небольших изменений в вашем проекте в зависимости от того, как вы настроили Tailwind.

Если вы уже выбрали mode: 'jit' в Tailwind CSS v2.x, вы можете безопасно удалить это из своей конфигурации в v3.0:

tailwind.config.js

module.exports = {
  mode: 'jit',
  // ...
}

Настроить источники контента

Поскольку Tailwind больше не использует PurgeCSS под капотом, мы переименовали параметр purge в content, чтобы лучше отразить его назначение:

tailwind.config.js

module.exports = {
  purge: [
  content: [
    // Example content paths...
    './public/**/*.html',
    './src/**/*.{js,jsx,ts,tsx,vue}',
  ],
  theme: {
    // ...
  }
  // ...
}

Если вы еще не использовали опцию purge в своем проекте, очень важно настроить пути к шаблонам сейчас, иначе ваш скомпилированный CSS будет пуст.

Поскольку мы больше не используем PurgeCSS под капотом, некоторые из расширенных параметров очистки были изменены. Дополнительную информацию о дополнительных параметрах смотрите в новой документации конфигурации содержимого.

Удалить конфигурацию темного режима

Функция темного режима теперь включена с использованием стратегии media по умолчанию, поэтому вы можете полностью удалить этот ключ из файла tailwind.config.js, если вы не используете стратегию class.

tailwind.config.js

module.exports = {
  darkMode: 'media',
  // ...
}

Вы также можете безопасно удалить этот ключ, если он в настоящее время установлен на false:

tailwind.config.js

module.exports = {
  darkMode: false,
  // ...
}

Удалить вариант конфигурации

В Tailwind CSS v3.0 каждый вариант автоматически доступен для каждой утилиты по умолчанию, поэтому вы можете удалить раздел variants из файла tailwind.config.js:

tailwind.config.js

module.exports = {
  // ...
  variants: {
    extend: {
      padding: ['hover'],
    }
  },
}

Замените @variants на @layer

Поскольку все варианты теперь включены по умолчанию, вам больше не нужно явно включать их для пользовательского CSS с помощью директив @variants или @responsive.

Вместо этого добавьте любой собственный CSS к соответствующему «макету» с помощью директивы @layer:

 @variants hover, focus {
 @layer utilities {
   .content-auto {
     content-visibility: auto;
   }
 }

Любой пользовательский CSS, добавленный к одному из слоев Tailwind, автоматически поддерживает варианты.

Смотрите документацию по добавлению пользовательских стилей с помощью CSS и @layer для получения дополнительной информации.

Автоматические преобразования и фильтры

В Tailwind CSS v3.0 утилиты преобразования и фильтрации, такие как scale-50 и brightness-75, вступят в силу автоматически без необходимости добавления классов transform, filter или backdrop-filter:

<div class="transform scale-50 filter grayscale backdrop-filter backdrop-blur-sm">
<div class="scale-50 grayscale backdrop-blur-sm">

Хотя нет никакого вреда в том, чтобы оставить их в вашем HTML, их можно безопасно удалить — за одним исключением. Если вы полагаетесь на transform для создания нового контекста стека, вы можете оставить его, иначе вы можете столкнуться с проблемами z-порядка. В качестве альтернативы замените его на relative или isolate, чтобы принудительно использовать новый контекст стека.

Новый синтаксис модификатора непрозрачности

В новом движке представлен новый синтаксис для изменения непрозрачности утилит цвета, на которые мы рекомендуем перейти с таких утилит, как bg-opacity-*:

<div class="bg-black bg-opacity-25">
<div class="bg-black/25">

Старый подход по-прежнему работает во всех случаях, за исключением использования утилиты border-opacity-* с классом border по умолчанию — в версии 3 вам нужно будет явно указать цвет границы:

<div class="border border-opacity-25">
<div class="border border-gray-200/25">

Все остальные ситуации ведут себя так же, поэтому, за исключением этого изменения, ваши проекты будут работать точно так же, как и раньше. Тем не менее, мы рекомендуем использовать новый синтаксис в будущем и планируем отключить такие утилиты, как border-opacity-* и bg-opacity-* по умолчанию в версии 4, хотя вы все равно сможете включить их при необходимости.

Этот новый синтаксис работает для всех утилит для работы с цветом, даже для тех, у которых раньше не было способа изменить непрозрачность, например from-red-500/75.

Изменения цветовой палитры

Tailwind CSS v3.0 теперь по умолчанию включает все цвета из расширенной цветовой палитры, включая ранее отключенные цвета, такие как голубой, розовый, фуксия и салатовый, а также все пять вариантов серого.

Удалены цветовые псевдонимы

В версии 2.0 несколько цветов по умолчанию были псевдонимами расширенных цветов:

v2 по умолчанию	v2 Расширенная
`green`	`emerald`
`yellow`	`amber`
`purple`	`violet`

В версии 3.0 эти цвета используют свои расширенные имена по умолчанию, поэтому то, что раньше называлось bg-green-500, теперь называется bg-emerald-500 и bg-green-500 теперь относится к зеленому цвету из расширенная палитра.

Если вы используете эти цвета в своем проекте, самый простой способ обновления - вернуть им их предыдущие имена в файле tailwind.config.js:

tailwind.config.js

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extend: {
      colors: {
        green: colors.emerald,
        yellow: colors.amber,
        purple: colors.violet,
      }
    },
  },
  // ...
}

Если вы уже используете индивидуальную цветовую палитру, это изменение на вас никак не повлияет.

Переименованы серые шкалы

В рамках включения всех расширенных цветов по умолчанию мы дали различным оттенкам серого более короткие однословные имена, чтобы сделать их более практичными в использовании и сделать их одновременное сосуществование менее неудобным.

v2 По умолчанию	v2 Расширенные	v3 Унифицированные
Нет данных	`blueGray`	`slate`
`gray`	`coolGray`	`gray`
Нет данных	`gray`	`zinc`
Нет данных	`trueGray`	`neutral`
Нет данных	`warmGray`	`stone`

Если вы ссылались на какой-либо из расширенных серых цветов, вам следует обновить свои ссылки на новые имена, например:

tailwind.config.js

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extend: {
      colors: {
        gray: colors.trueGray,
        gray: colors.neutral,
      }
    },
  },
  // ...
}

Если вы не ссылались ни на один из оттенков серого из расширенной цветовой палитры, это изменение не повлияет на вас вообще.

Изменения названия класса

Некоторые имена классов в Tailwind CSS v3.0 были изменены, чтобы избежать конфликтов имен, улучшить взаимодействие с разработчиками или сделать возможным поддержку новых функций.

Везде, где это возможно, мы сохранили старое имя, поэтому многие из этих изменений не являются критическими, но вам рекомендуется обновить имена классов.

overflow-clip/ellipsis

Эти проклятые разработчики браузеров добавили реальное свойство overflow: clip, поэтому использование overflow-clip для text-overflow: clip сейчас действительно плохая идея.

Мы переименовали overflow-clip в text-clip и переименовали overflow-ellipsis в text-ellipsis, чтобы избежать коллизии имен:

<div class="overflow-clip overflow-ellipsis">
<div class="text-clip text-ellipsis">

Крайне маловероятно, что это кого-то коснется, так как существует очень мало вариантов использования для text-clip, и он действительно включен только для завершения.

flex-grow/shrink

Мы добавили grow-* и shrink-* как псевдонимы для flex-grow-* и flex-shrink-*:

<div class="flex-grow-0 flex-shrink">
<div class="grow-0 shrink">

Старые имена классов всегда будут работать, но вам рекомендуется обновить их до новых.

outline-black/white

Поскольку браузеры, наконец, начинают учитывать радиус границы при рендеринге контуров, мы добавили отдельные утилиты для свойств outline-style, outline-color, outline-width и outline-offset.

Это означает, что outline-white и outline-black теперь устанавливают только контур цвета, тогда как в v2 они устанавливают цвет, ширину, стиль и смещение.

Если вы используете в своем проекте outline-white или outline-black, вы можете вернуть старые стили, добавив в свой проект следующий настраиваемый CSS:

@layer utilities {
  .outline-black {
    outline: 2px dotted black;
    outline-offset: 2px;
  }

  .outline-white {
    outline: 2px dotted white;
    outline-offset: 2px;
  }
}

Кроме того, вы можете обновить любое их использование в своем CSS с помощью следующих классов:

<div class="outline-black">
<div class="outline-black outline-2 outline-dotted outline-offset-2">

<div class="outline-white">
<div class="outline-white outline-2 outline-dotted outline-offset-2">

decoration-clone/slice

Мы добавили box-decoration-clone и box-decoration-slice в качестве псевдонимов для decoration-clone и decoration-slice, чтобы избежать путаницы со всеми новыми утилитами text-decoration, которые используют пространство имен decoration-:

<div class="decoration-clone"></div>
<div class="box-decoration-clone"></div>

<div class="decoration-slice"></div>
<div class="box-decoration-slice"></div>

Старые имена классов всегда будут работать, но вам рекомендуется обновить их до новых.

Прочие мелкие изменения

Tailwind CSS v3.0 требует нескольких других небольших критических изменений, которые вряд ли коснутся многих людей, но были здесь зафиксированы.

Разделитель не может быть тире

Символ тире (-) не может использоваться в качестве настраиваемого разделителя в версии 3.0 из-за неоднозначности синтаксического анализа, которую он вносит в движок.

Вместо этого вам придется переключиться на другой символ, например _:

tailwind.config.js

module.exports = {
  // ...
  separator: '-',
  separator: '_',
}

Префикс не может быть функцией

До Tailwind CSS v3.0 можно было определить префикс класса как функцию:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  prefix(selector) {
    // ...
  },
}

Это невозможно в новом движке, и нам пришлось удалить поддержку этой функции.

Вместо этого используйте статический префикс, который одинаков для каждого класса, который генерирует Tailwind:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  prefix: 'tw-',
}

Порядок модификаторов файлов изменен

Незначительное изменение с версии v3.0.0-alpha.2, где был введен модификатор file - если вы комбинируете его с другими модификаторами, такими как hover или focus, вам нужно будет изменить порядок модификаторов:

<input class="file:hover:bg-blue-600 ...">
<input class="hover:file:bg-blue-600 ...">

Дополнительные сведения смотрите в документации упорядочивание модификаторов в стеке.

Заливка и обводка с использованием цветовой палитры

Утилиты fill-* и stroke-* теперь по умолчанию отражают ваш ключ theme.colors. Это не критическое изменение, если вы не настроили свою цветовую палитру, но если вы это сделали, классы fill-current и stroke-current могут не работать, если в вашу цветовую палитру не включен current в вашу собственную цветовую палитру.

Добавьте current в свою пользовательскую цветовую палитру, чтобы решить эту проблему:

tailwind.config.js

module.exports = {
  // ...
  theme: {
    colors: {
      current: 'currentColor',
      // ...
    }
  }
}

Отрицательные значения удалены

Отрицательный префикс в таких утилитах, как -mx-4, теперь является первоклассной функцией Tailwind, а не чем-то, обусловленным вашей темой, поэтому вы можете добавить - перед любой утилитой, которая поддерживает отрицательные значения, и она будет работать

Отрицательные значения были удалены из темы по умолчанию, поэтому, если вы ссылались на них с помощью theme(), вы увидите ошибку при попытке скомпилировать свой CSS.

Используйте функцию calc() для обновления любого затронутого кода:

.my-class {
  top: theme('top.-4')
  top: calc(theme('top.4') * -1)
}

Должен присутствовать базовый слой

В Tailwind CSS v3.0 директива @tailwind base должна присутствовать для того, чтобы такие утилиты, как преобразования, фильтры и тени, работали должным образом.

Если вы ранее отключили базовые стили Tailwind, не включив эту директиву, вам следует добавить их обратно и вместо этого отключить preflight в конфигурации corePlugins:

main.css

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

tailwind.config.js

module.exports = {
  // ...
  corePlugins: {
    preflight: false,
  },
}

Это отключит глобальные базовые стили Tailwind, не затрагивая утилиты, которые для правильной работы полагаются на добавление собственных базовых стилей.

Был переименован слой Screens

Слой @tailwind screens был переименован в @tailwind variants:

main.css

 /* ... */
 @tailwind screens;
 @tailwind variants;

Я думаю, что вы с большей вероятностью подвергнетесь нападению акулы во время работы за своим столом, чем это изменение повлияет на вас.

На этой странице