عرض السمات
يمكن الوصول إلى جميع السمات داخل ملفات القوالب باستخدام متغيري $attributes أو $a ومعرّف الحقل المعني.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
كتابة السمات برمجيًا
يضع المحرر القيم المحفوظة ضمن blockstudio.attributes. أما أي جهة تكتب كتلة خارج المحرر، مثل REST API أو WP-CLI أو عملية ترحيل المحتوى أو خادم MCP، فتحدد الكتلة من السمات التي يسجلها Blockstudio على WP_Block_Type وتكتبها في المستوى الأعلى. تعمل الصيغتان عند العرض:
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
لا تُقرأ من المستوى الأعلى إلا المعرّفات التي تعلن عنها الكتلة، لذلك لا تُعتمد أبدًا سمات WordPress نفسه، مثل anchor وclassName وlock وmetadata وstyle، كقيم للحقول. إذا ظهر المعرّف نفسه في الموضعين، فتكون الأولوية للقيمة المتداخلة.
قراءة السمات برمجيًا
غالبًا ما تحتاج التعليمات البرمجية التي تعمل خارج القالب، مثل البيانات المنظّمة على save_post، أو عمليات التصدير أو فهرسة البحث أو عامل التصفية render_block، إلى قيم الكتلة المحفوظة كما يراها القالب. تعيد bs_block_values() هذه القيم دون عرض الكتلة. استدعِها بعد تسجيل الكتلة (init أو بعده) مع مصفوفة attrs الكاملة من parse_blocks():
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
النتيجة هي مصفوفة القالب $a، ومفاتيحها معرّفات الحقول:
- تُطبَّق القيم الافتراضية للحقول، ويحتوي حقل المكرّر الذي يتضمن
minعلى صفوفه الأولية. - تُدمج القيم العليا المستوى مع
blockstudio.attributes، وتكون الأولوية للقيمة المتداخلة. لا تُقرأ من المستوى الأعلى إلا المعرّفات المُعلنة، ويزيل WordPress القيمة العليا المستوى التي لا تطابق النوع المسجّل للحقل، مثل سلسلة نصية لقائمة منسدلة، تمامًا كما يحدث عند العرض. - تُضمَّن حقول الامتدادات المطابقة مع قيمها الافتراضية. أما امتداد كتلة أساسية أو تابعة لجهة خارجية فيقرأ
blockstudio.attributesفقط، كما يحدث عند العرض. - تُطبَّق تنسيقات الإرجاع، لذا فإن القائمة المنسدلة التي لها
returnFormatبقيمةlabelتُرجع التسمية، ويُرجع حقل الملفات بيانات المرفقات. - تكون الحقول المعطّلة والفارغة
false، كما في القالب.
يعني null أن الكتلة والامتداد غير مُدارين بواسطة Blockstudio. تُرجع كتلة Blockstudio بلا حقول [].
تُجري الدالة التحويل نفسه الذي يجريه العرض، لذا لها الآثار الجانبية نفسها: تستعلم حقول الملفات عن المرفقات، ويُعرض حقل الكتلة الذي لا يُرجع data الكتلة المشار إليها، ويُشغَّل عامل التصفية blockstudio/blocks/attributes/render لكل قيمة. لا تعرض الدالة قالب الكتلة نفسه ولا تحل innerBlocks؛ لذا عليك اجتيازها بنفسك. يحتفظ حقل التعليمات البرمجية بمعرّف %selector% مُنشأ يختلف بين الاستدعاءات.
يعتمد الحل على سياق WordPress الحالي. لا تُنشأ البيانات الوصفية الخاصة بالعرض فقط، مثل عدّادات الكتل وinnerBlocks؛ وتتلقى عوامل تصفية عرض السمات اسم الكتلة، لا البيانات الوصفية لكتلة معروضة بالكامل.
لا يوجد خيار للحصول على القيم المخزّنة دون التحويل. اقرأ مصفوفة attrs مباشرةً للحصول عليها، أو استخدم bs_validate_block() للتحقق منها.
القيم الفارغة
تعيد قيم السمات false إذا كان الحقل فارغًا أو لم يُحدد أي خيار.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
الأنواع المركبة
الملفات
افتراضيًا (من دون returnFormat أو مع "returnFormat": "object")، يُرجع حقل الملفات مصفوفة تحتوي على بيانات المرفق. ومع "multiple": true، يُرجع قائمة من هذه المصفوفات. يكون الملف الذي لم يعد مرفقه موجودًا false.
| المفتاح | الوصف |
|---|---|
ID |
معرّف المرفق. |
title |
عنوان المرفق. |
alt |
النص البديل. يُستخدم عنوان المرفق بديلًا عنه إذا كان فارغًا. |
caption |
التسمية التوضيحية. |
description |
الوصف. |
href |
الرابط الدائم لصفحة المرفق. |
url |
URL الملف. مع قائمة اختيار الحجم ("size": true)، يكون URL للحجم المحدد. |
sizes |
URL وأبعاد كل حجم صورة مسجّل، انظر أدناه. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
يحتوي sizes على إدخال لكل حجم صورة مسجّل بالإضافة إلى full: URL تحت اسم الحجم، والأبعاد تحت <size>-width و<size>-height. إذا لم يُنشئ حجم WordPress مرفقًا، فسيُحلّ إلى الملف الأصلي بأبعاده. إذا تعذّر على WordPress تحديد صورة أو معاينة، فسيكون المفتاح sizes غائبًا. على سبيل المثال، لا يتضمن ملف PDF بلا معاينة مُنشأة sizes، لكن قد يتضمن ملف PDF ذي بيانات معاينة وصفية أحجامًا للصور. تكون sizes هي null عند عدم تسجيل أي أحجام للصور أو عند تعطيلها بواسطة مرشح files/sizesالمرشح. يمكن لهذا المرشح أيضًا تقصير الخريطة، لذا تحقّق من وجود الحجم قبل قراءة أبعاده، كما في الأمثلة أعلاه.
لا يتضمن الكائن مفاتيح width أو height أو mime أو type أو size. اقرأ الأبعاد من sizes، أو استخدم ID مع دوال مثل wp_get_attachment_image() وget_post_mime_type().
تنسيقات الإرجاع
يغيّر returnFormat ما يُرجعه الحقل:
returnFormat |
القيمة |
|---|---|
"object" (افتراضي) |
المصفوفة الموضّحة أعلاه. |
"id" |
معرّف المرفق كما هو مخزّن، أو قائمة بالمعرّفات مع "multiple": true. |
"url" |
URL كسلسلة نصية، أو قائمة بعناوين URL مع "multiple": true. تستخدم الصور مجموعة الأحجام المضبوطة بواسطة returnSize (الافتراضي full)، وتستخدم الملفات الأخرى URL الملف. |
الرابط
يعيد حقل الرابط كائنًا يحتوي على URL والسمات:
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
الأيقونة
يعيد حقل الأيقونة كائنًا يحتوي على المفاتيح set وsubSet وicon. استخدم الدالتين المساعدتين bs_render_icon() وbs_icon() لإخراج SVG:
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
تُخرج bs_render_icon() SVG مباشرةً، بينما تعيده bs_icon() كسلسلة نصية.
السمات
يعيد نوع حقل السمات مصفوفة من أزواج {attribute, value} لعرضها كسمات HTML. استخدم bs_render_data_attributes() لإخراجها:
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
تُخرج bs_render_data_attributes() السمات مباشرةً، بينما تعيدها bs_data_attributes() كسلسلة نصية.
المجموعة
تضيف حقول المجموعات اسم المجموعة كبادئة إلى معرّفات السمات التابعة لها. استخدم bs_get_group() لاستخراج حقول المجموعة في مصفوفة واضحة:
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
يزيل هذا بادئة المجموعة من مفاتيح السمات. على سبيل المثال، يصبح $a['settings_title'] $group['title'].
يعمل هذا الدليل المساعد أيضًا عندما تأتي المجموعة من حقل مخصص معاد الاستخدام:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
الحقل المكرر
كرّر على عناصر الحقل المكرر:
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}