Treci la conținut

Pluginuri personalizate

Vizualizați ca Markdown Editați pe GitHub Documentație la 3843abd

Un plugin personalizat este o clasă PHP care implementează TailwindPHP\Plugin\PluginInterface. Primește o instanță PluginAPI și o folosește pentru a înregistra utilitare statice și funcționale, componente și variante. După înregistrarea cu registerPlugin(), pluginul este identificat după nume într-o directivă @plugin — același mecanism folosit de pluginurile integrate pentru tipografie și formulare.

PluginInterface

Implementați trei metode:

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() returnează identificatorul folosit în @plugin "...".
  • __invoke() rulează pluginul și înregistrează toate elementele prin $api. Tabloul $options conține valorile din blocul @plugin CSS.
  • getThemeExtensions() returnează spațiile de nume ale temei de combinat înainte de generarea utilitarelor (returnați [] dacă nu există).

Exemplu

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

Referință PluginAPI

API reproduce interfața pluginului TailwindCSS API:

Metodă Semnătură Scop
addBase addBase(array $css): void Adaugă stiluri la nivelul de bază.
addUtilities addUtilities(array $utilities, array $options = []): void Înregistrează clase de utilitare statice după selector.
matchUtilities matchUtilities(array $utilities, array $options = []): void Înregistrează utilitare funcționale; $options['values'] furnizează harta valorilor, iar $options['supportsNegativeValues'] activează valorile negative.
addComponents addComponents(array $components, array $options = []): void Înregistrează clase de componente (stratul componentelor).
matchComponents matchComponents(array $components, array $options = []): void Înregistrează componente funcționale cu o hartă a valorilor.
addVariant addVariant(string $name, string|array $variant): void Înregistrează o variantă statică dintr-un selector.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Înregistrează o variantă funcțională; $options['values'] furnizează harta valorilor.
theme theme(string $path, mixed $defaultValue = null): mixed Citește o valoare a temei folosind o cale cu puncte (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Citește o valoare de configurare folosind o cale cu puncte sau întreaga configurație dacă $path este null.
prefix prefix(string $className): string Aplică prefixul configurat unui nume de clasă.

Funcția callback transmisă lui matchUtilities, matchComponents și matchVariant primește valoarea și un al doilea tablou de argumente care conține o cheie modifier.

Alegeți nume de utilitare pe care utilitarele de bază Tailwind nu le folosesc deja. Când un utilitar de plugin are același nume cu unul de bază (de exemplu tab-*, folosit de Tailwind pentru tab-size începând cu v4.3), ambele declarații sunt incluse în aceeași regulă, iar cea de bază apare ultima și are prioritate: un plugin tab-4 asociat cu 7 produce tot tab-size: 4.

Problemă cunoscută: variantele înregistrate cu addVariant() și variantele pentru fiecare valoare înregistrate de matchVariant() nu sunt aplicate în versiunea actuală. hocus:flex din exemplul de mai sus se compilează în .hocus\:flex { display: flex; } fără selector :hover/:focus (#10). Până la remedierea problemei, definiți varianta în CSS folosind @custom-variant; aceasta funcționează: @custom-variant hocus (&:hover, &:focus);.

Înregistrare și utilizare

Înregistrați instanța pluginului, apoi referiți-vă la ea folosind numele din 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";'
);

Consultați Plugins pentru directiva @plugin și detalii despre încărcare, iar Theme pentru valorile expuse prin $api->theme().