Preskočiť na obsah

Vlastné pluginy

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 3843abd

Vlastný plugin je trieda PHP, ktorá implementuje TailwindPHP\Plugin\PluginInterface. Dostane inštanciu PluginAPI a pomocou nej registruje statické a funkčné nástroje, komponenty a varianty. Po registrácii cez registerPlugin() sa plugin vyhľadá podľa názvu v direktíve @plugin — rovnakým spôsobom ako vstavané pluginy pre typografiu a formuláre.

PluginInterface

Implementujte tri metódy:

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() vracia identifikátor použitý v @plugin "...".
  • __invoke() spustí plugin a zaregistruje všetko cez $api. Pole $options obsahuje hodnoty z bloku @plugin CSS.
  • getThemeExtensions() vracia menné priestory témy, ktoré sa zlúčia pred generovaním nástrojov (ak žiadne nie sú, vráťte []).

Príklad

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
    }
}

Referencia PluginAPI

Rozhranie API kopíruje rozhranie pluginu TailwindCSS API:

Metóda Signatúra Účel
addBase addBase(array $css): void Pridanie štýlov do základnej vrstvy.
addUtilities addUtilities(array $utilities, array $options = []): void Registrácia statických tried nástrojov podľa selektora.
matchUtilities matchUtilities(array $utilities, array $options = []): void Registrácia funkčných nástrojov; $options['values'] poskytuje mapu hodnôt, $options['supportsNegativeValues'] povoľuje záporné hodnoty.
addComponents addComponents(array $components, array $options = []): void Registrácia tried komponentov (vrstva komponentov).
matchComponents matchComponents(array $components, array $options = []): void Registrácia funkčných komponentov s mapou hodnôt.
addVariant addVariant(string $name, string|array $variant): void Registrácia statického variantu zo selektora.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Registrácia funkčného variantu; $options['values'] poskytuje mapu hodnôt.
theme theme(string $path, mixed $defaultValue = null): mixed Načítanie hodnoty témy podľa bodkovej cesty (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Načítanie hodnoty konfigurácie podľa bodkovej cesty alebo celej konfigurácie, ak je $path null.
prefix prefix(string $className): string Použitie nakonfigurovaného prefixu na názov triedy.

Funkcia callback odovzdaná do matchUtilities, matchComponents a matchVariant dostane hodnotu a druhý argument: pole obsahujúce kľúč modifier.

Vyberte názvy utilít, ktoré jadro Tailwind už nepoužíva. Keď má utilita pluginu rovnaký názov ako utilita jadra (napríklad tab-*, ktorý jadro Tailwind používa pre tab-size od v4.3), obe deklarácie sa ocitnú v rovnakom pravidle a utilita jadra je posledná, takže vyhrá: plugin tab-4 namapovaný na 7 stále vytvorí tab-size: 4.

Známy problém: varianty registrované pomocou addVariant() a varianty pre jednotlivé hodnoty, ktoré registruje matchVariant(), sa v aktuálnom vydaní neuplatňujú. hocus:flex z vyššie uvedeného príkladu sa skompiluje na .hocus\:flex { display: flex; } bez selektora :hover/:focus (#10). Kým sa to neopraví, definujte variant v CSS pomocou @custom-variant, čo funguje: @custom-variant hocus (&:hover, &:focus);.

Registrácia a používanie

Zaregistrujte inštanciu pluginu a potom na ňu odkazujte názvom z 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";'
);

Pozrite si Pluginy pre direktívu @plugin a Téma pre hodnoty sprístupnené cez $api->theme().