انتقل إلى المحتوى

عرض السمات

يمكن الوصول إلى جميع السمات داخل ملفات القوالب باستخدام متغيري $attributes أو $a ومعرّف الحقل المعني.

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>

كتابة السمات برمجيًا

يضع المحرر القيم المحفوظة ضمن blockstudio.attributes. أما أي جهة تكتب كتلة خارج المحرر، مثل REST API أو WP-CLI أو عملية ترحيل المحتوى أو خادم MCP، فتحدد الكتلة من السمات التي يسجلها Blockstudio على WP_Block_Type وتكتبها في المستوى الأعلى. تعمل الصيغتان عند العرض:

PHP
// 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():

PHP
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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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

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
<?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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>

تُخرج bs_render_data_attributes() السمات مباشرةً، بينما تعيدها bs_data_attributes() كسلسلة نصية.

المجموعة

تضيف حقول المجموعات اسم المجموعة كبادئة إلى معرّفات السمات التابعة لها. استخدم bs_get_group() لاستخراج حقول المجموعة في مصفوفة واضحة:

PHP

PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>

يزيل هذا بادئة المجموعة من مفاتيح السمات. على سبيل المثال، يصبح $a['settings_title'] $group['title'].

يعمل هذا الدليل المساعد أيضًا عندما تأتي المجموعة من حقل مخصص معاد الاستخدام:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>

الحقل المكرر

كرّر على عناصر الحقل المكرر:

PHP

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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

وصفات أنماط الحقول