Προσαρμοσμένα πρόσθετα

Ένα προσαρμοσμένο πρόσθετο είναι μια κλάση PHP που υλοποιεί το TailwindPHP\Plugin\PluginInterface. Λαμβάνει μια παρουσία PluginAPI και τη χρησιμοποιεί για να καταχωρίσει στατικές και λειτουργικές βοηθητικές κλάσεις, στοιχεία και παραλλαγές. Αφού καταχωριστεί με το registerPlugin(), το πρόσθετο επιλύεται βάσει ονόματος σε μια οδηγία @plugin — με τον ίδιο μηχανισμό που χρησιμοποιούν τα ενσωματωμένα πρόσθετα τυπογραφίας και φορμών.

PluginInterface

Υλοποιήστε τρεις μεθόδους:

namespace TailwindPHP\Plugin;

interface PluginInterface
{
    public function getName(): string;
    public function __invoke(PluginAPI $api, array $options = []): void;
    public function getThemeExtensions(array $options = []): array;
}

• Το getName() επιστρέφει το αναγνωριστικό που χρησιμοποιείται στο @plugin "...".
• Το __invoke() εκτελεί το πρόσθετο και καταχωρίζει τα πάντα μέσω του $api. Ο πίνακας $options περιέχει τις τιμές από το μπλοκ @plugin CSS.
• Το getThemeExtensions() επιστρέφει τους χώρους ονομάτων του θέματος που θα συγχωνευτούν πριν δημιουργηθούν οι βοηθητικές κλάσεις (επιστρέψτε [] αν δεν υπάρχουν).

Παράδειγμα

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

Το API αντικατοπτρίζει την TailwindCSS API του πρόσθετου:

Η συνάρτηση επανάκλησης που περνά στο matchUtilities, matchComponents και matchVariant λαμβάνει την τιμή και ένα δεύτερο όρισμα, έναν πίνακα που περιέχει ένα κλειδί modifier.

Επιλέξτε ονόματα βοηθητικών κλάσεων που δεν χρησιμοποιεί ήδη ο πυρήνας του Tailwind. Όταν μια βοηθητική κλάση πρόσθετου έχει το ίδιο όνομα με μια βασική (για παράδειγμα, το tab-*, που ο πυρήνας του Tailwind χρησιμοποιεί για το tab-size από το v4.3), και οι δύο δηλώσεις τοποθετούνται στον ίδιο κανόνα και η βασική προστίθεται τελευταία, οπότε υπερισχύει: ένα πρόσθετο tab-4 με αντιστοίχιση στο 7 εξακολουθεί να παράγει tab-size: 4.

Γνωστό πρόβλημα: Οι παραλλαγές που καταχωρίζονται με το addVariant(), καθώς και οι παραλλαγές ανά τιμή που καταχωρίζει το matchVariant(), δεν εφαρμόζονται στην τρέχουσα έκδοση. Το hocus:flex από το παραπάνω παράδειγμα μεταγλωττίζεται σε .hocus\:flex { display: flex; } χωρίς επιλογέα :hover/:focus (#10). Μέχρι να διορθωθεί, ορίστε την παραλλαγή στο CSS με @custom-variant, που λειτουργεί: @custom-variant hocus (&:hover, &:focus);.

Καταχώριση και χρήση

Καταχωρίστε την παρουσία του πρόσθετου και έπειτα αναφερθείτε σε αυτό με το όνομα από το getName():

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";'
);

Δείτε τα Πρόσθετα για την οδηγία @plugin και τα Θέμα για τις τιμές που διατίθενται μέσω του $api->theme().