Към съдържанието

Персонализирани плъгини

Преглед като 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 отразява TailwindCSS приставния API:

Метод Сигнатура Предназначение
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 Регистрира класове на компоненти (слой components).
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().