Lewati ke konten

Plugin Kustom

Lihat sebagai Markdown Edit di GitHub Dokumentasi di 3843abd

Plugin kustom adalah kelas PHP yang mengimplementasikan TailwindPHP\Plugin\PluginInterface. Plugin menerima instance PluginAPI dan menggunakannya untuk mendaftarkan utilitas statis dan fungsional, komponen, serta varian. Setelah didaftarkan dengan registerPlugin(), plugin dapat dipanggil berdasarkan nama dalam direktif @plugin — mekanisme yang sama dengan yang digunakan plugin tipografi dan formulir bawaan.

PluginInterface

Implementasikan tiga 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() mengembalikan identifier yang digunakan dalam @plugin "...".
  • __invoke() menjalankan plugin dan mendaftarkan semuanya melalui $api. Array $options memuat nilai dari blok @plugin CSS.
  • getThemeExtensions() mengembalikan namespace tema yang akan digabungkan sebelum utilitas dibuat (kembalikan [] jika tidak ada).

Contoh

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

Referensi PluginAPI

API mencerminkan API plugin TailwindCSS:

Metode Signature Tujuan
addBase addBase(array $css): void Menambahkan gaya lapisan dasar.
addUtilities addUtilities(array $utilities, array $options = []): void Mendaftarkan kelas utilitas statis dengan selector sebagai kunci.
matchUtilities matchUtilities(array $utilities, array $options = []): void Mendaftarkan utilitas fungsional; $options['values'] menyediakan peta nilai, $options['supportsNegativeValues'] mengaktifkan nilai negatif.
addComponents addComponents(array $components, array $options = []): void Mendaftarkan kelas komponen (lapisan komponen).
matchComponents matchComponents(array $components, array $options = []): void Mendaftarkan komponen fungsional dengan peta nilai.
addVariant addVariant(string $name, string|array $variant): void Mendaftarkan varian statis dari selector.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void Mendaftarkan varian fungsional; $options['values'] menyediakan peta nilai.
theme theme(string $path, mixed $defaultValue = null): mixed Membaca nilai tema berdasarkan jalur titik (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed Membaca nilai konfigurasi berdasarkan jalur titik, atau seluruh konfigurasi jika $path bernilai null.
prefix prefix(string $className): string Menerapkan prefiks yang dikonfigurasi ke nama kelas.

Callback yang diteruskan ke matchUtilities, matchComponents, dan matchVariant menerima nilai serta array argumen kedua yang berisi kunci modifier.

Pilih nama utilitas yang belum digunakan oleh Tailwind inti. Jika utilitas plugin memakai nama yang sama dengan utilitas inti (misalnya tab-*, yang digunakan Tailwind inti untuk tab-size sejak v4.3), kedua deklarasi masuk ke aturan yang sama dan utilitas inti ditempatkan terakhir, sehingga menang: plugin tab-4 yang dipetakan ke 7 tetap menghasilkan tab-size: 4.

Masalah yang diketahui: varian yang didaftarkan dengan addVariant(), serta varian per nilai yang didaftarkan oleh matchVariant(), belum diterapkan dalam rilis saat ini. hocus:flex dari contoh di atas dikompilasi menjadi .hocus\:flex { display: flex; } tanpa selector :hover/:focus (#10). Sampai masalah ini diperbaiki, definisikan varian dalam CSS dengan @custom-variant, yang berfungsi: @custom-variant hocus (&:hover, &:focus);.

Mendaftarkan dan menggunakan

Daftarkan instance plugin, lalu rujuk plugin tersebut menggunakan nama dari 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";'
);

Lihat Plugin untuk direktif @plugin, dan Tema untuk nilai yang disediakan melalui $api->theme().