Vai al contenuto

Plugin personalizzati

Visualizza come Markdown Modifica su GitHub Documentazione di 3843abd

Un plugin personalizzato è una classe PHP che implementa TailwindPHP\Plugin\PluginInterface. Riceve un'istanza PluginAPI e la usa per registrare utility statiche e funzionali, componenti e varianti. Dopo la registrazione con registerPlugin(), il plugin viene risolto per nome in una direttiva @plugin — lo stesso meccanismo usato dai plugin integrati per tipografia e moduli.

PluginInterface

Implementa tre metodi:

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() restituisce l'identificatore usato in @plugin "...".
  • __invoke() esegue il plugin, registrando ogni elemento tramite $api. L'array $options contiene i valori del blocco @plugin CSS.
  • getThemeExtensions() restituisce gli spazi dei nomi del tema da unire prima della generazione delle utility (restituisce [] se non ce ne sono).

Esempio

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

riferimento PluginAPI

Il API rispecchia TailwindCSS API del plugin:

Metodo Firma Scopo
addBase addBase(array $css): void Aggiunge stili al livello base.
addUtilities addUtilities(array $utilities, array $options = []): void Registra classi di utility statiche indicizzate per selettore.
matchUtilities matchUtilities(array $utilities, array $options = []): void Registra utility funzionali; $options['values'] fornisce la mappa dei valori, $options['supportsNegativeValues'] abilita i valori negativi.
addComponents addComponents(array $components, array $options = []): void Registra classi di componenti (livello components).
matchComponents matchComponents(array $components, array $options = []): void Registra componenti funzionali con una mappa dei valori.
addVariant addVariant(string $name, string|array $variant): void Registra una variante statica a partire da un selettore.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Registra una variante funzionale; $options['values'] fornisce la mappa dei valori.
theme theme(string $path, mixed $defaultValue = null): mixed Legge un valore del tema tramite percorso con punti (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Legge un valore di configurazione tramite percorso con punti, oppure l'intera configurazione se $path è null.
prefix prefix(string $className): string Applica il prefisso configurato a un nome di classe.

La callback passata a matchUtilities, matchComponents e matchVariant riceve il valore e un array come secondo argomento, contenente una chiave modifier.

Scegli nomi di utility non già usati dal Tailwind di base. Quando un'utility del plugin condivide il nome con una di base (per esempio tab-*, che il Tailwind di base usa per tab-size da v4.3), entrambe le dichiarazioni finiscono nella stessa regola e quella di base viene dopo, quindi prevale: un tab-4 del plugin associato a 7 produce comunque tab-size: 4.

Problema noto: le varianti registrate con addVariant() e quelle per valore registrate da matchVariant() non vengono applicate nella versione corrente. hocus:flex dell'esempio sopra viene compilato in .hocus\:flex { display: flex; } senza selettore :hover/:focus (#10). Finché il problema non sarà risolto, definisci la variante in CSS con @custom-variant, soluzione funzionante: @custom-variant hocus (&:hover, &:focus);.

Registrazione e utilizzo

Registra l'istanza del plugin, quindi richiamala con il nome indicato in 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 Plugin per la direttiva @plugin e Tema per i valori esposti tramite $api->theme().