انتقل إلى المحتوى

إضافات مخصصة

عرض بتنسيق Markdown التعديل على GitHub التوثيق في 3843abd

الإضافة المخصصة هي فئة PHP تنفذ TailwindPHP\Plugin\PluginInterface. وتتلقى مثيلًا من PluginAPI وتستخدمه لتسجيل الأدوات الثابتة والوظيفية والمكونات والمتغيرات. بعد تسجيلها باستخدام registerPlugin()، تُستدعى الإضافة باسمها في توجيه @plugin — وهي الآلية نفسها التي تستخدمها إضافتا typography وforms المدمجتان.

PluginInterface

نفّذ ثلاث دوال:

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() المعرّف المستخدم في @plugin "...".
  • تشغّل __invoke() الإضافة، وتسجل كل شيء عبر $api. وتحمل المصفوفة $options القيم من كتلة @plugin CSS.
  • تعيد getThemeExtensions() مساحات أسماء النسق لدمجها قبل إنشاء الأدوات (أعد [] إن لم توجد).

مثال

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

تحاكي API واجهة إضافة TailwindCSS API:

الدالة التوقيع الغرض
addBase addBase(array $css): void إضافة أنماط إلى الطبقة الأساسية.
addUtilities addUtilities(array $utilities, array $options = []): void تسجيل فئات أدوات ثابتة مرتبطة بمحدد.
matchUtilities matchUtilities(array $utilities, array $options = []): void تسجيل أدوات وظيفية؛ يوفّر $options['values'] خريطة القيم، ويتيح $options['supportsNegativeValues'] القيم السالبة.
addComponents addComponents(array $components, array $options = []): void تسجيل فئات المكونات (طبقة المكونات).
matchComponents matchComponents(array $components, array $options = []): void تسجيل مكونات وظيفية بخريطة قيم.
addVariant addVariant(string $name, string|array $variant): void تسجيل متغير ثابت من محدد.
matchVariant matchVariant(string $name, callable $callback, array $options = []): void تسجيل متغير وظيفي؛ يوفّر $options['values'] خريطة القيم.
theme theme(string $path, mixed $defaultValue = null): mixed قراءة قيمة من النسق باستخدام مسار مفصول بنقاط (e.g. colors.blue.500).
config config(?string $path = null, mixed $defaultValue = null): mixed قراءة قيمة من الإعدادات بمسار مفصول بنقاط، أو الإعدادات كاملة عندما تكون $path null.
prefix prefix(string $className): string تطبيق البادئة المضبوطة على اسم فئة.

تتلقى الدالة الراجعة الممررة إلى 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():

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

راجع الإضافات لمعرفة توجيه @plugin، والنسق لمعرفة القيم التي يتيحها $api->theme().