الترقية إلى الإصدار v7
يغطي هذا الدليل التغييرات المطلوبة عند الترقية من Blockstudio 6 إلى 7.
استيرادات وحدات ES
بادئة npm: الجديدة (موصى بها)
يقدم Blockstudio 7 بادئة npm: جديدة لاستيرادات وحدات ES، بما يتوافق مع اصطلاح محددات npm الخاصة بـDeno.
قبل (v6):
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";
بعد (v7):
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
استيرادات CSS
ينطبق التغيير نفسه على استيرادات CSS:
قبل (v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
بعد (v7):
import "npm:swiper@11.0.0/swiper.min.css";
التوافق مع الإصدارات السابقة
تظل البادئة blockstudio/ مدعومة للتوافق مع الإصدارات السابقة، وستواصل شيفرتك الحالية العمل دون تغيير. ومع ذلك، نوصي بالترحيل إلى البادئة npm: اتساقًا مع منظومة JavaScript الأوسع.
تقدم البادئة npm: عدة مزايا:
- التوافق مع المنظومة – تتبع الاصطلاح المعتمد لدى Deno
- الوضوح – توضح فورًا أنك تستورد من npm
- الاستعداد للمستقبل – قد تُهمَل البادئة
blockstudio/في إصدار رئيسي مستقبلي
أسماء الخطافات
يوحّد Blockstudio 7 أسماء جميع خطافات PHP لاستخدام snake_case بدلًا من camelCase، بما يتوافق مع اصطلاحات WordPress الأساسية.
أسماء الخطافات التي تغيرت
| الاسم القديم (v6) | الاسم الجديد (v7) |
|---|---|
blockstudio/blocks/components/useblockprops/render |
blockstudio/blocks/components/use_block_props/render |
blockstudio/blocks/components/innerblocks/render |
blockstudio/blocks/components/inner_blocks/render |
blockstudio/blocks/components/innerblocks/frontend/wrap |
blockstudio/blocks/components/inner_blocks/frontend/wrap |
blockstudio/blocks/components/richtext/render |
blockstudio/blocks/components/rich_text/render |
blockstudio/assets/process/scss/importPaths |
blockstudio/assets/process/scss/import_paths |
blockstudio/settings/assets/process/scssFiles |
blockstudio/settings/assets/process/scss_files |
blockstudio/settings/editor/formatOnSave |
blockstudio/settings/editor/format_on_save |
blockstudio/settings/blockEditor/disableLoading |
blockstudio/settings/block_editor/disable_loading |
blockstudio/settings/blockEditor/cssClasses |
blockstudio/settings/block_editor/css_classes |
blockstudio/settings/blockEditor/cssVariables |
blockstudio/settings/block_editor/css_variables |
blockstudio/settings/ai/enableContextGeneration |
blockstudio/settings/ai/enable_context_generation |
التوافق مع الإصدارات السابقة
تظل أسماء الخطافات القديمة بنمط camelCase مدعومة للتوافق مع الإصدارات السابقة، وستواصل شيفرتك الحالية العمل دون تغيير. ومع ذلك، نوصي بالترحيل إلى الأسماء الجديدة بنمط snake_case اتساقًا مع الاصطلاح.
مثال على الترحيل:
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
return ['my-stylesheet'];
});
// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
return ['my-stylesheet'];
});
وسوم الكتل المعتمدة
Blockstudio يُبقي الإصدار 7.6 بادئات المشروع والأسماء البديلة المطابقة كنقاط امتداد وقت التشغيل، لكنه يستخدم <bs:namespace-slug> بوصفه الصيغة القياسية في الأمثلة ومخرجات الفهرس وتعريفات العرض والتشخيصات. وتحمل الوسوم القياسية اسم الكتلة المسجل الفعلي ولا تعتمد على مرشح خاص بالمضيف.
لمشروع يستخدم brand => ["theme-components"] وui => ["bsui"]:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
يفحص أمر ترحيل مستقل مشروعًا قائمًا ويعيد كتابة الصيغ المختصرة بالصيغة القياسية. ويُصدر تقريرًا أولًا، ويتوقف عند الحالات التي لم تُحسم، ولا يغيّر سوى أسماء الوسوم. راجع ترحيل وسوم الكتل لمعرفة الأمر ومدخلاته وإجراءات السلامة فيه.
تسمية ملفات الأصول
Blockstudio يقدّم الإصدار 7 تدوين النقطة لامتدادات ملفات الأصول، ليحل محل تدوين الشرطة القديم بوصفه الاصطلاح الموصى به.
أسماء الملفات التي تغيّرت
| الاسم القديم (v6) | الاسم الجديد (v7) |
|---|---|
*-inline.(s)css |
*.inline.(s)css |
*-inline.js |
*.inline.js |
*-editor.(s)css |
*.editor.(s)css |
*-editor.js |
*.editor.js |
*-scoped.(s)css |
*.scoped.(s)css |
*-view.js |
*.view.js |
التوافق مع الإصدارات السابقة
لا يزال تدوين الشرطة مدعومًا للتوافق مع الإصدارات السابقة. وستواصل ملفاتك الحالية العمل دون إعادة تسميتها. ومع ذلك، نوصي بالانتقال إلى تدوين النقطة للكتل الجديدة.
مثال على الترحيل:
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css → style.inline.css
├── style-scoped.css → style.scoped.css
├── style-editor.css → style.editor.css
├── script.js
├── script-inline.js → script.inline.js
├── script-editor.js → script.editor.js
└── script-view.js → script.view.js
مفتاح الحقل
أصبحت القيمة الافتراضية لخاصية switch هي false بدلًا من true. في v6، كان لكل حقل مفتاح تبديل غير مرئي على الحافة اليسرى ومفعّلًا افتراضيًا. أما في v7، فالتبديل اختياري ويستخدم رمز عين ظاهرًا في تسمية الحقل.
ما الذي تغيّر
- القيمة الافتراضية الآن هي
false: لم تعد الحقول تحتوي على مفتاح تبديل ما لم تضبط"switch": trueصراحةً - أيقونة عين مرئية: بدلًا من منطقة نقر مخفية على الجانب الأيسر، يظهر زر بأيقونة عين في منطقة التسمية
- طبقة تعطيل: عند تعطيل حقل، تظهر طبقة ضبابية تتضمن النص "This field is disabled" بدلًا من خفض التعتيم فقط
الترحيل
إذا كنت تعتمد على سلوك التبديل الافتراضي في v6، فعليك تفعيله صراحةً:
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
إذا سبق أن ضبطت "switch": false لتعطيل مفتاح التبديل، فيمكنك حذفه لأن false هي القيمة الافتراضية الآن.
Tailwind CSS
يستبدل Blockstudio 7 نهج v6 Tailwind بالكامل. في v6، كان يُجمّع Tailwind CSS على جانب العميل عبر CDN في المحرر ويُحفظ على القرص عند حفظ المقالة. أما في v7، فيُجمّع Tailwind CSS على جانب الخادم مع كل طلب للواجهة الأمامية عبر TailwindPHP مع تخزين مؤقت تلقائي قائم على الملفات.
للاطلاع على التفاصيل الكاملة للنظام الجديد، راجع توثيق Tailwind CSS.
الترجمة من جهة الخادم دائمًا
عندما تكون قيمة tailwind.enabled هي true، يُترجم كل طلب للواجهة الأمامية من جهة الخادم. تسلسل الترجمة:
- يعرض WordPress الصفحة كاملة HTML في مخزن إخراج مؤقت
- تُستخرج مرشحات أصناف CSS من HTML (بتعبير نمطي سريع، دون ترجمة)
- تُرتب المرشحات وتُجزّأ مع إعداد CSS لإنشاء مفتاح ذاكرة التخزين المؤقت
- عند إصابة ذاكرة التخزين المؤقت: يُقرأ ملف CSS المخزن مؤقتًا ويُدرج
- عند عدم الإصابة: يترجم TailwindPHP ملف CSS، ويكتبه في ذاكرة التخزين المؤقت المشتركة لوقت التشغيل الخاصة بـBlockstudio ضمن النطاق
tailwind، ثم يُدرجه
يُدرج CSS المترجم كوسم <style id="blockstudio-tailwind"> مضمن قبل </head>. ويشمل ذلك إعداد Tailwind المسبق وجميع أصناف الأدوات المطابقة.
يبقى البرنامج النصي CDN نشطًا في المحرر للمعاينة المباشرة فقط. ولا يُقدّم مطلقًا على الواجهة الأمامية.
تغيّر تنسيق config
تغيّرت خاصية config من كائن JSON (Tailwind v3) إلى سلسلة CSS (صياغة Tailwind v4 التي تبدأ بـCSS).
قبل (v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
بعد (v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
إزالة إعداد customClasses
أُزيل إعداد المصفوفة customClasses. مع نهج Tailwind v4 الذي يبدأ بـCSS، تُعرّف أصناف الأدوات المخصصة مباشرةً في سلسلة config باستخدام @layer utilities.
قبل (v6):
{
"tailwind": {
"customClasses": [
{ "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
{ "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
]
}
}
بعد (v7):
{
"tailwind": {
"config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
}
}
أو عبر المرشح للإعدادات متعددة الأسطر:
add_filter('blockstudio/settings/tailwind/config', function () {
return <<<CSS
@layer utilities {
.btn { @apply px-4 py-2 rounded-lg font-medium; }
.card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
أُزيل أيضًا المرشح blockstudio/settings/tailwind/custom_classes. استخدم المرشح blockstudio/tailwind/css بدلًا منه لإلحاق قواعد CSS مخصصة.
إزالة نقطة النهاية REST
أُزيلت نقطة النهاية POST /blockstudio/v1/editor/tailwind/save. لم يعد يُحفظ CSS المترجم من المحرر. إذا كان لديك كود مخصص يستدعي نقطة النهاية هذه، فيمكنك حذفه بأمان.
التخزين المؤقت
يستخدم Blockstudio استراتيجية تخزين مؤقت قائمة على المرشحات. فبدلًا من تجزئة HTML الصفحة كاملة (ما سيؤدي إلى إبطال ذاكرة التخزين المؤقت عند كل طلب بسبب قيم nonce والطوابع الزمنية)، لا تُجزّأ سوى مرشحات الأصناف CSS. وهذا يعني:
- تشترك صفحتان لهما أصناف CSS نفسها في الملف المخزن مؤقتًا نفسه
- لا يؤدي المحتوى الديناميكي (قيم nonce وأشرطة الإدارة والطوابع الزمنية) إلى إبطال ذاكرة التخزين المؤقت
- لا تُبطل ذاكرة التخزين المؤقت إلا عند تغيّر مجموعة أصناف CSS أو تغيّر الإعدادات
تستخدم ملفات ذاكرة التخزين المؤقت جذر وقت التشغيل Blockstudio المُعدّ ضمن
sites/{network-blog}/{runtime-identity}/tailwind/. استدعِ
Blockstudio\Runtime_Cache::purge('tailwind') لفرض إعادة الترجمة.
تغييرات المرشحات
| الاسم القديم (v6) | الاسم الجديد (v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
أُزيل |
blockstudio/settings/tailwind/custom_classes |
أُزيل |
الملفات وعمليات الإضافة إلى قائمة التحميل التي أُزيلت
في v6، كان يُدرج Tailwind CSS كأوراق أنماط خارجية (blockstudio-tailwind، blockstudio-tailwind-preflight). أما في v7، فتُحقن جميع CSS مباشرةً عبر مخزن مؤقت للمخرجات. ولا توجد وسوم روابط أو أوراق أنماط مُدرجة لـ Tailwind في الواجهة الأمامية.
مكتبة الكتل
أُزيلت مكتبة “Blockstudio Elements” المضمنة. ولم يعد لإعداد library في blockstudio.json والمرشح blockstudio/settings/library أي تأثير.
إذا كنت تستخدم كتل المكتبة (المعرض، وشرائح العرض، ومقارنة الصور، والتعليمات البرمجية، والأيقونة)، فانسخ مجلدات الكتل من دليل includes/library/blockstudio-element/ في تثبيت v6 إلى دليل blockstudio في قالبك، وحدّث ملفات block.json الخاصة بها بأسماء وفئات جديدة.