Gå til indhold

Brugerdefinerede plugins

Vis som Markdown Rediger på GitHub Dokumentation hos 3843abd

Et brugerdefineret plugin er en klasse af typen PHP, der implementerer TailwindPHP\Plugin\PluginInterface. Den modtager en instans af PluginAPI og bruger den til at registrere statiske og funktionelle utilities, komponenter og varianter. Når pluginet er registreret med registerPlugin(), kan det slås op ved navn i et @plugin-direktiv — samme mekanisme som de indbyggede typografi- og formularplugins bruger.

PluginInterface

Implementér tre metoder:

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() returnerer identifikatoren, der bruges i @plugin "...".
  • __invoke() kører pluginet og registrerer alt gennem $api. Arrayet $options indeholder værdierne fra blokken @plugin CSS.
  • getThemeExtensions() returnerer tema-navneområder, der skal flettes ind, før utilities genereres (returnér [], hvis der ikke er nogen).

Eksempel

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

Reference for PluginAPI

API afspejler plugin-TailwindCSS i API:

Metode Signatur Formål
addBase addBase(array $css): void Tilføj basislag-styles.
addUtilities addUtilities(array $utilities, array $options = []): void Registrér statiske utility-klasser, grupperet efter selector.
matchUtilities matchUtilities(array $utilities, array $options = []): void Registrér funktionelle utilities; $options['values'] angiver værdikortet, og $options['supportsNegativeValues'] aktiverer negative værdier.
addComponents addComponents(array $components, array $options = []): void Registrér komponentklasser (komponentlaget).
matchComponents matchComponents(array $components, array $options = []): void Registrér funktionelle komponenter med et værdikort.
addVariant addVariant(string $name, string|array $variant): void Registrér en statisk variant ud fra en selector.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Registrér en funktionel variant; $options['values'] angiver værdikortet.
theme theme(string $path, mixed $defaultValue = null): mixed Læs en temaværdi via en punktsti (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Læs en konfigurationsværdi via en punktsti eller hele konfigurationen, når $path er null.
prefix prefix(string $className): string Anvend det konfigurerede præfiks på et klassenavn.

Callbacken, der sendes til matchUtilities, matchComponents og matchVariant, modtager værdien og et andet argument-array med en modifier-nøgle.

Vælg utility-navne, som core Tailwind ikke allerede bruger. Hvis et plugin-utility har samme navn som et i core (for eksempel tab-*, som core Tailwind bruger til tab-size siden v4.3), havner begge erklæringer i samme regel, og core-udgaven kommer sidst og vinder: et plugin-tab-4, der er knyttet til 7, producerer stadig tab-size: 4.

Kendt problem: Varianter, der registreres med addVariant(), og varianter pr. værdi, som matchVariant() registrerer, anvendes ikke i den aktuelle udgivelse. hocus:flex fra eksemplet ovenfor kompileres til .hocus\:flex { display: flex; } uden en :hover/:focus-selector (#10). Indtil problemet er rettet, skal du definere varianten i CSS med @custom-variant; det fungerer: @custom-variant hocus (&:hover, &:focus);.

Registrering og brug

Registrér plugininstansen, og referér derefter til den med navnet fra 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";'
);

Se Plugins for direktivet @plugin og Tema for de værdier, der er tilgængelige via $api->theme().