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

السمة والتخصيص

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

تتكون سمة Tailwind من مجموعة مسطحة من متغيرات CSS. يمكنك توسيعها أو استبدالها بكتلة @theme { … } في CSS المدخل، والإشارة إلى تلك القيم من داخل CSS عبر دوال السمة، ثم قراءة القيم المحلولة من PHP. لا يوجد ملف إعداد JavaScript — فالسمة موجودة بالكامل في CSS.

كتلة @theme

تعرّف كتلة @theme رموز التصميم على هيئة خصائص مخصصة من CSS. وتحدد بادئة مساحة الاسم لكل متغير (--color-* و--font-* و--breakpoint-* و--spacing-* و…) الأدوات المساعدة والمتغيرات التي يغذيها الرمز في Tailwind.

PHP
use TailwindPHP\tw;

$css = tw::generate('<div class="bg-brand text-brand xs:flex">', '
    @import "tailwindcss";

    @theme {
        --color-brand: #3b82f6;
        --font-heading: "Inter", sans-serif;
        --breakpoint-xs: 20rem;
        --spacing-huge: 10rem;
    }
');

يسجل كل رمز أدوات مساعدة ضمن مساحة اسمه. ينشئ المثال أعلاه bg-brand وtext-brand وborder-brand وعائلة font-heading ومتغيرًا متجاوبًا هو xs: وخياري التباعد p-huge/m-huge — ولا تُنشأ هذه إلا عند ظهور الفئة في محتواك.

CSS
/* bg-brand resolves to the theme variable */
:root, :host {
  --color-brand: #3b82f6;
}
.bg-brand {
  background-color: var(--color-brand);
}

يسجل الرمز --breakpoint-xs المتغير xs: مباشرةً:

CSS
@media (min-width: 20rem) {
  .xs\:flex {
    display: flex;
  }
}

مساحات الأسماء الشائعة

مساحة الاسم ما تولّده
--color-* bg-* وtext-* وborder-* وfill-* وstroke-* و…
--font-* أدوات مساعدة من عائلة font-*
--text-* أدوات مساعدة لحجم الخط text-*
--breakpoint-* متغيرات متجاوبة (sm: وmd: وxs: مخصص)
--spacing-* قيم تباعد مسماة (p-huge وm-huge)
--radius-* أدوات مساعدة rounded-*
--shadow-* أدوات مساعدة shadow-*

مسح مساحة اسم

يؤدي ضبط محرف البدل لمساحة اسم على initial إلى إزالة الإعدادات الافتراضية في Tailwind لتلك المساحة قبل إضافة رموزك. يتيح لك هذا البدء بلوحة ألوان خالية:

CSS
@theme {
    /* Drop every default color, then define only what you need */
    --color-*: initial;
    --color-brand: #3b82f6;
    --color-ink: #111827;
}

يمسح --*: initial; السمة بالكامل. وتحذف قيمة واحدة من initial لمفتاح ليس محرف بدل (--color-red-500: initial;) ذلك الرمز وحده. القيمة الوحيدة المقبولة لمحرف بدل -* هي initial — وأي قيمة أخرى تؤدي إلى خطأ.

قراءة قيم السمة في CSS

theme()

تقرأ الدالة القديمة theme() قيمة باستخدام تدوين النقاط ضمن نطاقات أسماء v3-style. وتحلّها إلى قيمة الرمز أثناء الترجمة، لذا يمكن استخدامها حيثما تُتوقع قيمة، بما في ذلك القواعد المخصصة والتصريحات الأخرى.

PHP
$css = tw::generate('<div class="callout">', '
    @import "tailwindcss";
    .callout { color: theme(colors.red.500); }
');
CSS
.callout {
  color: oklch(63.7% .237 25.331);
}

تُطابق المسارات النقطية المتغيرات الأساسية (colors.red.500 → --color-red-500، وfontFamily.sans → عائلة sans). يدعم هذا معدِّل العتامة: theme(colors.red.500 / 50%). ويمكن تمرير قيمة احتياطية كوسيط ثانٍ: theme(colors.brand, #000). إذا تعذّر حل مسار ولم تُحدَّد قيمة احتياطية، يُستبعد الخيار الذي يستخدمه.

--theme()

يقرأ --theme() متغيرًا من السمة باستخدام اسم الخاصية المخصصة CSS، ويعيد مرجعًا من نوع var() افتراضيًا، لتظل القيمة قابلة للتجاوز أثناء التشغيل:

CSS
.btn { color: --theme(--color-brand); }
/* → color: var(--color-brand); */

أضف inline لاستبدال مرجع var() بالقيمة التي تم حلها: --theme(--color-brand inline). الوسيط الثاني قيمة احتياطية (--theme(--color-brand, #000))، وتُعالَج قيمة initial الاحتياطية بطريقة خاصة — إذ تُدرج في مراجع var() المتداخلة التي تُحل بدورها إلى initial. داخل قاعدة at-rule (@media، @container)، يُحل --theme() دائمًا مباشرةً لأن var() غير صالح في تلك المقدمات.

--spacing()

يضرب --spacing(n) وحدة التباعد الأساسية للسمة (--spacing) في n:

CSS
@utility my-gap { gap: --spacing(4); }
/* → gap: calc(var(--spacing) * 4); */

تُحل قيمة المضاعف 1 إلى المتغير الأساسي نفسه (--spacing(1) → var(--spacing)، وهو أيضًا ما يصدره p-1)، بينما تُحل 0 إلى طول صفري عادي.

هذا هو الحساب نفسه الذي تستخدمه أدوات التباعد المضمنة، لذا تظل القيم المخصصة متوافقة مع p-4 وm-4 وما شابهها.

--alpha()

يطبّق --alpha(color / opacity) العتامة على لون باستخدام color-mix() في فضاء الألوان oklab:

CSS
@utility tint { color: --alpha(var(--color-red-500) / 50%); }
CSS
.tint {
  color: #fb2c3680;
}
@supports (color: color-mix(in lab, red, red)) {
  .tint {
    color: color-mix(in oklab, var(--color-red-500) 50%, transparent);
  }
}

تظل صيغة color-mix() قابلة للتجاوز أثناء التشغيل؛ وتغطي القيمة الاحتياطية الثابتة التي تسبقها، والمحتسبة من قيمة السمة، المتصفحات التي لا تدعم color-mix(). عطّل القيمة الاحتياطية باستخدام الخيار polyfills في tw::compile().

تراكب العتامة وcolor-mix() → oklab()

تتراكب معدّلات العتامة. تطبيق 50% على قيمة تحمل عتامة بنسبة 50% ينتج 25%، ويُحسب ذلك في oklab. عندما يُحل معدّل العتامة على لون ثابت، يختزل TailwindPHP تعبير color-mix(in oklab, …) إلى قيمة oklab() ملموسة — وهو التحويل نفسه الذي يجريه lightningcss في سلسلة أدوات Tailwind الأصلية — بينما تحتفظ الألوان الديناميكية (التي لا تزال ضمن var()) بصيغة color-mix() لتظل قابلة للتجاوز أثناء التشغيل.

قراءة قيم السمة من PHP

تعيد ثلاث دوال وصول قيم السمة المحلولة على هيئة مصفوفات PHP. تقبل كل منها سلسلة إدخال اختيارية CSS (الافتراضية @import "tailwindcss";)، وتتوفر أيضًا على مثيل المترجم.

PHP
use TailwindPHP\tw;

tw::colors();
// ['red-500' => 'oklch(63.7% .237 25.331)', 'blue-500' => 'oklch(62.3% .214 259.815)', ...]

tw::breakpoints();
// ['sm' => '40rem', 'md' => '48rem', 'lg' => '64rem', 'xl' => '80rem', '2xl' => '96rem']

tw::spacing('@import "tailwindcss"; @theme { --spacing-huge: 10rem; }');
// ['huge' => '10rem']

مرّر سلسلة CSS لقراءة القيم وفق سمة مخصصة:

PHP
tw::colors('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
// [..., 'brand' => '#3b82f6']

tw::breakpoints('@import "tailwindcss"; @theme { --breakpoint-xs: 20rem; }');
// ['sm' => '40rem', ..., '2xl' => '96rem', 'xs' => '20rem']

يستخدم TailwindCSS 4 قيمة أساسية واحدة من --spacing بدلًا من مقياس --spacing-*، لذا يعيد tw::spacing() رموز --spacing-* المخصصة التي تحددها فقط. تتوفر الطرق نفسها من مثيل المترجم: $compiler->colors() و$compiler->breakpoints() و$compiler->spacing(). راجع API للاطلاع على التواقيع كاملة.

الخطوات التالية