Hoppa till innehåll

Anpassade insticksprogram

Visa som Markdown Redigera på GitHub Dokumentation på 3843abd

Ett anpassat insticksprogram är en PHP-klass som implementerar TailwindPHP\Plugin\PluginInterface. Den får en instans av PluginAPI och använder den för att registrera statiska och funktionella utilities, komponenter och varianter. När insticksprogrammet har registrerats med registerPlugin() kan det hämtas via namn i ett @plugin-direktiv — samma mekanism som de inbyggda insticksprogrammen för typografi och formulär använder.

PluginInterface

Implementera 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() returnerar identifieraren som används i @plugin "...".
  • __invoke() kör insticksprogrammet och registrerar allt via $api. Arrayen $options innehåller värdena från blocket @plugin CSS.
  • getThemeExtensions() returnerar temautrymmen som ska slås samman innan utilities genereras (returnera [] om det inte finns några).

Exempel

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

Referens för PluginAPI

API speglar insticksprogrammets TailwindCSS API:

Metod Signatur Syfte
addBase addBase(array $css): void Lägg till stilar i baslagret.
addUtilities addUtilities(array $utilities, array $options = []): void Registrera statiska utility-klasser med selektor som nyckel.
matchUtilities matchUtilities(array $utilities, array $options = []): void Registrera funktionella utilities; $options['values'] anger värdekartan och $options['supportsNegativeValues'] aktiverar negativa värden.
addComponents addComponents(array $components, array $options = []): void Registrera komponentklasser (komponentlagret).
matchComponents matchComponents(array $components, array $options = []): void Registrera funktionella komponenter med en värdekarta.
addVariant addVariant(string $name, string|array $variant): void Registrera en statisk variant från en selektor.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Registrera en funktionell variant; $options['values'] anger värdekartan.
theme theme(string $path, mixed $defaultValue = null): mixed Läs ett temavärde via en punktseparerad sökväg (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Läs ett konfigurationsvärde via en punktseparerad sökväg, eller hela konfigurationen när $path är null.
prefix prefix(string $className): string Tillämpa det konfigurerade prefixet på ett klassnamn.

Callbackfunktionen som skickas till matchUtilities, matchComponents och matchVariant får värdet och en andra argumentarray som innehåller en nyckel av typen modifier.

Välj utility-namn som kärnan i Tailwind inte redan använder. Om ett utility-namn i insticksprogrammet krockar med ett namn i kärnan (till exempel tab-*, som kärnan i Tailwind använder för tab-size sedan v4.3), hamnar båda deklarationerna i samma regel och kärnans deklaration kommer sist och vinner: ett tab-4 i insticksprogrammet mappat till 7 ger fortfarande tab-size: 4.

Känt problem: Varianter som registreras med addVariant() och varianterna per värde som matchVariant() registrerar tillämpas inte i den aktuella versionen. hocus:flex från exemplet ovan kompileras till .hocus\:flex { display: flex; } utan någon :hover/:focus-selektor (#10). Tills det är åtgärdat kan du definiera varianten i CSS med @custom-variant; det fungerar: @custom-variant hocus (&:hover, &:focus);.

Registrering och användning

Registrera insticksprograminstansen och hänvisa sedan till den med namnet från 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 Insticksprogram för direktivet @plugin och information om inläsning, och Tema för värdena som exponeras via $api->theme().