Tailwind CSS
يتضمن Blockstudio دعمًا مدمجًا لـ Tailwind CSS v4. عند تفعيله، تُترجم كل صفحة من الواجهة الأمامية على جانب الخادم عبر TailwindPHP مع تخزين مؤقت تلقائي قائم على الملفات. وفي محرر الكتل، يوفّر سكربت Tailwind CDN المضمّن معاينة مباشرة أثناء التحرير.
لا حاجة إلى خطوة بناء أو CLI أو Node.js.
آلية العمل
يستخدم Blockstudio استراتيجيتين منفصلتين للترجمة بحسب السياق:
الواجهة الأمامية (من جانب الخادم)
في كل طلب للواجهة الأمامية، يلتقط Blockstudio صفحة HTML كاملة عبر مخزن إخراج مؤقت، ويستخرج جميع مرشحات الفئات CSS، ولا يترجم إلا CSS المستخدمة بالفعل، ثم يدرج النتيجة كوسم <style> مضمن قبل </head>.
تدفق الترجمة:
- يعرض WordPress صفحة HTML كاملة في مخزن إخراج مؤقت
- يفحص
TailwindPHP::extractCandidates()ملف HTML ويستخرج جميع أسماء فئات CSS المحتملة (تعبير نمطي سريع، بلا ترجمة) - تُجزّأ المرشحات المرتبة مع إعداد CSS لإنشاء مفتاح ذاكرة التخزين المؤقت
- عند إصابة ذاكرة التخزين المؤقت: تُقرأ CSS المترجمة من القرص وتُدرج
- عند غيابها: يترجم
TailwindPHP::generate()ملف CSS ويكتبه في مجلد ذاكرة التخزين المؤقت ثم يدرجه
يُدرج CSS المترجم كما يلي:
<style id="blockstudio-tailwind">
/* compiled CSS */
</style>
يشمل ذلك إعادة الضبط الأولية لـ Tailwind (إعادة ضبط CSS) وجميع الفئات النفعية المطابقة.
المحرر (من جانب العميل)
داخل محرر الكتل، يعمل سكربت Tailwind CDN مضمّن (إصدار المتصفح من Tailwind CSS v4) على جانب العميل. ويوفر معاينة مباشرة وفورية أثناء كتابة أسماء الفئات، دون أي اتصالات ذهاب وإياب إلى الخادم. لا يُحمّل CDN إلا في المحرر ولا يُقدّم مطلقًا على الواجهة الأمامية.
عند تفعيل assets.reset.enabled، يستعيد Blockstudio أيضًا أدوات العرض والموضع الشائعة في Tailwind داخل لوحة المحرر. يمنع ذلك قواعد تغليف كتل المحرر التابعة لـ WordPress من تجاوز فئات مستوى الحاوية مثل flex وgrid وabsolute وfixed وsticky، فتتطابق التخطيطات المعتمدة على الأدوات النفعية مع الواجهة الأمامية بدرجة أكبر.
تفعيل Tailwind
أضف إعداد tailwind إلى blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"tailwind": {
"enabled": true
}
}
أو فعّله عبر مرشح:
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
عندما تكون enabled هي true، ستُترجم Tailwind CSS تلقائيًا وتُدرج في كل صفحة من الواجهة الأمامية. يمكنك استخدام فئات Tailwind النفعية في أي مكان: في قوالب الكتل وقوالب القوالب ومرشحات the_content أو أي HTML يظهر في مخرجات الصفحة.
مخرجات الواجهة الأمامية
يُدرج CSS المترجم ضمن الصفحة افتراضيًا، مع الحفاظ على المخرجات المستخدمة في الإصدارات السابقة. ويمكن للمواقع التي لديها قواعد مشتركة كثيرة استخدام ورقة أنماط مجزّأة حسب المحتوى بدلًا من ذلك:
{
"tailwind": {
"enabled": true,
"output": "link"
}
}
يُصدر "output": "link" ملف ذاكرة التخزين المؤقت الحالي tailwind/{content-hash}.css بوصفه <link rel="stylesheet">. تتغير قيمة URL عند تغير هوية وقت التشغيل أو المرشحات أو المحرك أو مدخل CSS، لذا يمكن للمتصفحات وذاكرات التخزين المؤقت الطرفية الاحتفاظ بعناوين URL القديمة بأمان. اضبط خادم الويب أو CDN لإرسال ترويسة Cache-Control: public, immutable طويلة الأمد لنطاق ذاكرة التخزين المؤقت هذا.
جذر ذاكرة التخزين المؤقت الافتراضي عام ويقع تحت wp-content. إذا كان cache.path يشير إلى وحدة تخزين مطلقة خاصة، يعود Blockstudio إلى CSS مضمن ما لم يوفّر المرشح الحالي blockstudio/files/url قيمة عامة لـ URL ضمن نطاق tailwind:
add_filter(
'blockstudio/files/url',
function (string $url, string $path, string $scope): string {
if ('tailwind' !== $scope) {
return $url;
}
return 'https://static.example.com/blockstudio/' . basename($path);
},
10,
3
);
مساعدات تركيب القوالب
يتيح Blockstudio لمحرك TailwindPHP المضمّن نفسه العمل مع قوالب PHP. لا حاجة إلى نسخة من جهة القالب أو تنفيذ احتياطي:
$classes = bs_tw_merge('px-2 text-sm', 'px-4');
// text-sm px-4
$button = bs_tw_variants([
'base' => 'inline-flex items-center',
'variants' => [
'size' => [
'sm' => 'h-8 px-3',
'lg' => 'h-12 px-6',
],
],
'defaultVariants' => [
'size' => 'sm',
],
]);
echo $button(['size' => 'lg', 'class' => 'rounded']);
يقبل bs_tw_merge() قيم فئات متداخلة ويحل تعارضات أدوات Tailwind النفعية. ويعيد bs_tw_variants() دالة قابلة للاستدعاء بأسلوب CVA وتدعم الأساس والمتغيرات والمتغيرات الافتراضية والمتغيرات المركبة وclass وclassName.
الإعداد
يعتمد Tailwind v4 أسلوب إعداد يبدأ بـ CSS. وبدلًا من ملف إعداد JavaScript، تكتب الإعداد مباشرةً بصيغة CSS باستخدام التوجيه @theme.
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-family-heading: 'Inter', sans-serif; }"
}
}
قيمة config هي سلسلة CSS تُضاف بعد التوجيه @import "tailwindcss". يمكنك استخدام أي صياغة إعداد صالحة لـ Tailwind v4 من CSS هنا:
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: oklch(0.7 0.15 200); } @layer base { h1 { font-size: var(--text-4xl); } }"
}
}
بالنسبة إلى الإعدادات متعددة الأسطر، يكون أسلوب المرشح أسهل استخدامًا:
add_filter('blockstudio/settings/tailwind/config', function () {
return <<<CSS
@theme {
--color-primary: #3b82f6;
--color-secondary: #10b981;
--font-family-heading: 'Inter', sans-serif;
--breakpoint-xs: 30rem;
}
@layer base {
body {
font-family: var(--font-family-sans);
}
}
@layer utilities {
.btn { @apply px-4 py-2 rounded-lg font-medium; }
.btn-primary { @apply bg-blue-500 text-white hover:bg-blue-600; }
.card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
فئات الأدوات المخصصة
لتعريف أسماء بديلة قابلة لإعادة الاستخدام للفئات، استخدم @layer utilities مع التوجيه @apply الخاص بـ Tailwind مباشرةً في سلسلة الإعداد:
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: #6366f1; } @layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .section { @apply py-16 px-4 max-w-7xl mx-auto; } }"
}
}
يترجم هذا الفئات إلى جانب جميع أدوات Tailwind النفعية القياسية. وهي تعمل على الواجهة الأمامية (الترجمة من جانب الخادم) وفي المحرر (معاينة CDN).
يحافظ Blockstudio على ترتيب طبقات التتالي القياسي في Tailwind:
theme، ثم base، ثم components، ثم utilities. وهذا يطابق Tailwind CSS، لذا يمكن للقواعد في الطبقات اللاحقة تجاوز القواعد في الطبقات السابقة كما هو متوقع.
نوع حقل الفئات
لاستخدام فئات Tailwind في حقل classes لكتلة مع دعم الإكمال التلقائي، عيّن tailwind: true للحقل:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{
"id": "classes",
"type": "classes",
"label": "Classes",
"tailwind": true,
"default": "bg-white text-gray-900"
}
]
}
}
عندما تكون tailwind هي true:
- يقدّم الحقل اقتراحات إكمال تلقائي من قائمة فئات Tailwind الكاملة
- يُحمّل سكربت Tailwind CDN في المحرر لتوفير معاينة مباشرة
- تُخزّن الفئات كسلسلة مفصولة بمسافات في سمات الكتلة
استخدم قيمة الفئات في قالبك:
<div class="<?php echo $a['classes']; ?>">
<!-- block content -->
</div>
مرجع الإعدادات
| الخيار | النوع | الافتراضي | الوصف |
|---|---|---|---|
enabled |
boolean | false |
تفعيل تجميع Tailwind CSS في الواجهة الأمامية |
config |
string | "" |
سلسلة إعداد Tailwind v4 CSS-أولًا |
الإعداد عبر JSON
{
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: pink; }"
}
}
الإعداد عبر المرشحات
add_filter('blockstudio/settings/tailwind/enabled', '__return_true');
add_filter('blockstudio/settings/tailwind/config', function () {
return '@theme { --color-brand: pink; }';
});
التخزين المؤقت
يستخدم Blockstudio استراتيجية تخزين مؤقت مخصصة، صُممت لتناسب بنية Tailwind القائمة على الأدوات النفعية.
آلية عمل ذاكرة التخزين المؤقت
بدلًا من تجزئة HTML الصفحة بأكملها (ما يؤدي إلى إبطال ذاكرة التخزين المؤقت عند كل طلب بسبب القيم العشوائية والطوابع الزمنية وغيرها من المحتوى الديناميكي)، يستخرج Blockstudio مرشحات الفئات CSS فقط من HTML. ثم تُرتّب هذه المرشحات وتُجزّأ مع إعداد CSS لإنشاء مفتاح ثابت لذاكرة التخزين المؤقت.
وهذا يعني:
- تشترك صفحتان تستخدمان المجموعة نفسها من أصناف Tailwind في ملف CSS مخزّن مؤقتًا، حتى إن اختلفت HTML بينهما تمامًا
- لا يؤدي المحتوى الديناميكي مثل الرموز غير المتكررة، وأشرطة المستخدمين المسجلين، وأعداد التعليقات، والطوابع الزمنية إلى إبطال ذاكرة التخزين المؤقت
- لا تُبطَل ذاكرة التخزين المؤقت إلا عند تغيّر مجموعة أصناف CSS في الصفحة أو تغيّر إعداد Tailwind
عندما يستخدم وقت التشغيل مصدر اكتشاف منطقي، يشارك المصدر المحدد وسياق وقت التشغيل أيضًا في مساحة أسماء ذاكرة التخزين المؤقت. وتُعزل آخر CSS صالحة بين المعاينات، ولا يمكن أن تتسرب من اختيار مصدر إلى آخر.
موقع ذاكرة التخزين المؤقت
تُخزّن ملفات ذاكرة التخزين المؤقت في:
wp-content/blockstudio/cache/sites/{network-blog}/{runtime-identity}/tailwind/
يحدد cache.path المُهيأ وهوية المواقع المتعددة الحالية وهوية وقت التشغيل الكاملة البادئة الدقيقة. يُسمّى كل ملف باستخدام تجزئة MD5:
{hash}.css.
مسح ذاكرة التخزين المؤقت
احذف محتويات مجلد ذاكرة التخزين المؤقت لفرض إعادة التجميع:
// Clear all cached Tailwind CSS
Blockstudio\Runtime_Cache::purge('tailwind');
أو عبر WP-CLI:
wp eval "Blockstudio\\Runtime_Cache::purge('tailwind');"
سيعيد طلب الواجهة الأمامية التالي تجميع CSS وتخزينه مؤقتًا تلقائيًا.
المرشحات
blockstudio/tailwind/css
عدّل مُدخل CSS قبل التجميع. تبدأ سلسلة مُدخل CSS بـ @import "tailwindcss";، تليها أي إعدادات. استخدم هذا المرشح لإضافة توجيهات CSS إضافية أو قواعد @layer مخصصة أو عمليات استيراد الإضافات.
add_filter('blockstudio/tailwind/css', function (string $css): string {
// Add a custom utility
$css .= "\n@utility container-narrow { max-width: 48rem; margin-inline: auto; }";
return $css;
});
يبدو مُدخل CSS الكامل الذي تتم تجميعه على النحو التالي:
/* Base import */
@import 'tailwindcss';
/* Config from settings (if set) */
@theme {
--color-brand: pink;
}
/* Anything added via the blockstudio/tailwind/css filter */
مخزن الإخراج المؤقت
يرتبط تجميع Tailwind بنظام مخزن الإخراج المؤقت في Blockstudio. يلتقط المخزن HTML الصفحة كاملة بعد انتهاء WordPress من العرض، ما يتيح لـ Tailwind فحص جميع الأصناف من كل مصدر: قوالب الكتل، وقوالب القوالب، ومخرجات الإضافات، ومرشحات the_content، ومناطق الأدوات.
يعمل مرشح التجميع بالأولوية 999999 على خطاف blockstudio/buffer/output، لضمان معالجة HTML النهائي بعد جميع التعديلات الأخرى. يبدأ المخزن عند إجراء template_redirect، ما يعني أنه يعمل في طلبات الواجهة الأمامية فقط، وليس في لوحة الإدارة أو سياقات REST API أو AJAX.
يتيح تخزين المستند بأكمله مؤقتًا تنفيذ ذلك، لذا فهو مفعّل افتراضيًا. ويمكن لموقع لا يستخدم Tailwind ولا أصول الكتل تعطيله:
add_filter( 'blockstudio/buffer/enabled', '__return_false' );
يؤدي إرجاع false إلى تخطي المخزن بالكامل، ما يعطّل أيضًا تجميع Tailwind ونقل أنماط الكتل ونصوصها البرمجية إلى الرأس والتذييل.
البنية
Frontend Request
│
├─ WordPress renders HTML into output buffer
│
├─ blockstudio/buffer/output filter (priority 999999)
│ │
│ ├─ Settings::get('tailwind/enabled') → false? Return HTML unchanged
│ │
│ ├─ build_css_input()
│ │ ├─ @import "tailwindcss"
│ │ ├─ + tailwind/config setting
│ │ └─ + blockstudio/tailwind/css filter
│ │
│ ├─ TailwindPHP::extractCandidates($html)
│ │ └─ Returns array of CSS class names found in HTML
│ │
│ ├─ Cache key = md5(sorted candidates + css input)
│ │
│ ├─ Cache hit?
│ │ ├─ Yes → Read CSS from the shared runtime `tailwind/{hash}.css` scope
│ │ └─ No → TailwindPHP::generate() → Write to cache file
│ │
│ └─ Inject inline CSS, or link the content-hashed cache file when tailwind.output is "link"
│
└─ Browser receives HTML with compiled CSS
Editor Request
│
├─ Admin loads block editor
│
├─ Block with classes field (tailwind: true) detected
│ └─ Block_Registry::set_tailwind_active(true)
│
├─ Admin passes isTailwindActive + tailwindUrl to JS
│
└─ useTailwind() hook
├─ Injects Tailwind CDN script into document
├─ Creates hidden template div with HTML content
├─ Creates style tag for config
└─ CDN compiles CSS in-browser for live preview
مثال كامل
إعداد عملي كامل يتضمن ألوان سمة مخصصة وكتلة تستخدمها:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"tailwind": {
"enabled": true,
"config": "@theme { --color-brand: #6366f1; --color-brand-light: #a5b4fc; --color-surface: #f8fafc; } @layer utilities { .section-padding { @apply py-20 px-6; } .content-width { @apply max-w-5xl mx-auto; } .heading-xl { @apply text-4xl font-bold tracking-tight; } }"
}
}
{
"name": "my-theme/hero",
"title": "Hero Section",
"blockstudio": {
"attributes": [
{
"id": "title",
"type": "text",
"label": "Title",
"default": "Welcome"
},
{
"id": "wrapperClasses",
"type": "classes",
"label": "Wrapper Classes",
"tailwind": true,
"default": "section-padding bg-surface"
},
{
"id": "titleClasses",
"type": "classes",
"label": "Title Classes",
"tailwind": true,
"default": "heading-xl text-brand"
}
]
}
}
<section class="<?php echo $a['wrapperClasses']; ?>">
<div class="content-width">
<h1 class="<?php echo $a['titleClasses']; ?>">
<?php echo esc_html($a['title']); ?>
</h1>
</div>
</section>
يعرض هذا في الواجهة الأمامية جميع أدوات Tailwind المساعدة وألوان السمة المخصصة مجمّعة في وسم <style> مضمن واحد.
رموز التصميم، والأدوات المساعدة المخصصة، وإعداد Tailwind v4 الكامل لسمة جاهزة للإنتاج.