Preskoči na vsebino

Vtičniki po meri

Prikaži kot Markdown Uredi na GitHub Dokumentacija za 3843abd

Vtičnik po meri je razred PHP, ki implementira TailwindPHP\Plugin\PluginInterface. Prejme primerek PluginAPI in ga uporabi za registracijo statičnih ter funkcionalnih pripomočkov, komponent in različic. Ko ga registrirate z registerPlugin(), se vtičnik razreši po imenu v direktivi @plugin — enako kot vgrajena vtičnika za tipografijo in obrazce.

PluginInterface

Implementirajte tri 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() vrne identifikator, uporabljen v @plugin "...".
  • __invoke() zažene vtičnik in registrira vse prek $api. Polje $options vsebuje vrednosti iz bloka @plugin CSS.
  • getThemeExtensions() vrne imenske prostore teme, ki jih je treba združiti pred ustvarjanjem pripomočkov (če jih ni, vrne []).

Primer

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

Referenca PluginAPI

API zrcali vmesnik vtičnikov TailwindCSS API:

Metoda Podpis Namen
addBase addBase(array $css): void Doda sloge osnovne plasti.
addUtilities addUtilities(array $utilities, array $options = []): void Registrira statične razrede pripomočkov, določene po selektorju.
matchUtilities matchUtilities(array $utilities, array $options = []): void Registrira funkcionalne pripomočke; $options['values'] poda mapo vrednosti, $options['supportsNegativeValues'] omogoči negativne vrednosti.
addComponents addComponents(array $components, array $options = []): void Registrira razrede komponent (plast komponent).
matchComponents matchComponents(array $components, array $options = []): void Registrira funkcionalne komponente z mapo vrednosti.
addVariant addVariant(string $name, string|array $variant): void Registrira statično različico iz selektorja.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Registrira funkcionalno različico; $options['values'] poda mapo vrednosti.
theme theme(string $path, mixed $defaultValue = null): mixed Prebere vrednost teme po poti z ločili v obliki pike (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Prebere vrednost konfiguracije po poti z ločili v obliki pike ali celotno konfiguracijo, če je $path ničelna vrednost.
prefix prefix(string $className): string Uporabi konfigurirano predpono za ime razreda.

Povratni klic, posredovan metodam matchUtilities, matchComponents in matchVariant, prejme vrednost in drugo polje z vrednostjo ključa modifier.

Izberite imena pripomočkov, ki jih jedro Tailwind še ne uporablja. Kadar ima pripomoček vtičnika enako ime kot jedrni pripomoček (na primer tab-*, ki ga jedro Tailwind uporablja za tab-size, ker gre za v4.3), obe deklaraciji končata v istem pravilu, jedrna pa je navedena zadnja in zato prevlada: pripomoček vtičnika tab-4, preslikan v 7, še vedno ustvari tab-size: 4.

Znana težava: različice, registrirane z addVariant(), in različice za posamezne vrednosti, ki jih registrira matchVariant(), se v trenutni izdaji ne uporabijo. hocus:flex iz zgornjega primera se prevede v .hocus\:flex { display: flex; } brez selektorja :hover/:focus (#10). Dokler to ni odpravljeno, določite različico v CSS z @custom-variant, kar deluje: @custom-variant hocus (&:hover, &:focus);.

Registracija in uporaba

Registrirajte primerek vtičnika, nato pa se nanj sklicujte z imenom iz 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";'
);

Direktivo @plugin in navodila za nalaganje najdete v razdelku Vtičniki, vrednosti, ki so na voljo prek $api->theme(), pa v razdelku Tema.