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

أدوات الأصناف

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

يعني إنشاء class في القوالب ضم السلاسل النصية، وتبديل الأصناف حسب الشروط، ومنع الأدوات اللاحقة من التعارض مع السابقة (يجب ألا يبقى كل من p-2 وp-4). في JavaScript، يُقسّم هذا العمل بين clsx وtailwind-merge. يتضمن TailwindPHP نسخًا PHP من كليهما، لتحصل على السلوك نفسه دون سلسلة أدوات Node.js أو حزم Composer إضافية.

تغطي ثلاث دوال النطاق كله: تنشئ cn() وتزيل التعارضات، وتزيل merge() التعارضات فقط، بينما تكتفي join() بالضم.

cn()

الأداة الموصى بها. تنشئ الأصناف الشرطية بأسلوب clsx أولًا، ثم تحل تعارضات Tailwind باستخدام tailwind-merge، بحيث تسود الأداة المتعارضة الأخيرة.

PHP
use function TailwindPHP\cn;

// Conflicts are resolved — px-4 overrides px-2
cn('px-2 py-1', 'px-4');
// => 'py-1 px-4'

// Conditional classes via a key => bool array
cn('btn', ['btn-primary' => true, 'btn-disabled' => false]);
// => 'btn btn-primary'

الوسائط المقبولة

تقبل cn() أي عدد من الوسائط. وتُسطّح كل وسيطة وتُصفّى وفق دلالات clsx:

الوسيطة السلوك
string تُضاف كما هي.
int / float تُحوّل إلى سلسلة نصية ثم تُضاف.
مصفوفة متسلسلة تُعالَج عناصرها بالتكرار.
مصفوفة key => bool يُضاف كل مفتاح إذا كانت قيمته صادقة.
null وfalse و0 و'' تُتجاهل.
PHP
cn('flex', ['items-center' => true], ['p-4', ['gap-2']], null);
// => 'flex items-center p-4 gap-2'

نمط المكوّنات

تتيح cn() إمكانية تجاوز إعدادات المكوّن: ادمج أصنافه مع ما يمرره المستدعي، وستُحسم التعارضات لصالح المستدعي.

PHP
use function TailwindPHP\cn;

function Card(array $props = []): string {
    $class = cn(
        'rounded-lg border bg-card text-card-foreground shadow-sm',
        $props['class'] ?? null
    );
    return "<div class=\"{$class}\">" . ($props['children'] ?? '') . "</div>";
}

Card(['class' => 'p-6', 'children' => 'Content']);
// <div class="rounded-lg border bg-card text-card-foreground shadow-sm p-6">Content</div>

لأنماط المكوّنات التعريفية متعددة المحاور، اجمع cn() مع variants().

merge()

حلّ التعارضات فقط، دون إنشاء شرطي. مرّر سلاسل الأصناف؛ فالأصناف اللاحقة تتجاوز السابقة عند استهداف الخاصية نفسها. استخدمها عندما تكون مدخلاتك سلاسل نصية عادية بالفعل.

PHP
use function TailwindPHP\merge;

merge('px-2 py-1 bg-red-500', 'px-4 bg-blue-500');
// => 'py-1 px-4 bg-blue-500'

// Conflict resolution is variant-aware
merge('hover:bg-red-500', 'hover:bg-blue-500');
// => 'hover:bg-blue-500'

إن cn() مبنية فوق clsx باستخدام merge()؛ لذا استخدم merge() مباشرةً فقط عندما لا تحتاج إلى صياغة المصفوفة الشرطية.

join()

ضم بسيط دون حلّ للتعارضات. تُسقط القيم غير الصادقة، لكن تُبقي جميع الأدوات المتعارضة. استخدمها عندما تعرف عدم وجود تعارضات وتريد الخيار الأقل كلفة.

PHP
use function TailwindPHP\join;

join('foo', 'bar', null, 'baz');
// => 'foo bar baz'

أيّها أستخدم؟

الدالة تنشئ (الشروط والمصفوفات) تحلّ التعارضات متى تُستخدم
cn() نعم نعم الخيار الافتراضي — لإنشاء سلاسل أصناف قد تتعارض.
merge() لا نعم عندما تكون المدخلات سلاسل نصية عادية وتحتاج فقط إلى إزالة التعارضات.
join() نعم لا عندما تعرف عدم وجود تعارضات وتريد أقل قدر من العمل.

الاستيرادات

PHP
use function TailwindPHP\cn;
use function TailwindPHP\merge;
use function TailwindPHP\join;

توجد الدوال الثلاث في مساحة الأسماء الرئيسية TailwindPHP، وهي مضمنة مع الحزمة. إنها نسخ PHP من clsx (لـ Luke Edwards) وtailwind-merge (لـ Dany Castillo).