Перейти до вмісту

Власні плагіни

Переглянути як 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 Реєструє класи компонентів (шар компонентів).
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 див. у розділі Plugins, а значення, доступні через $api->theme(), — у Theme.