Siirry sisältöön

Mukautetut laajennukset

Näytä Markdown-muodossa Muokkaa palvelussa GitHub Dokumentaatio: 3843abd

Mukautettu laajennus on PHP-luokka, joka toteuttaa TailwindPHP\Plugin\PluginInterfacen. Se saa PluginAPI-instanssin ja käyttää sitä staattisten ja funktionaalisten apuohjelmien, komponenttien ja varianttien rekisteröintiin. Kun laajennus on rekisteröity registerPlugin()lla, se löytyy nimellä @plugin-direktiivissä — samaa mekanismia käyttävät sisäänrakennetut typografia- ja lomakelaajennukset.

PluginInterface

Toteuta kolme metodia:

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() palauttaa tunnisteen, jota käytetään @plugin "..."ssä.
  • __invoke() suorittaa laajennuksen ja rekisteröi kaiken $apin kautta. $options-taulukko sisältää arvot @plugin CSS -lohkolta.
  • getThemeExtensions() palauttaa teeman nimiavaruudet, jotka yhdistetään ennen apuohjelmien luontia (palauta [], jos niitä ei ole).

Esimerkki

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

API vastaa TailwindCSS-laajennuksen API-rajapintaa:

Metodi Allekirjoitus Tarkoitus
addBase addBase(array $css): void Lisää perustason tyylit.
addUtilities addUtilities(array $utilities, array $options = []): void Rekisteröi staattisia apuohjelmaluokkia valitsimen perusteella.
matchUtilities matchUtilities(array $utilities, array $options = []): void Rekisteröi funktionaalisia apuohjelmia; $options['values'] määrittää arvojen kartan, $options['supportsNegativeValues'] sallii negatiiviset arvot.
addComponents addComponents(array $components, array $options = []): void Rekisteröi komponenttiluokkia (komponenttikerros).
matchComponents matchComponents(array $components, array $options = []): void Rekisteröi funktionaalisia komponentteja arvojen kartan avulla.
addVariant addVariant(string $name, string|array $variant): void Rekisteröi staattisen variantin valitsimesta.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Rekisteröi funktionaalisen variantin; $options['values'] määrittää arvojen kartan.
theme theme(string $path, mixed $defaultValue = null): mixed Lukee teeman arvon pistepolun perusteella (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Lukee asetuksen pistepolun perusteella tai koko asetuksen, kun $path on null.
prefix prefix(string $className): string Käyttää luokkanimessä määritettyä etuliitettä.

Metodeille matchUtilities, matchComponents ja matchVariant annettu takaisinkutsufunktio saa arvon ja toisena argumenttina taulukon, joka sisältää modifier-avaimen.

Valitse apuohjelmille nimet, joita ydin Tailwind ei jo käytä. Jos lisäosan apuohjelmalla on sama nimi kuin ytimen apuohjelmalla (esimerkiksi tab-*, jota ydin Tailwind käyttää kohteelle tab-size versiosta v4.3 alkaen), molemmat määrittelyt päätyvät samaan sääntöön, ja ytimen määrittely tulee viimeisenä, joten se voittaa: lisäosan tab-4, joka on yhdistetty arvoon 7, tuottaa silti tuloksen tab-size: 4.

Tunnettu ongelma: Metodilla addVariant() rekisteröityjä variantteja sekä arvokohtaisia variantteja, jotka matchVariant() rekisteröi, ei käytetä nykyisessä julkaisussa. Yllä olevan esimerkin hocus:flex kääntyy muotoon .hocus\:flex { display: flex; } ilman :hover/:focus-valitsinta (#10). Kunnes ongelma korjataan, määrittele variantti tiedostossa CSS käyttämällä @custom-variant, joka toimii: @custom-variant hocus (&:hover, &:focus);.

Rekisteröinti ja käyttö

Rekisteröi laajennuksen instanssi ja viittaa siihen sitten nimellä, joka annetaan metodissa 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";'
);

Katso sivulta Laajennukset ohjeet @plugin-direktiivin käyttöön ja sivulta Teema tiedot arvoista, jotka $api->theme() tuo saataville.