Pāriet uz saturu

Pielāgoti spraudņi

Skatīt kā Markdown Rediģēt vietnē GitHub Dokumentācija vietnē 3843abd

Pielāgots spraudnis ir PHP klase, kas ievieš TailwindPHP\Plugin\PluginInterface. Tas saņem PluginAPI instanci un izmanto to, lai reģistrētu statiskās un funkcionālās utilītas, komponentus un variantus. Pēc reģistrēšanas ar registerPlugin() spraudni var atrast pēc nosaukuma @plugin direktīvā — tāpat darbojas iebūvētie tipogrāfijas un veidlapu spraudņi.

PluginInterface

Ieviesiet trīs metodes:

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() atgriež identifikatoru, ko izmanto @plugin "...".
  • __invoke() palaiž spraudni un reģistrē visu, izmantojot $api. Masīvā $options ir vērtības no @plugin CSS bloka.
  • getThemeExtensions() atgriež tēmas nosaukumvietas, kas jāapvieno pirms utilītu ģenerēšanas (ja to nav, atgrieziet []).

Piemērs

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

PluginAPI atsauce

API atspoguļo TailwindCSS spraudņa API:

Metode Paraksts Mērķis
addBase addBase(array $css): void Pievienot pamata slāņa stilus.
addUtilities addUtilities(array $utilities, array $options = []): void Reģistrēt statiskas utilītu klases pēc atlasītāja.
matchUtilities matchUtilities(array $utilities, array $options = []): void Reģistrēt funkcionālās utilītas; $options['values'] nodrošina vērtību karti, $options['supportsNegativeValues'] iespējo negatīvas vērtības.
addComponents addComponents(array $components, array $options = []): void Reģistrēt komponentu klases (komponentu slānis).
matchComponents matchComponents(array $components, array $options = []): void Reģistrēt funkcionālos komponentus ar vērtību karti.
addVariant addVariant(string $name, string|array $variant): void Reģistrēt statisku variantu no atlasītāja.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Reģistrēt funkcionālu variantu; $options['values'] nodrošina vērtību karti.
theme theme(string $path, mixed $defaultValue = null): mixed Nolasīt tēmas vērtību pēc punktu ceļa (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Nolasīt konfigurācijas vērtību pēc punktu ceļa vai visu konfigurāciju, ja $path ir null.
prefix prefix(string $className): string Piemērot konfigurēto prefiksu klases nosaukumam.

Atzvanfunkcija, kas nodota metodēm matchUtilities, matchComponents un matchVariant, saņem vērtību un otru argumentu — masīvu ar atslēgu modifier.

Izvēlieties utilītu nosaukumus, ko pamata Tailwind vēl neizmanto. Ja spraudņa utilītai ir tāds pats nosaukums kā pamata utilītai (piemēram, tab-*, ko pamata Tailwind izmanto tab-size kopš v4.3), abas deklarācijas nonāk vienā noteikumā, un pēdējā ir pamata deklarācija, tāpēc uzvar tā: pat ja spraudņa tab-4 ir piesaistīts 7, tiek iegūts tab-size: 4.

Zināma problēma: varianti, kas reģistrēti ar addVariant(), un katras vērtības varianti, ko reģistrē matchVariant(), pašreizējā laidienā netiek piemēroti. Iepriekšējā piemērā hocus:flex tiek kompilēts kā .hocus\:flex { display: flex; } bez :hover/:focus atlasītāja (#10). Kamēr problēma nav novērsta, definējiet variantu CSS, izmantojot @custom-variant — tas darbojas: @custom-variant hocus (&:hover, &:focus);.

Reģistrēšana un lietošana

Reģistrējiet spraudņa instanci, pēc tam norādiet to pēc nosaukuma, kas iegūts no 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";'
);

Direktīvu @plugin un ielādes informāciju skatiet sadaļā Spraudņi, bet vērtības, kas pieejamas caur $api->theme(), — sadaļā Tēma.