Добавление пользовательских стилей

Чаще всего самой большой проблемой при работе с фреймворком является необходимость выполнения действий, которые фреймворк не обрабатывает.

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

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

Настройка вашей темы

Если вы хотите изменить такие вещи, как палитра цветов, шкала отступов, шкала типографики или точки разрыва, добавьте свои настройки в раздел theme файла tailwind.config.js.

module.exports = {
  theme: {
    screens: {
      sm: '480px',
      md: '768px',
      lg: '976px',
      xl: '1440px',
    },
    colors: {
      'blue': '#1fb6ff',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '128': '32rem',
        '144': '36rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

Дополнительную информацию о настройке темы вы найдёте в документации по Конфигурации темы.

Использование произвольных значений

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

Когда вам действительно нужно что-то вроде top: 117px, чтобы получить изображение фона в нужном месте, используйте квадратную нотацию Tailwind, чтобы сгенерировать класс на лету с любым произвольным значением:

<div class="top-[117px]">
  <!-- ... -->
</div>

Это в основном как встроенные стили, с существенным преимуществом, что вы можете комбинировать его с интерактивными модификаторами, такими как hover, и адаптивными модификаторами, такими как lg:

<div class="top-[117px] lg:top-[344px]">
  <!-- ... -->
</div>

Это работает для всего в фреймворке, включая такие вещи, как цвета фона, размеры шрифтов, содержимое псевдоэлементов и многое другое:

<div class="bg-[#bada55] text-[22px] before:content-['Festivus']">
  <!-- ... -->
</div>

Также можно использовать функцию theme для ссылки на значения дизайна в файле tailwind.config.js:

<div class="grid grid-cols-[fit-content(theme(spacing.32))]">
  <!-- ... -->
</div>

При использовании переменной CSS в качестве произвольного значения, использование var(...) не требуется — достаточно указать имя самой переменной:

<div class="bg-[--my-color]">
  <!-- ... -->
</div>

Произвольные свойства

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

<div class="[mask-type:luminance]">
  <!-- ... -->
</div>

Это действительно похоже на встроенные стили, но опять же с преимуществом использования модификаторов:

<div class="[mask-type:luminance] hover:[mask-type:alpha]">
  <!-- ... -->
</div>

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

<div class="[--scroll-offset:56px] lg:[--scroll-offset:44px]">
  <!-- ... -->
</div>

Произвольные варианты

Произвольные варианты похожи на произвольные значения, но для изменения селектора на лету, как вы можете с встроенными вариантами псевдоклассов, такими как hover:{utility} или адаптивными вариантами, такими как md:{utility}, но используя квадратную нотацию непосредственно в вашем HTML.

Дополнительную информацию можно найти в документации по произвольным вариантам.

Обработка пробелов

Когда произвольное значение должно содержать пробел, используйте символ подчёркивания (_) вместо него, и Tailwind автоматически преобразует его в пробел во время сборки:

<div class="grid grid-cols-[1fr_500px_2fr]">
  <!-- ... -->
</div>

В ситуациях, где подчёркивания используются часто, а пробелы недопустимы, Tailwind сохранит подчёркивание вместо преобразования его в пробел, например, в URL:

<div class="bg-[url('/what_a_rush.png')]">
  <!-- ... -->
</div>

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

<div class="before:content-['hello\_world']">
  <!-- ... -->
</div>

Если вы используете что-то вроде JSX, где обратная косая черта удаляется из рендерного HTML, используйте String.raw(), чтобы обратная косая черта не обрабатывалась как символ экранирования JavaScript:

<div className={String.raw`before:content-['hello\_world']`}>
  <!-- ... -->
</div>

Разрешение неоднозначностей

Многие утилиты в Tailwind используют общее пространство имён, но отображаются в разных свойствах CSS. Например, text-lg и text-black оба используют пространство имён text-, но одно предназначено для font-size, а другое — для color.

При использовании произвольных значений Tailwind обычно автоматически обрабатывает эту неоднозначность на основе переданного значения:

<!-- Will generate a font-size utility -->
<div class="text-[22px]">...</div>

<!-- Will generate a color utility -->
<div class="text-[#bada55]">...</div>

Иногда это действительно неоднозначно, например, при использовании переменных CSS:

<div class="text-[var(--my-var)]">...</div>

В таких ситуациях вы можете «подсказать» подлежащий тип Tailwind, добавив тип данных CSS перед значением:

<!-- Will generate a font-size utility -->
<div class="text-[length:var(--my-var)]">...</div>

<!-- Will generate a color utility -->
<div class="text-[color:var(--my-var)]">...</div>

Использование CSS и @layer

Когда вам нужно добавить действительно пользовательские правила CSS в проект Tailwind, самый простой способ — добавить пользовательский CSS в ваш стилевой файл:

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

.my-custom-style {
  /* ... */
}

Для большей гибкости вы также можете использовать директиву @layer для добавления стилей к слоям Tailwind base, components и utilities:

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

@layer components {
  .my-custom-style {
    /* ... */
  }
}

.btn {
  background: blue;
  /* ... */
}

.bg-black {
  background: black;
}

<button class="btn bg-black">...</button>
<button class="bg-black btn">...</button>

Директива @layer помогает контролировать порядок объявлений, автоматически перемещая ваши стили в соответствующую директиву @tailwind и также включает функции, такие как модификаторы и удаление неиспользуемого пользовательского CSS для вашего собственного пользовательского CSS.

Добавление базовых стилей

Если вы просто хотите установить некоторые значения по умолчанию для страницы (например, цвет текста, цвет фона или семейство шрифтов), самый простой способ — добавить несколько классов к элементам html или body:

<!doctype html>
<html lang="en" class="text-gray-900 bg-gray-100 font-serif">
  <!-- ... -->
</html>

Это позволяет хранить базовые решения по стилизации в вашем разметке вместе со всеми остальными стилями, а не скрывать их в отдельном файле.

Если вы хотите добавить свои собственные базовые стили по умолчанию для определённых элементов HTML, используйте директиву @layer для добавления этих стилей в слой base Tailwind:

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

@layer base {
  h1 {
    @apply text-2xl;
  }
  h2 {
    @apply text-xl;
  }
  /* ... */
}

Используйте функцию theme или директиву @apply при добавлении пользовательских базовых стилей, если вы хотите сослаться на любые значения, определённые в вашей теме.

Добавление классов компонентов

Используйте слой components для любых более сложных классов, которые вы хотите добавить в свой проект, которые вы по-прежнему хотели бы иметь возможность переопределять с помощью утилитарных классов.

Традиционно это были бы классы, такие как card, btn, badge — и тому подобное.

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

@layer components {
  .card {
    background-color: theme('colors.white');
    border-radius: theme('borderRadius.lg');
    padding: theme('spacing.6');
    box-shadow: theme('boxShadow.xl');
  }
  /* ... */
}

Определяя классы компонентов в слое components, вы по-прежнему можете использовать утилитарные классы для их переопределения при необходимости:

<!-- Will look like a card, but with square corners -->
<div class="card rounded-none">
  <!-- ... -->
</div>

Используя Tailwind, вам, вероятно, не понадобятся эти типы классов так часто, как вы думаете. Ознакомьтесь с нашим руководством по Переиспользованию стилей для получения рекомендаций.

Слой components также является хорошим местом для размещения пользовательских стилей для любых сторонних компонентов, которые вы используете:

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

@layer components {
  .select2-dropdown {
    @apply rounded-b-lg shadow-md;
  }
  .select2-search {
    @apply border border-gray-300 rounded;
  }
  .select2-results__group {
    @apply text-lg font-bold text-gray-900;
  }
  /* ... */
}

Используйте функцию theme или директиву @apply при добавлении пользовательских стилей компонентов, если вы хотите сослаться на любые значения, определённые в вашей теме.

Добавление пользовательских утилит

Добавьте все свои пользовательские утилитарные классы в слой utilities Tailwind:

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

@layer utilities {
  .content-auto {
    content-visibility: auto;
  }
}

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

Использование модификаторов с пользовательским CSS

Любые пользовательские стили, которые вы добавляете в Tailwind с помощью @layer будут автоматически поддерживать синтаксис модификаторов Tailwind для обработки таких вещей, как состояния наведения, адаптивные точки разрыва, тёмный режим и многое другое.

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

@layer utilities {
  .content-auto {
    content-visibility: auto;
  }
}

<div class="lg:dark:content-auto">
  <!-- ... -->
</div>

Дополнительную информацию о работе этих модификаторов вы найдете в документации по Состояниям наведения, фокуса и другим состояниям.

Удаление неиспользуемого пользовательского CSS

Любые пользовательские стили, которые вы добавляете в слои base, components или utilities, будут включены в скомпилированный CSS только в том случае, если эти стили фактически используются в вашем HTML.

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

@layer components {
  /* This won't be included in your compiled CSS unless you actually use it */
  .card {
    /* ... */
  }
}

Если вы хотите добавить некоторый пользовательский CSS, который должен всегда включаться, добавьте его в свой стилевой файл без использования директивы @layer:

@tailwind base;
@tailwind components;

/* This will always be included in your compiled CSS */
.card {
  /* ... */
}

@tailwind utilities;

Убедитесь, что ваши пользовательские стили расположены там, где нужно, чтобы получить желаемое поведение приоритетов. В приведенном выше примере мы добавили класс .card перед @tailwind utilities, чтобы убедиться, что утилиты по-прежнему могут его переопределять.

Использование нескольких файлов CSS

Если вы пишете много CSS и организуете его в несколько файлов, убедитесь, что эти файлы объединены в один стилевой файл перед обработкой их с помощью Tailwind, иначе вы увидите ошибки об использовании @layer без соответствующей директивы @tailwind.

Самый простой способ сделать это — использовать плагин postcss-import:

module.exports = {
  plugins: {
    'postcss-import': {},
    tailwindcss: {},
    autoprefixer: {},
  }
}

Узнайте больше в нашей документации по импортам на этапе сборки.

Слои и CSS на уровне компонентов

Компонентные фреймворки, такие как Vue и Svelte, поддерживают добавление стилей на уровне компонентов внутри блока <style>, который находится в каждом файле компонента.

Хотя вы можете использовать такие функции, как @apply и theme внутри стилей компонентов, такая как эта, директива @layer не будет работать, и вы увидите ошибку об использовании @layer без соответствующей директивы @tailwind.

<div>
  <slot></slot>
</div>

<style>
  /* Won't work because this file is processed in isolation */
  @layer components {
    div {
      background-color: theme('colors.white');
      border-radius: theme('borderRadius.lg');
      padding: theme('spacing.6');
      box-shadow: theme('boxShadow.xl');
    }
  }
</style>

Это связано с тем, что под капотом такие фреймворки, как Vue и Svelte, обрабатывают каждый блок <style> независимо и запускают вашу цепочку плагинов PostCSS для каждого из них изолированно.

Это означает, что если у вас есть 10 компонентов, каждый из которых содержит блок <style>, Tailwind выполняется 10 отдельных раз, и каждый запуск не имеет никакого знания об остальных запусках. Из-за этого Tailwind не может взять стили, которые вы определяете в блоке @layer, и перенести их в соответствующую директиву @tailwind, поскольку, насколько Tailwind может судить, нет директивы @tailwind для перемещения стилей.

Одним из решений является простое не использование @layer внутри стилей ваших компонентов:

<div>
  <slot></slot>
</div>

<style>
  div {
    background-color: theme('colors.white');
    border-radius: theme('borderRadius.lg');
    padding: theme('spacing.6');
    box-shadow: theme('boxShadow.xl');
  }
</style>

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

Мы рекомендуем просто не использовать стили компонентов таким образом, а вместо этого использовать Tailwind так, как это предполагается — как единый глобальный стилевой файл, где вы используете классы напрямую в вашем HTML:

<div class="bg-white rounded-lg p-6 shadow-xl">
  <slot></slot>
</div>

Написание плагинов

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

const plugin = require('tailwindcss/plugin')

module.exports = {
  // ...
  plugins: [
    plugin(function ({ addBase, addComponents, addUtilities, theme }) {
      addBase({
        'h1': {
          fontSize: theme('fontSize.2xl'),
        },
        'h2': {
          fontSize: theme('fontSize.xl'),
        },
      })
      addComponents({
        '.card': {
          backgroundColor: theme('colors.white'),
          borderRadius: theme('borderRadius.lg'),
          padding: theme('spacing.6'),
          boxShadow: theme('boxShadow.xl'),
        }
      })
      addUtilities({
        '.content-auto': {
          contentVisibility: 'auto',
        }
      })
    })
  ]
}

Узнайте больше о написании собственных плагинов в документации по плагинам.