Przejdź do treści

Własne wtyczki

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: 3843abd

Własna wtyczka to klasa PHP implementująca TailwindPHP\Plugin\PluginInterface. Otrzymuje instancję PluginAPI i używa jej do rejestrowania statycznych i funkcyjnych narzędzi, komponentów oraz wariantów. Po zarejestrowaniu za pomocą registerPlugin() wtyczkę można wywołać po nazwie w dyrektywie @plugin — tak samo działają wbudowane wtyczki typografii i formularzy.

PluginInterface

Zaimplementuj trzy metody:

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() zwraca identyfikator używany w @plugin "...".
  • __invoke() uruchamia wtyczkę, rejestrując wszystkie elementy za pomocą $api. Tablica $options zawiera wartości z bloku @plugin CSS.
  • getThemeExtensions() zwraca przestrzenie nazw motywu do połączenia przed wygenerowaniem narzędzi (zwróć [], jeśli nie ma żadnych).

Przykład

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

Dokumentacja PluginAPI

API odzwierciedla TailwindCSS wtyczki API:

Metoda Sygnatura Cel
addBase addBase(array $css): void Dodaje style warstwy bazowej.
addUtilities addUtilities(array $utilities, array $options = []): void Rejestruje statyczne klasy narzędziowe przypisane do selektora.
matchUtilities matchUtilities(array $utilities, array $options = []): void Rejestruje narzędzia funkcyjne; $options['values'] dostarcza mapę wartości, a $options['supportsNegativeValues'] włącza wartości ujemne.
addComponents addComponents(array $components, array $options = []): void Rejestruje klasy komponentów (warstwa komponentów).
matchComponents matchComponents(array $components, array $options = []): void Rejestruje komponenty funkcyjne z mapą wartości.
addVariant addVariant(string $name, string|array $variant): void Rejestruje wariant statyczny z selektora.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Rejestruje wariant funkcyjny; $options['values'] dostarcza mapę wartości.
theme theme(string $path, mixed $defaultValue = null): mixed Odczytuje wartość motywu według ścieżki rozdzielonej kropkami (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Odczytuje wartość konfiguracji według ścieżki rozdzielonej kropkami lub całą konfigurację, gdy $path ma wartość null.
prefix prefix(string $className): string Stosuje skonfigurowany prefiks do nazwy klasy.

Funkcja zwrotna przekazana do matchUtilities, matchComponents i matchVariant otrzymuje wartość oraz tablicę drugiego argumentu zawierającą klucz modifier.

Wybieraj nazwy narzędzi, których nie używa już podstawowy Tailwind. Gdy narzędzie wtyczki ma taką samą nazwę jak podstawowe (na przykład tab-*, używane przez podstawowy Tailwind dla tab-size od v4.3), obie deklaracje trafiają do tej samej reguły, a podstawowa jest ostatnia, więc wygrywa: narzędzie wtyczki tab-4 przypisane do 7 nadal tworzy tab-size: 4.

Znany problem: warianty zarejestrowane za pomocą addVariant() oraz warianty dla poszczególnych wartości rejestrowane przez matchVariant() nie są stosowane w bieżącym wydaniu. hocus:flex z powyższego przykładu kompiluje się do .hocus\:flex { display: flex; } bez selektora :hover/:focus (#10). Dopóki nie zostanie to naprawione, zdefiniuj wariant w CSS za pomocą @custom-variant — to działa: @custom-variant hocus (&:hover, &:focus);.

Rejestrowanie i używanie

Zarejestruj instancję wtyczki, a następnie odwołaj się do niej nazwą z 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";'
);

Zobacz Wtyczki, aby poznać dyrektywę @plugin, oraz Motyw, aby dowiedzieć się o wartościach udostępnianych przez $api->theme().