التسجيل
إنشاء كتل خاصة بك باستخدام Blockstudio سهل للغاية. يبحث المكوّن الإضافي عن مجلد blockstudio داخل القالب النشط حاليًا. وسيُسجّل جميع المجلدات الفرعية التي تحتوي على ملف block.json يتضمن المفتاح blockstudio.
block.json
{
"name": "blockstudio/native",
"title": "Native Block",
"category": "text",
"icon": "star-filled",
"description": "Native Blockstudio block.",
"blockstudio": true
}
القالب
لن تُسجّل الكتلة المخصصة بعد لأنها تفتقر إلى قالب. لإصلاح ذلك، أنشئ ملف index.php في المجلد نفسه الذي يوجد فيه ملف block.json، وسيُعرض محتواه تلقائيًا عند استخدام الكتلة.
<h1>My first native block.</h1>
المنطق الشرطي
يمكن تسجيل الكتل بشكل مشروط باستخدام المفتاح conditions. وهو يدعم جميع المتغيرات العامة المتاحة أيضًا للسمات.
لن يسجّل المثال التالي الكتلة إلا إذا كان نوع المنشور الحالي صفحة:
{
"blockstudio": {
"conditions": [
[
{
"type": "postType",
"operator": "==",
"value": "page"
}
]
]
}
}
تبعيات المكوّنات الإضافية
يمكن للكتل الاعتماد على مكوّنات WordPress الإضافية النشطة باستخدام المفتاح pluginDependencies. وإذا لم يكن أحد المكوّنات الإضافية المدرجة نشطًا، فسيتم تخطي الكتلة أثناء التسجيل.
تستخدم التبعيات معرّفات المكوّنات الإضافية WordPress:
{
"blockstudio": {
"pluginDependencies": [
"woocommerce",
"advanced-custom-fields"
]
}
}
استخدم صيغة الكائن لطلب إصدار من مكوّن إضافي. تستخدم قيود الإصدار المعاملات نفسها التي يستخدمها PHP في version_compare()؛ ويُعامل الإصدار الذي لا يسبقه معامل على أنه >=.
{
"blockstudio": {
"pluginDependencies": {
"woocommerce": {
"version": ">6"
}
}
}
}
أيقونة مخصصة
يمكن تسجيل أيقونات SVG مخصصة للكتل كما يلي:
{
"blockstudio": {
"icon": "<svg></svg>"
}
}
لا يسمح WordPress بأيقونات SVG مخصصة في مفتاح block.json icon الخاص به، بل يُسمح فقط بمعرّفات Dashicons.
كتل WordPress القياسية
يسجّل Blockstudio تلقائيًا أيضًا كتل WordPress القياسية الموجودة في مجلدات Blockstudio لديك. ويُسجّل عبر آلية register_block_type() الأصلية في WordPress أي ملف block.json لا يحتوي على المفتاح blockstudio لكنه يتضمن الخاصية name الصالحة.
هذا يعني أنه يمكنك وضع الكتل التي أنشأها @wordpress/create-block مباشرةً في مجلد blockstudio/، وستُسجّل تلقائيًا إلى جانب كتل Blockstudio. لا حاجة إلى كود تسجيل منفصل للمكوّن الإضافي.
blockstudio/
├── hero/
│ ├── block.json ← Blockstudio block (has "blockstudio" key)
│ └── index.twig
├── my-js-block/
│ ├── block.json ← Standard WP block (no "blockstudio" key)
│ ├── index.js ← Compiled editor script
│ ├── index.css
│ ├── style-index.css
│ └── render.php
أنشئ كتلتك باستخدام npx wp-scripts build، ثم انقل مجلد الإخراج إلى دليل Blockstudio. وسيتم تسجيلها تلقائيًا.
وينطبق الأمر نفسه على الكتل المقتصرة على PHP في الإصدار 7.0 من WordPress:
لا تحتاج block.json مع دعم autoRegister وrender.php إلى نص برمجي أو عملية بناء، ويمكن تسجيلها هنا مثل أي كتلة قياسية أخرى. يقصر النظام الأساسي هذا المسار على الكتل البسيطة ذات السمات النصية أو الصحيحة أو المنطقية أو التعدادية؛ فإذا احتاجت الكتلة إلى كتل داخلية أو نص منسق أو وسائط أو عناصر تحكم مخصصة، فأنشئ كتلة من جهة العميل أو امنحها مفتاح blockstudio والتزم بـ PHP.
HTML
يستخدم Blockstudio محلّل عناصر React لعرض عنصر الأيقونة، لذا يمكن استخدام HTML داخل نص الأيقونة.
{
"blockstudio": {
"icon": "<div>:-)</div>"
}
}
مسارات مخصصة
افتراضيًا، يبحث Blockstudio تكراريًا في مجلد blockstudio داخل القالب الحالي أو القالب الفرعي عن الكتل. ويمكنك تغيير هذا السلوك بطريقتين.
مرشح
// Custom path within your theme.
add_filter('blockstudio/path', function () {
return get_template_directory() . '/blocks';
});
// Custom path within a plugin.
add_filter('blockstudio/path', function () {
return WP_PLUGIN_DIR . '/my-custom-plugin/blocks';
});
في أنظمة الملفات المركّبة أو الافتراضية، استخدم مصدر اكتشاف منطقيًا بدلًا من إضافة مسارات مستقلة للمجلد الأصلي وطبقة التجاوز. تدعم المصادر المنطقية التجاوز حسب المسار، ووراثة الملفات الشقيقة، والحذف، وهوية الذاكرة المؤقتة، ومصدر الملفات. راجع مصادر الاكتشاف المنطقية.
النسخ
إذا لم تكن الخيارات أعلاه كافية، يمكنك إنشاء نسخة من الصنف Blockstudio\Build في مجلدات مختلفة تختارها:
add_action('init', function () {
Blockstudio\Build::init([
'dir' => get_template_directory() . '/client-blocks'
]);
});
بيانات المرشح الوصفية
يمكن ترشيح البيانات الوصفية قبل تسجيل الكتلة باستخدام المرشح blockstudio/blocks/meta:
add_filter('blockstudio/blocks/meta', function ($meta, $block) {
if (str_starts_with($block['name'], 'marketing')) {
$meta['icon'] = 'megaphone';
}
return $meta;
}, 10, 2);
يُستخدم المثال أعلاه داخليًا لمنح جميع عناصر مكتبة Blockstudio الأيقونة نفسها.