Ga naar de inhoud

Aangepaste plugins

Bekijken als Markdown Bewerken op GitHub Documentatie op 3843abd

Een aangepaste plugin is een PHP-klasse die TailwindPHP\Plugin\PluginInterface implementeert. De plugin ontvangt een PluginAPI-instantie en gebruikt die om statische en functionele utilities, componenten en varianten te registreren. Na registratie met registerPlugin() wordt de plugin op naam gevonden in een @plugin-directive — hetzelfde mechanisme dat de ingebouwde plugins voor typografie en formulieren gebruiken.

PluginInterface

Implementeer drie methoden:

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() retourneert de identifier die in @plugin "..." wordt gebruikt.
  • __invoke() voert de plugin uit en registreert alles via $api. De array $options bevat de waarden uit het @plugin-blok van CSS.
  • getThemeExtensions() retourneert themanaamruimten die moeten worden samengevoegd voordat utilities worden gegenereerd (retourneert [] als er geen zijn).

Voorbeeld

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

Referentie voor PluginAPI

De API weerspiegelt de plugin-TailwindCSS van API:

Methode Signatuur Doel
addBase addBase(array $css): void Stijlen voor de basislaag toevoegen.
addUtilities addUtilities(array $utilities, array $options = []): void Statische utilityklassen registreren op basis van selector.
matchUtilities matchUtilities(array $utilities, array $options = []): void Functionele utilities registreren; $options['values'] levert de waardenmap, $options['supportsNegativeValues'] schakelt negatieve waarden in.
addComponents addComponents(array $components, array $options = []): void Componentklassen registreren (componentenlaag).
matchComponents matchComponents(array $components, array $options = []): void Functionele componenten registreren met een waardenmap.
addVariant addVariant(string $name, string|array $variant): void Een statische variant registreren op basis van een selector.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Een functionele variant registreren; $options['values'] levert de waardenmap.
theme theme(string $path, mixed $defaultValue = null): mixed Een themewaarde ophalen via een puntpad (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Een configwaarde ophalen via een puntpad, of de volledige config wanneer $path null is.
prefix prefix(string $className): string Het geconfigureerde prefix toepassen op een klassenaam.

De callback die aan matchUtilities, matchComponents en matchVariant wordt doorgegeven, ontvangt de waarde en een tweede argumentarray met een modifier-sleutel.

Kies utilitynamen die de core van Tailwind niet al gebruikt. Wanneer een pluginutility dezelfde naam heeft als een coreutility (bijvoorbeeld tab-*, die de core van Tailwind gebruikt voor tab-size sinds v4.3), komen beide declaraties in dezelfde regel terecht en staat de corevariant als laatste, waardoor die wint: een plugin-tab-4 gekoppeld aan 7 levert nog steeds tab-size: 4 op.

Bekend probleem: varianten die zijn geregistreerd met addVariant(), en de varianten per waarde die matchVariant() registreert, worden in de huidige versie niet toegepast. hocus:flex uit het bovenstaande voorbeeld wordt gecompileerd naar .hocus\:flex { display: flex; } zonder selector :hover/:focus (#10). Tot dit is opgelost, definieer je de variant in CSS met @custom-variant; dat werkt: @custom-variant hocus (&:hover, &:focus);.

Registreren en gebruiken

Registreer de plugininstantie en verwijs er vervolgens naar met de naam uit 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";'
);

Zie Plugins voor de directive @plugin en Thema voor de waarden die via $api->theme() beschikbaar zijn.