Spec-Zone.ru › Tailwind CSS

Плагины

Расширение Tailwind с помощью многократно используемых плагинов сторонних разработчиков.

Обзор

Плагины позволяют регистрировать новые стили для Tailwind, которые будут внедрены в пользовательский стилевой лист с помощью JavaScript вместо CSS.

Чтобы начать работу с первым плагином, импортируйте функцию plugin Tailwind из tailwindcss/plugin. Затем внутри массива plugins, вызовите импортированную функцию plugin с анонимной функцией в качестве первого аргумента.

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities, addComponents, e, config }) {
      // Add your custom styles here
    }),
  ]
}

Функции плагинов принимают один объект-аргумент, который можно распаковать в несколько вспомогательных функций:

  • addUtilities(), для регистрации новых статических стилей-утилит
  • matchUtilities(), для регистрации новых динамических стилей-утилит
  • addComponents(), для регистрации новых статических стилей компонентов
  • matchComponents(), для регистрации новых динамических стилей компонентов
  • addBase(), для регистрации новых базовых стилей
  • addVariant(), для регистрации пользовательских статических вариантов
  • matchVariant(), для регистрации пользовательских динамических вариантов
  • theme(), для поиска значений в конфигурации темы пользователя
  • config(), для поиска значений в конфигурации Tailwind пользователя
  • corePlugins(), для проверки, включен ли базовый плагин
  • e(), для ручного экранирования строк, предназначенных для использования в именах классов

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

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

Плагины можно добавить в свой проект, установив их через npm, а затем добавив их в файл tailwind.config.js:

tailwind.config.js
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/container-queries'),
  ]
}

Шрифты

Плагин @tailwindcss/typography добавляет набор prose классов, которые можно использовать для быстрого добавления осмысленных шрифтовых стилей к блокам содержимого, которые поступают из источников, таких как Markdown или база данных CMS.

<article class="prose lg:prose-xl">
  <h1>Garlic bread with cheese: What the science tells us</h1>
  <p>
    For years parents have espoused the health benefits of eating garlic bread with cheese to their
    children, with the food earning such an iconic status in our culture that kids will often dress
    up as warm, cheesy loaf for Halloween.
  </p>
  <p>
    But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
    springing up around the country.
  </p>
  <!-- ... -->
</article>

Подробнее о плагине шрифтов →

Формы

Плагин @tailwindcss/forms добавляет настроенный уровень сброса форм, что упрощает стилизацию элементов формы с помощью классов-утилит.

<!-- You can actually customize padding on a select element: -->
<select class="px-4 py-3 rounded-full">
  <!-- ... -->
</select>

<!-- Or change a checkbox color using text color utilities: -->
<input type="checkbox" class="rounded text-pink-500" />

Подробнее о плагине форм →

Соотношение сторон

Плагин @tailwindcss/aspect-ratio является альтернативой встроенной поддержке aspect-ratio в старых браузерах и добавляет aspect-w-{n} и aspect-h-{n} классы, которые можно комбинировать, чтобы задать элементу фиксированное соотношение сторон.

<div class="aspect-w-16 aspect-h-9">
  <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</div>

Подробнее о плагине соотношения сторон →

Запросы к контейнерам

Плагин @tailwindcss/container-queries добавляет новые @{size} варианты, такие как @sm и @md, которые позволяют стилизовать элемент на основе размеров родительского элемента, помеченного как @container, а не области просмотра.

<div class="@container">
  <div class="@lg:text-sky-400">
    <!-- ... -->
  </div>
</div>

Подробнее о плагине запросов к контейнерам →

Добавление утилит

Функции addUtilities и matchUtilities позволяют регистрировать новые стили в слое utilities Tailwind.

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

Статические утилиты

Используйте функцию addUtilities для регистрации простых статических утилит, которые не поддерживают значения, предоставляемые пользователем:

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities }) {
      addUtilities({
        '.content-auto': {
          'content-visibility': 'auto',
        },
        '.content-hidden': {
          'content-visibility': 'hidden',
        },
        '.content-visible': {
          'content-visibility': 'visible',
        },
      })
    })
  ]
}

Дополнительную информацию о представлении ваших стилей в формате JavaScript см. в справочнике синтаксиса CSS-в-JS.

Динамические утилиты

Используйте функцию matchUtilities для регистрации утилит, которые сопоставляются со значениями, определенными в конфигурации theme пользователя:

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  theme: {
    tabSize: {
      1: '1',
      2: '2',
      4: '4',
      8: '8',
    }
  },
  plugins: [
    plugin(function({ matchUtilities, theme }) {
      matchUtilities(
        {
          tab: (value) => ({
            tabSize: value
          }),
        },
        { values: theme('tabSize') }
      )
    })
  ]
}

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

<div class="tab-[13]">
  <!-- ... -->
</div>

Префикс и важность

По умолчанию утилиты плагинов автоматически учитывают пользовательские настройки prefix и important.

Это означает, что при данной конфигурации Tailwind:

tailwind.config.js
module.exports = {
  prefix: 'tw-',
  important: true,
  // ...
}

…пример плагина выше сгенерирует следующий CSS:

.tw-content-auto {
  content-visibility: auto !important;
}
.tw-content-hidden {
  content-visibility: hidden !important;
}
.tw-content-visible {
  content-visibility: visible !important;
}

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

Любые пользовательские утилиты, добавленные с помощью addUtilities, могут автоматически использоваться с модификаторами:

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

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

Указание значений по умолчанию

Плагины утилит могут задавать значения по умолчанию, включив объект конфигурации в качестве второго аргумента функции plugin:

./plugins/tab-size.js
const plugin = require('tailwindcss/plugin')

module.exports = plugin(function({ matchUtilities, theme }) {
  matchUtilities(
    {
      tab: (value) => ({
        tabSize: value
      }),
    },
    { values: theme('tabSize') }
  )
}, {
  theme: {
    tabSize: {
      1: '1',
      2: '2',
      4: '4',
      8: '8',
    }
  }
})

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

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

Функция addComponents позволяет регистрировать новые стили в слое components Tailwind.

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

Чтобы добавить новые стили компонентов из плагина, вызовите addComponents, передав свои стили в формате CSS-в-JS:

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addComponents }) {
      addComponents({
        '.btn': {
          padding: '.5rem 1rem',
          borderRadius: '.25rem',
          fontWeight: '600',
        },
        '.btn-blue': {
          backgroundColor: '#3490dc',
          color: '#fff',
          '&:hover': {
            backgroundColor: '#2779bd'
          },
        },
        '.btn-red': {
          backgroundColor: '#e3342f',
          color: '#fff',
          '&:hover': {
            backgroundColor: '#cc1f1a'
          },
        },
      })
    })
  ]
}

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

Префикс и важность

По умолчанию классы компонентов автоматически учитывают настройку prefix пользователя, но они не затрагиваются настройкой important пользователя.

Это означает, что при данной конфигурации Tailwind:

tailwind.config.js
module.exports = {
  prefix: 'tw-',
  important: true,
  // ...
}

…пример плагина выше сгенерирует следующий CSS:

.tw-btn {
  padding: .5rem 1rem;
  border-radius: .25rem;
  font-weight: 600;
}
.tw-btn-blue {
  background-color: #3490dc;
  color: #fff;
}
.tw-btn-blue:hover {
  background-color: #2779bd;
}
.tw-btn-red {
  background-color: #e3342f;
  color: #fff;
}
.tw-btn-red:hover {
  background-color: #cc1f1a;
}

Хотя редко бывает веская причина сделать объявления компонентов важными, если вам действительно это нужно, вы всегда можете добавить !important вручную:

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addComponents }) {
      addComponents({
        '.btn': {
          padding: '.5rem 1rem !important',
          borderRadius: '.25rem !important',
          fontWeight: '600 !important',
        },
        // ...
      })
    })
  ]
}

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

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  prefix: 'tw-',
  plugins: [
    plugin(function({ addComponents }) {
      const components = {
        // ...
        '.navbar-inverse a.nav-link': {
            color: '#fff',
        }
      }

      addComponents(components)
    })
  ]
}

…будет сгенерирован следующий CSS:

.tw-navbar-inverse a.tw-nav-link {
    color: #fff;
}

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

Любые классы компонентов, добавленные с помощью addComponents, могут автоматически использоваться с модификаторами:

<div class="btn md:btn-lg">
  <!-- ... -->
</div>

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

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

Функция addBase позволяет регистрировать новые стили в слое base Tailwind. Используйте ее для добавления таких элементов, как базовые шрифтовые стили, настроенные глобальные сбросы или @font-face правила.

Чтобы добавить новые базовые стили из плагина, вызовите addBase, передав свои стили в формате CSS-в-JS:

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addBase, theme }) {
      addBase({
        'h1': { fontSize: theme('fontSize.2xl') },
        'h2': { fontSize: theme('fontSize.xl') },
        'h3': { fontSize: theme('fontSize.lg') },
      })
    })
  ]
}

Поскольку базовые стили предназначены для назначения простых селекторов, таких как div или h1, они не учитывают пользовательские настройки prefix или important.

Добавление вариантов

Функции addVariant и matchVariant позволяют регистрировать собственные пользовательские модификаторы, которые можно использовать так же, как встроенные варианты, например, hover, focus, или supports.

Статические варианты

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

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  // ...
  plugins: [
    plugin(function({ addVariant }) {
      addVariant('optional', '&:optional')
      addVariant('hocus', ['&:hover', '&:focus'])
      addVariant('inverted-colors', '@media (inverted-colors: inverted)')
    })
  ]
}

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

<form class="flex inverted-colors:outline ...">
  <input class="optional:border-gray-300 ..." />
  <button class="bg-blue-500 hocus:bg-blue-600">...</button>
</form>

Динамические варианты

Используйте функцию matchVariant для регистрации новых параметризованных вариантов, таких как встроенные supports-*, data-*, и aria-* варианты:

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ matchVariant }) {
      matchVariant(
        'nth',
        (value) => {
          return `&:nth-child(${value})`;
        },
        {
          values: {
            1: '1',
            2: '2',
            3: '3',
          }
        }
      );
    })
  ]
}

Варианты, определенные с помощью matchVariant, также поддерживают произвольные значения с использованием квадратной нотации:

<div class="nth-[3n+1]:bg-blue-500 ...">
  <!-- ... -->
</div>

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

matchVariant("min", (value) => `@media (min-width: ${value})`, {
  sort(a, z) {
    return parseInt(a.value) - parseInt(z.value);
  },
});

Состояния родительских и дочерних элементов

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

Для поддержки group-* и peer-* версий ваших пользовательских модификаторов, зарегистрируйте их как отдельные варианты, используя специальную директиву :merge, чтобы убедиться, что классы .group и .peer появляются только один раз в итоговом селекторе.

tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  // ...
  plugins: [
    plugin(function({ addVariant }) {
      addVariant('optional', '&:optional')
      addVariant('group-optional', ':merge(.group):optional &')
      addVariant('peer-optional', ':merge(.peer):optional ~ &')
    })
  ]
}

Расширение конфигурации

Плагины могут объединить свои собственные значения конфигурации в пользовательскую tailwind.config.js конфигурацию, предоставив объект в качестве второго аргумента функции plugin:

./plugins/tab-size.js
const plugin = require('tailwindcss/plugin')

module.exports = plugin(function({ matchUtilities, theme }) {
  matchUtilities(
    {
      tab: (value) => ({
        tabSize: value
      }),
    },
    { values: theme('tabSize') }
  )
}, {
  theme: {
    tabSize: {
      1: '1',
      2: '2',
      4: '4',
      8: '8',
    }
  }
})

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

Экспонирование опций

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

В таких случаях вы можете использовать plugin.withOptions для определения плагина, который можно вызвать с объектом конфигурации. Этот API похож на обычный API plugin, за исключением того, что каждый аргумент должен быть функцией, которая получает пользовательскую options и возвращает значение, которое вы обычно передавали бы с помощью обычного API:

./plugins/markdown.js
const plugin = require('tailwindcss/plugin')

module.exports = plugin.withOptions(function (options = {}) {
  return function({ addComponents }) {
    const className = options.className ?? 'markdown'

    addComponents({
      [`.${className}`]: {
        // ...
      }
    })
  }
}, function (options) {
  return {
    theme: {
      markdown: {
        // ...
      }
    },
  }
})

Пользователь вызывал бы ваш плагин, передавая свои параметры при его регистрации в своей plugins конфигурации:

tailwind.config.js
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('./plugins/markdown.js')({
      className: 'wysiwyg'
    })
  ],
}

Пользователь также может зарегистрировать плагины, созданные таким образом, обычно без вызова, если им не нужно передавать какие-либо пользовательские параметры:

tailwind.config.js
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('./plugins/markdown.js')
  ],
}

Синтаксис CSS-в-JS

Система плагинов Tailwind ожидает правила CSS, написанные как JavaScript-объекты, используя тот же вид синтаксиса, что и в библиотеках CSS-в-JS, таких как Emotion, работающий под капотом с помощью postcss-js.

Рассмотрим простое правило CSS:

.card {
  background-color: #fff;
  border-radius: .25rem;
  box-shadow: 0 2px 4px rgba(0,0,0,0.2);
}

Перевод этого в объект CSS-в-JS будет выглядеть так:

addComponents({
  '.card': {
    'background-color': '#fff',
    'border-radius': '.25rem',
    'box-shadow': '0 2px 4px rgba(0,0,0,0.2)',
  }
})

Для удобства имена свойств также могут быть написаны в camelCase и будут автоматически переведены в dash-case:

addComponents({
  '.card': {
    backgroundColor: '#fff',
    borderRadius: '.25rem',
    boxShadow: '0 2px 4px rgba(0,0,0,0.2)',
  }
})

Вложенность также поддерживается (с помощью postcss-nested), используя тот же синтаксис, с которым вы можете быть знакомы из Sass или Less:

addComponents({
  '.card': {
    backgroundColor: '#fff',
    borderRadius: '.25rem',
    boxShadow: '0 2px 4px rgba(0,0,0,0.2)',
    '&:hover': {
      boxShadow: '0 10px 15px rgba(0,0,0,0.2)',
    },
    '@media (min-width: 500px)': {
      borderRadius: '.5rem',
    }
  }
})

Несколько правил могут быть определены в одном объекте:

addComponents({
  '.btn': {
    padding: '.5rem 1rem',
    borderRadius: '.25rem',
    fontWeight: '600',
  },
  '.btn-blue': {
    backgroundColor: '#3490dc',
    color: '#fff',
    '&:hover': {
      backgroundColor: '#2779bd'
    },
  },
  '.btn-red': {
    backgroundColor: '#e3342f',
    color: '#fff',
    '&:hover': {
      backgroundColor: '#cc1f1a'
    },
  },
})

…или в виде массива объектов, если вам нужно повторить одно и то же ключевое слово:

addComponents([
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
  {
    '@media (min-width: 500px)': {
      // ...
    }
  },
])

© 2022 Tailwind Labs Inc.
https://tailwindcss.com/docs/plugins

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API