Перейти к содержимому

Пользовательские плагины

Просмотреть как Markdown Редактировать на GitHub Документация по 3843abd

Пользовательский плагин — это класс PHP, реализующий TailwindPHP\Plugin\PluginInterface. Он получает экземпляр PluginAPI и использует его для регистрации статических и функциональных утилит, компонентов и вариантов. После регистрации через registerPlugin() плагин выбирается по имени в директиве @plugin — так же работают встроенные плагины типографики и форм.

PluginInterface

Реализуйте три метода:

PHP
namespace TailwindPHP\Plugin;

interface PluginInterface
{
    public function getName(): string;
    public function __invoke(PluginAPI $api, array $options = []): void;
    public function getThemeExtensions(array $options = []): array;
}
  • getName() возвращает идентификатор, используемый в @plugin "...".
  • __invoke() запускает плагин, регистрируя всё через $api. Массив $options содержит значения из блока @plugin CSS.
  • getThemeExtensions() возвращает пространства имен темы, которые нужно объединить до генерации утилит (если таких нет, верните []).

Пример

PHP
use TailwindPHP\Plugin\PluginInterface;
use TailwindPHP\Plugin\PluginAPI;

class MyCustomPlugin implements PluginInterface
{
    public function getName(): string
    {
        return 'my-custom-plugin';
    }

    public function __invoke(PluginAPI $api, array $options = []): void
    {
        // Static utilities
        $api->addUtilities([
            '.btn' => [
                'padding' => '0.5rem 1rem',
                'border-radius' => '0.25rem',
                'font-weight' => '600',
            ],
            '.btn-primary' => [
                'background-color' => 'blue',
                'color' => 'white',
            ],
        ]);

        // Functional utilities (generates .gutter-sm, .gutter-md, .gutter-lg)
        $api->matchUtilities(
            [
                'gutter' => fn ($value) => ['padding-inline' => $value],
            ],
            ['values' => ['sm' => '1rem', 'md' => '2rem', 'lg' => '3rem']]
        );

        // Component classes (sorted into the components layer)
        $api->addComponents([
            '.card' => [
                'background-color' => 'white',
                'border-radius' => '0.5rem',
                'padding' => '1rem',
            ],
        ]);

        // Custom variant (see the note below the API reference)
        $api->addVariant('hocus', '&:hover, &:focus');

        // Read a theme value
        $primary = $api->theme('colors.blue.500', '#3b82f6');
    }

    public function getThemeExtensions(array $options = []): array
    {
        return []; // Return theme additions if needed
    }
}

Справочник по PluginAPI

API повторяет API плагина TailwindCSS:

Метод Сигнатура Назначение
addBase addBase(array $css): void Добавить стили базового слоя.
addUtilities addUtilities(array $utilities, array $options = []): void Зарегистрировать статические утилитарные классы по селектору.
matchUtilities matchUtilities(array $utilities, array $options = []): void Зарегистрировать функциональные утилиты; $options['values'] задает карту значений, $options['supportsNegativeValues'] включает отрицательные значения.
addComponents addComponents(array $components, array $options = []): void Зарегистрировать классы компонентов (слой компонентов).
matchComponents matchComponents(array $components, array $options = []): void Зарегистрировать функциональные компоненты с картой значений.
addVariant addVariant(string $name, string|array $variant): void Зарегистрировать статический вариант по селектору.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Зарегистрировать функциональный вариант; $options['values'] задает карту значений.
theme theme(string $path, mixed $defaultValue = null): mixed Прочитать значение темы по точечному пути (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Прочитать значение конфигурации по точечному пути или всю конфигурацию, если $path равно null.
prefix prefix(string $className): string Применить заданный префикс к имени класса.

Колбэк, переданный в matchUtilities, matchComponents и matchVariant, получает значение и массив второго аргумента, содержащий ключ modifier.

Выбирайте имена утилит, которые ядро Tailwind еще не использует. Если имя утилиты плагина совпадает с именем встроенной (например, tab-*, которое ядро Tailwind использует для tab-size, начиная с v4.3), оба объявления попадают в одно правило, причем встроенное идет последним и получает приоритет: утилита плагина tab-4 со значением 7 всё равно создает tab-size: 4.

Известная проблема: варианты, зарегистрированные через addVariant(), и варианты для отдельных значений, регистрируемые matchVariant(), в текущем выпуске не применяются. hocus:flex из примера выше компилируется в .hocus\:flex { display: flex; } без селектора :hover/:focus (#10). Пока проблема не исправлена, задайте вариант в CSS с помощью @custom-variant — этот способ работает: @custom-variant hocus (&:hover, &:focus);.

Регистрация и использование

Зарегистрируйте экземпляр плагина, а затем укажите его имя из getName():

PHP
use TailwindPHP\tw;
use function TailwindPHP\registerPlugin;

registerPlugin(new MyCustomPlugin());

$css = tw::generate(
    '<div class="btn btn-primary card gutter-md">…</div>',
    '@plugin "my-custom-plugin"; @import "tailwindcss/utilities.css";'
);

См. раздел Плагины, посвященный директиве @plugin, и раздел Тема, в котором описаны значения, доступные через $api->theme().