الترحيل من ACF Blocks
إذا كنت تنشئ كتل WordPress مخصصة باستخدام ACF (Advanced Custom Fields)، فالانتقال إلى Blockstudio سهل. المفاهيم متشابهة: تعرّف الحقول وتكتب قالبًا، فتظهر الكتلة في المحرر. يكمن الاختلاف في أن Blockstudio يكتشف مجلدات الكتل تلقائيًا، ويعرّف الحقول في مخططه الخاص داخل block.json، ويزوّد كل قالب بقيم حقوله ضمن مصفوفة واحدة من $a.
يشرح هذا الدليل عملية الانتقال خطوة بخطوة، مع مقارنات جنبًا إلى جنب بين أنماط ACF وBlockstudio.
الاختلاف الجوهري
منذ ACF 6.0، تكون كتلة ACF عبارة عن block.json بمفتاح acf يحدد قالب العرض، ويُسجّل كل مجلد كتلة باستدعاء register_block_type() خاص به. تأتي الحقول من مجموعة حقول مرتبطة بالكتلة بقاعدة تحديد موقع Block (تُنشأ في لوحة الإدارة، أو تُزامن عبر Local JSON، أو تُسجّل باستخدام acf_add_local_field_group())، أو، منذ ACF PRO 6.8.1، من مصفوفة acf.fields مضمنة في ملف block.json نفسه. يستبدل Blockstudio استدعاء التسجيل بالاكتشاف التلقائي القائم على الملفات: أنشئ مجلدًا يحتوي على block.json وindex.php، وسيُسجّل البلوك تلقائيًا.
ACF:
{
"name": "acf/hero",
"title": "Hero",
"acf": {
"renderTemplate": "template.php"
}
}
add_action( 'init', function () {
register_block_type( __DIR__ . '/blocks/hero' );
} );
acf_add_local_field_group([
'key' => 'group_hero',
'title' => 'Hero Fields',
'fields' => [
['key' => 'field_title', 'name' => 'title', 'type' => 'text', 'label' => 'Title'],
['key' => 'field_image', 'name' => 'image', 'type' => 'image', 'label' => 'Background', 'return_format' => 'array'],
],
'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);
<?php
$title = get_field('title');
$image = get_field('image');
?>
<div class="hero" <?php if ($image) : ?>style="background-image: url(<?php echo esc_url($image['url']); ?>)"<?php endif; ?>>
<h1><?php echo esc_html($title); ?></h1>
</div>
Blockstudio:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "image", "type": "files", "label": "Background", "multiple": false }
]
}
}
<div useBlockProps class="hero" <?php if ($a['image']) : ?>style="background-image: url(<?php echo esc_url($a['image']['url']); ?>)"<?php endif; ?>>
<h1><?php echo esc_html($a['title']); ?></h1>
</div>
لا حاجة إلى استدعاء تسجيل أو دالة عرض: بنية المجلد هي التسجيل، وتوجد الحقول في block.json بجوار القالب. يستخدم القالب $a بدلًا من استدعاء get_field().
تسجيل الكتل
ACF
تُسجّل كتل ACF الحالية انطلاقًا من block.json بمفتاح acf (renderTemplate أو renderCallback، بالإضافة إلى خيارات مثل blockVersion)، ويُحمّلها استدعاء register_block_type() صريح لكل مجلد كتلة، عادةً في init ضمن functions.php أو ملف إضافة. قد تستخدم الكتل الأقدم acf_register_block_type()، التي توثق ACF أنها مهملة منذ ACF 6.0؛ وهي ما تزال تعمل، لذا انقل هذه الكتل بالطريقة نفسها.
Blockstudio
أنشئ مجلدًا في دليل blockstudio/ الخاص بقالبك (أو في blocks/ إن رغبت). أضف ملف block.json يتضمن البيانات الوصفية القياسية لكتلة WordPress بالإضافة إلى مفتاح blockstudio. هذا كل ما في الأمر.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
يستخدم block.json تنسيق WordPress block.json القياسي مع المفتاح blockstudio للحقول والإعدادات:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
الوصول إلى قيم الحقول
هذا هو التغيير الأكثر شيوعًا الذي ستجريه أثناء الانتقال.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (متاح دائمًا) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
المتغير $a اختصار لـ$attributes ويحتوي على جميع قيم حقول الكتلة الحالية. وهو متاح دائمًا في القالب، سواء في المحرر أو الواجهة الأمامية.
متغيرات القالب
يوفر Blockstudio عدة متغيرات في كل قالب:
| المتغير | الاختصار | الوصف |
|---|---|---|
$attributes |
$a |
جميع قيم الحقول |
$block |
$b |
بيانات الكتلة الوصفية (الاسم والعنوان والدليل والرابط ومعرّف المنشور) |
$context |
$c |
سياق الكتلة الأصلية |
$content |
محتوى InnerBlocks | |
$post_id |
معرّف المنشور الحالي (يعمل في المحرر والواجهة الأمامية؛ post_id أو postId في Twig) |
مواءمة أنواع الحقول
معظم أنواع حقول ACF لها مقابل مباشر في Blockstudio. تختلف صيغة JSON، لكن المفاهيم تتوافق بسهولة.
حقول النص والمحتوى
ACF:
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']
Blockstudio:
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }
لإتاحة تحرير النص في محرر الكتل، وليس مجرد إدخاله في حقل نصي، استخدم النوع richtext مع مكوّن <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
حقول الصور والملفات
يتوافق حقلا image وfile في ACF مع النوع files في Blockstudio:
ACF:
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']
Blockstudio:
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true }
{ "id": "document", "type": "files", "label": "Document", "multiple": false, "allowedTypes": ["application/pdf"] }
بنية الكائن المُعاد مشابهة:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
الخصائص المتاحة: ID، title، alt، caption، description، href، url، sizes. الأبعاد بوحدة sizes، مثلًا $a['photo']['sizes']['full-width'].
القوائم المنسدلة وأزرار الاختيار ومربعات الاختيار
ACF:
[
'name' => 'color',
'type' => 'select',
'choices' => ['red' => 'Red', 'blue' => 'Blue'],
'return_format' => 'value',
]
Blockstudio:
{
"id": "color",
"type": "select",
"label": "Color",
"options": [
{ "value": "red", "label": "Red" },
{ "value": "blue", "label": "Blue" }
]
}
استخدم "returnFormat": "both" للحصول على القيمة والتسمية معًا:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
ينطبق النمط نفسه على النوعين radio وcheckbox.
التبديل والقيم المنطقية
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
حقل الرابط
ACF:
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']
// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];
Blockstudio:
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];
اللون والتدرج
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
يتكامل النوع color مع لوحة الألوان WordPress. ويوفر النوع gradient أداة لاختيار التدرج.
الرقم والنطاق والتاريخ
ACF:
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']
Blockstudio:
{ "id": "count", "type": "number", "label": "Count", "min": 1, "max": 10 }
{ "id": "opacity", "type": "range", "label": "Opacity", "min": 0, "max": 100, "step": 5 }
{ "id": "eventDate", "type": "date", "label": "Event Date" }
الحقول المكررة
يتوافق حقل التكرار في ACF مباشرةً مع النوع repeater في Blockstudio. عادةً ما تكرّر قوالب ACF باستخدام have_rows() / the_row() / get_sub_field() (كما يعيد get_field() في حقل التكرار مصفوفة من الصفوف)؛ أما Blockstudio فلا يحتوي إلا على مصفوفة PHP عادية، مرتبة مسبقًا في $a.
ACF:
['name' => 'features', 'type' => 'repeater', 'sub_fields' => [
['name' => 'title', 'type' => 'text'],
['name' => 'description', 'type' => 'textarea'],
]]
// Template
if (have_rows('features')) :
while (have_rows('features')) : the_row();
echo get_sub_field('title');
echo get_sub_field('description');
endwhile;
endif;
Blockstudio:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 10,
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<?php foreach ($a['features'] as $feature) : ?>
<h3><?php echo esc_html($feature['title']); ?></h3>
<p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>
تدعم الحقول المكررة في Blockstudio التداخل حتى 3 مستويات.
المجموعات
يتوافق حقل المجموعة في ACF مع النوع group في Blockstudio. وتُسبق معرّفات الحقول داخل المجموعات بمعرّف المجموعة.
ACF:
['name' => 'author', 'type' => 'group', 'sub_fields' => [
['name' => 'name', 'type' => 'text'],
['name' => 'role', 'type' => 'text'],
]]
// Template
$author = get_field('author');
echo $author['name'];
echo $author['role'];
Blockstudio:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" }
]
}
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>
تزيل الأداة المساعدة bs_get_group() بادئة المجموعة من معرّفات الحقول لتسهيل الوصول إليها. ومن دونها، ستصل إلى الحقول بصيغة $a['author_name'] و$a['author_role'].
المنطق الشرطي
يدعم كل من ACF وBlockstudio المنطق الشرطي لإظهار الحقول وإخفائها استنادًا إلى قيم حقول أخرى.
ACF:
['name' => 'showSubtitle', 'type' => 'true_false'],
[
'name' => 'subtitle',
'type' => 'text',
'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]
Blockstudio:
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
"id": "subtitle",
"type": "text",
"label": "Subtitle",
"conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}
تشير شروط Blockstudio إلى معرّفات الحقول مباشرةً، لا إلى مفاتيحها. العوامل المتاحة: == و!= وincludes و!includes وempty و!empty و< و> و<= و>=.
يدعم Blockstudio أيضًا شروطًا عامة تستند إلى نوع المنشور ومعرّفه ودور المستخدم ومعرّف المستخدم:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
يدعم كل من ACF وBlockstudio كتل InnerBlocks لإدراج كتل أخرى داخل كتلتك المخصصة، باستخدام وسم <InnerBlocks /> نفسه والسمات allowedBlocks وtemplate وtemplateLock نفسها، لذا ينتقل هذا الجزء من القالب عادةً دون تغيير.
Blockstudio:
<div useBlockProps class="my-wrapper">
<InnerBlocks
allowedBlocks='<?php echo esc_attr(wp_json_encode(["core/heading", "core/paragraph", "core/image"])); ?>'
template='<?php echo esc_attr(wp_json_encode([
["core/heading", ["placeholder" => "Section title"]],
["core/paragraph", ["placeholder" => "Section content"]]
])); ?>'
templateLock="insert"
/>
</div>
يُستبدل الوسم <InnerBlocks /> بمكوّن React في المحرر وبمحتوى الكتلة المعروض في الواجهة الأمامية.
تخزين بيانات المنشور الوصفية
يخزّن كل من ACF Blocks وBlockstudio قيم الحقول افتراضيًا كسمات للكتل في محتوى المقالة، وليس في البيانات الوصفية للمقالة. وهذا يعني أن قيم الحقول لا يمكن الاستعلام عنها باستخدام WP_Query ما لم تختر تخزينها في البيانات الوصفية.
أضافت ACF خيار تخزين بيانات المنشور الوصفية للكتل في ACF PRO 6.3 عبر usePostMeta: true، لكتلة واحدة في المستوى الأعلى لكل صفحة. أما Blockstudio فيتيح تفعيل ذلك لكل حقل باستخدام الخاصية storage:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
يُسجّل show_in_rest مفتاح البيانات الوصفية تلقائيًا. ويمكن الوصول إليه من أي مكان باستخدام get_post_meta($post_id, 'is_featured', true).
للقيم المستخدمة على مستوى الموقع كله، مثل صفحات خيارات ACF، استخدم تخزين الخيارات:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
توسيع الكتل الموجودة
تربط قاعدة تحديد الموقع Block في ACF مجموعات الحقول بكتل ACF فقط؛ ولا تضيف حقولًا إلى الكتل الأساسية أو التابعة لجهات خارجية. وتتمثل طريقة ACF لإضافة حقول إلى الكتل الأساسية، مثل العنوان والفقرة والصورة والزر، في WordPress Block BindingsAPI، الذي يربط سمات الكتل الموجودة بقيم حقول ACF. ويمكن لـBlockstudio إضافة حقول وعناصر تحكم جديدة إلى أي كتلة مسجّلة عبر ملفات التوسعة.
أنشئ ملف توسعة في دليل blockstudio لديك:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
تطبّق الخاصية set قيمة الحقل تلقائيًا على HTML الخاص بالكتلة. استخدم أحرف البدل لتوسيع عدة كتل دفعة واحدة: "name": "core/*".
قائمة التحقق للانتقال
- أنشئ مجلد الكتلة في
theme/blockstudio/{block-name}/معblock.jsonوindex.php. - انقل تعريفات الحقول من مجموعة حقول الكتلة (Local JSON أو
acf_add_local_field_group()أو مصفوفةacf.fieldsمضمنة) إلى مصفوفةblockstudio.attributesفيblock.json. غيّرnameإلىid، وأزلkey، وعدّل أسماء الأنواع عند الحاجة. - حدّث الوصول إلى القالب من
get_field('name')إلى$a['name']. واستبدل حلقاتhave_rows()بـforeach ($a['repeater'] as $item). - استبدل
get_sub_field()بالوصول المباشر إلى المصفوفة:$item['fieldId']. - أضف
useBlockPropsإلى العنصر الخارجي في القالب لدمج المحرر على النحو الصحيح. - انقل المنطق الشرطي من
conditional_logicفي ACF إلىconditionsفي Blockstudio، مع استخدام معرّفات الحقول بدلًا من مفاتيحها. - أضف التخزين لأي حقول كان يُستعلم عنها سابقًا باستخدام
get_post_meta()أو تُستخدم فيWP_Query. - أزل كود تسجيل ACF: استدعاءات
register_block_type()ومفاتيحacfللكتل التي نقلتها (أو استدعاءاتacf_register_block_type()الخاصة بها)، ومجموعات حقولها، سواء كانت في Local JSON أوacf_add_local_field_group()أو مصفوفةacf.fieldsمضمنة أو في لوحة الإدارة. - اختبر في المحرر للتحقق من ظهور الحقول على نحو صحيح، ثم افحص مخرجات الواجهة الأمامية.