التوجيهات

التوجيهات هي قواعد at-rule مسبوقة بـ@ تكتبها في ملف الإدخال CSS لتركيب مخرجات Tailwind وتوسيعها وترتيبها. تغطي هذه الصفحة @apply و@utility و@variant و@custom-variant و@layer. يُشرح @theme في النسق؛ و@plugin في الإضافات؛ و@source في @source.

@apply

تدرج @apply تصريحات الأدوات الموجودة ضمن المحدد الخاص بك. استخدمها لإضافة أنماط الأدوات إلى فئة دلالية، بما في ذلك داخل المحددات المتداخلة واستعلامات الوسائط.

use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');

تعمل المتغيرات ضمن قائمة @apply — إذ يوسّع @apply bg-blue-500 hover:bg-blue-600; حالة :hover، وتنتج البادئات المتجاوبة مثل @apply px-4 md:px-6 lg:px-8; قواعد @media المناسبة. ويُطبّق أيضًا المعدّل المهم (@apply !flex;). كما تدعم المحددات المتداخلة، لذا تطبق قاعدة مثل .card { h2 { @apply text-xl font-bold; } } الأدوات على h2 المتداخل.

@apply عبارة: @apply px-4 { … } مع جسم تؤدي إلى خطأ. أما @apply التي تسرد معرّفات بشرطات فقط (@apply --my-mixin;)، فهي مزيج CSS من مسودة المزائج CSS، وليست قائمة أدوات مساعدة؛ لذلك لا تحل TailwindPHP هذه المشكلة. ويؤدي وضع مزيج وأدوات مساعدة في @apply واحدة إلى خطأ (You cannot use @apply with both mixins and utilities…). تُسقط قواعد المزج حاليًا من المخرجات بدلًا من تمريرها (#12).

@utility

يسجل @utility أداة مخصصة تشارك في محرك Tailwind — فتُرتب ضمن طبقة utilities وتقبل المتغيرات مثل الأدوات المدمجة. للأداة الثابتة متن ثابت:

@utility content-auto {
    content-visibility: auto;
}

بما أنها أداة فعلية، تُركّب المتغيرات تلقائيًا (hover:content-auto وmd:content-auto). ويمكن أن يستخدم المتن نفسه @apply ومحددات متداخلة:

@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}

تستخدم الأداة الوظيفية لاحقة -* في الاسم، وتقرأ القيمة المطابقة باستخدام --value():

@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}

يحل --value() قيمة المرشح بمقارنتها بكل مصدر بالتتابع: مساحة أسماء في النسق (--gutter-*)، أو قيمة اعتباطية بنوع بيانات ([length])، أو نوع قيمة مجردة (integer وnumber وpercentage وratio). يُحذف التصريح إذا تعذر حل --value() الخاص به، لذا يؤدي تكديس التصريحات إلى سلسلة بدائل احتياطية:

تحل --modifier() الجزء الذي يلي / بالطريقة نفسها: باستخدام line-height: --modifier(integer); في النص، تُصدر gutter-4/7 أيضًا line-height: 7. تتبع أسماء الأدوات المساعدة قواعد TailwindCSS v4.3.3: بحد أقصى / واحد، ولا يأتي % إلا في النهاية بعد رقم، ولا تُستخدم النقاط إلا بين الأرقام.

@variant

تطبّق @variant متغيرًا على التصريحات داخل CSS الخاص بك، من دون تعريف أداة مساعدة:

.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}

.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}

يمكن تكديس المتغيرات (@variant hover:focus)، وإدراجها مفصولة بفواصل، وتضمين بعضها داخل بعض، كما يمكنها تسمية @custom-variant الخاصة بك. ويُعامل @variant على المستوى الأعلى، إذا لم يتضمن متنًا أو تضمن @slot، على أنه @custom-variant لضمان التوافق مع الإصدارات السابقة.

@custom-variant

تعرّف @custom-variant متغيرًا جديدًا يمكنك إضافته كبادئة إلى أي أداة مساعدة. يحدد الشكل المختصر اسم المتغير ويقدم محددًا أو قاعدة at-rule بين قوسين.

يستخدم متغير قائمة المحددات & للإشارة إلى العنصر:

@custom-variant hocus (&:hover, &:focus);

ثم تُصدر hocus:bg-blue-500 قاعدتي :hover و:focus. ويعمل شكل السمة بالطريقة نفسها:

@custom-variant loading (&[data-loading="true"]);

يُغلّف متغير قاعدة at-rule الأدوات المساعدة المطابقة داخل تلك القاعدة:

@custom-variant tablet (@media (min-width: 600px));

تتراكم المتغيرات المخصصة مع المتغيرات المضمنة — إذ يضمّن sm:hocus:bg-blue-500 محدد hocus داخل استعلام الوسائط sm. للحالات الأكثر تعقيدًا، استخدم صيغة الكتلة مع @slot لتحديد موضع إدراج تصريحات الأداة المساعدة:

@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}

@layer

تتحكم @layer في ترتيب التتابع باستخدام طبقات التتابع الأصلية في CSS. يعلن تصريح @layer وحده ترتيب الطبقات؛ وتكون الغلبة للطبقات اللاحقة بصرف النظر عن خصوصية المحدد. والترتيب المعتمد في Tailwind هو:

@layer theme, base, components, utilities;

هذا بالضبط ما تُعدّه @import "tailwindcss" داخليًا. يمكنك إعلان ترتيبك الخاص، أو تقسيمه على عدة تصريحات (@layer reset, base; ثم @layer components, utilities;)، وإسناد القواعد إلى طبقة مسماة باستخدام كتلة:

use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');

تُبقي إضافة الأنماط الأساسية عبر @layer base هذه الأنماط أسفل components وutilities، لذا تتغلب فئة الأداة المساعدة دائمًا على الإعدادات الافتراضية للعنصر. وينطبق الأمر نفسه على @layer components { … } لفئات المكونات التي ينبغي أن تكون أسفل الأدوات المساعدة. وتتناول Imports الطبقات المجهولة والمعدّلات layer() على @import.

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

• Theme — رموز @theme ودوال السمة.
• Imports — @import والوحدات الافتراضية والمعدّلات layer().
• Plugins — التوجيه @plugin وAPI الإضافات.
• @source — تحكّم في الملفات والفئات التي يجري فحصها.