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

تركيب القوالب باستخدام وسوم الكتل

بعد أن يحتوي المشروع على بضع كتل، تبدأ القوالب بالاعتماد بعضها على بعض. تريد كتلة الميزات عرض ثلاث بطاقات، وتحتاج صفحة الهبوط إلى قسم يتضمن زرًا. يمكنك استدعاء bs_render_block() لكل كتلة، لكن القالب المليء باستدعاءات PHP والمصفوفات المتداخلة يصعب قراءته ويصعب إنشاء التداخلات فيه.

تتيح لك وسوم الكتل كتابة الكتلة في الموضع الذي ينبغي أن يظهر فيه ناتجها، على هيئة وسم HTML:

HTML
<bs:acme-card title="Fast" text="Rendered on the server." />

يعني الوسم نفسه أمرين مختلفين بحسب موضع كتابته. ففي قالب كتلة أو في محتوى منشور، يُستبدل بناتج عرض الكتلة HTML. أما في مصدر صفحة أو نمط أو قالب موقع، فيتحول إلى كتلة WordPress حقيقية تظهر في المحرر. ينشئ هذا الدليل بضع كتل ويركبها بالطريقتين، ويضيف بادئة للمشروع لتقصير الأسماء، ثم يوضح كيفية تحويل الصيغ المختصرة إلى الصيغة القابلة للنقل.

الكتل

تكفي ثلاث كتل صغيرة. بطاقة بحقلين:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title", "default": "" },
      { "id": "text", "type": "textarea", "label": "Text", "default": "" }
    ]
  }
}
PHP
<article useBlockProps class="acme-card">
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['text'] ); ?></p>
</article>

قسم يحيط بكل ما يوضع بداخله، مع حقل heading مُعرّف بالطريقة نفسها التي عُرّف بها حقل البطاقة:

PHP
<section useBlockProps class="acme-section">
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <InnerBlocks />
</section>

وزر في مساحة أسماء ثانية، acme-ui/button، مع حقلي label وhref:

PHP
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>

الوسوم داخل قالب كتلة

تعرض قوالب الكتل الوسوم تلقائيًا، ولا يلزم أي إعداد. يمكن لكتلة الميزات عرض بطاقتين وفاصل أساسي مباشرةً:

PHP
<div useBlockProps class="acme-features">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <block name="acme/card" title="Typed" text="Fields come from block.json." />
  <block name="core/separator" />
</div>

ينتج عن عرض acme/features ما يلي:

HTML
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Typed</h3>
  <p>Fields come from block.json.</p>
</article>

  <hr class="wp-block-separator has-alpha-channel-opacity">
</div>

يسبق كل كتلة Blockstudio في المخرجات تعليق <!--blockstudio/namespace/slug-->. يزيله مخزن الصفحة المؤقت من الاستجابة؛ وللمخرجات التي تتجاوز المخزن المؤقت، استخدم bs_strip_render_markers(). الصيغتان متكافئتان. يضمّن <bs:acme-card> اسم الكتلة في الوسم، ويمرره <block name="acme/card"> كخاصية. تصبح كل خاصية أخرى قيمة حقل، لذا تصل title إلى قالب البطاقة بصفتها $a['title']. تعمل الكتل الأساسية أيضًا، إذ تُعرض عبر WordPress باستخدام عارضي الكتل المدمجين.

الوسوم المزدوجة والمحتوى الداخلي

يمرر الوسم المزدوج عناصره الفرعية إلى الكتلة. وفي كتلة Blockstudio، تملأ هذه العناصر <InnerBlocks />، وتُعرض الوسوم المتداخلة أولًا:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
HTML
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
  <h2>Why Acme</h2>
  <div>
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>

</div>
</section>

كيف يتحول اسم الوسم إلى اسم كتلة

لا يحتوي اسم الوسم <bs:> على شرطة مائلة، لذا يبحث Blockstudio عن اسم مناسب. يستبدل كل شرطة بواصل مائل بالتتابع من اليسار إلى اليمين، ويستخدم أول اسم مرشح مسجل. يُحل <bs:acme-card> إلى acme/card من المحاولة الأولى. أما <bs:acme-ui-button> فيجرّب acme/ui-button، فلا يجد شيئًا، ثم يُحل إلى acme-ui/button. لذلك تعمل مساحات الأسماء التي تحتوي على شرطات من دون أي إعداد، ما دام الاسمان المرشحان غير موجودين معًا.

أسماء أقصر باستخدام البادئات

<bs:acme-ui-button> دقيق لكنه طويل. تربط بادئة المشروع بادئة وسم قصيرة بمساحة أسماء واحدة أو أكثر. اضبطها في blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

أو سجّل الخريطة نفسها من PHP:

PHP
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
	$prefixes['acme'] = array( 'acme' );
	$prefixes['ui']   = array( 'acme-ui' );

	return $prefixes;
} );

الآن يُحل <acme-card> إلى acme/card، و<ui-button> إلى acme-ui/button. عندما تسرد البادئة عدة مساحات أسماء، تُجرّب بالترتيب وتُستخدم أول كتلة مسجلة، ما يتيح لكتلة المشروع أن تحجب كتلة مكتبة تحمل المعرّف المختصر نفسه.

يمكن تركيب البادئات أيضًا. يجرّب <acme-ui-button> أولًا acme/ui-button. هذه الكتلة غير موجودة، وبقية الوسم، ui-button، هي نفسها وسم بادئة مسجل، لذا ينتقل الحل إلى acme-ui/button. وتكون المطابقة المباشرة دائمًا لها الأولوية على المطابقة المتداخلة.

HTML
<bs:acme-section heading="Why Acme">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

يعرض هذا ناتج HTML نفسه تمامًا كما في الصيغة القياسية أعلاه.

تنطبق بضع قواعد على البادئات:

  • تتكون البادئة من أحرف صغيرة وأرقام، وتبدأ بحرف، ولا تحتوي على شرطات.
  • إذا لم يُحل وسم ذو بادئة إلى كتلة مسجلة، فيُترك في الناتج كما هو، لذا يبقى <acme-missing title="x" /> على صيغته.
  • تتقدم الأسماء المستعارة الدقيقة من المرشح blockstudio/block_tags/tag_aliases على البادئات. يربط الاسم المستعار وسمًا واحدًا ذا شرطة بكتلة واحدة؛ فمثلًا يجعل $aliases['acme-cta'] = 'acme-ui/button'; الوسم <acme-cta> يعرض الزر.

تُعرض وسوم البادئات والأسماء المستعارة في قوالب الكتل إلى جانب وسوم <bs:> و<block> من الإصدار 7.5 من Blockstudio.

السمات

تصبح الخصائص التي تطابق معرّف حقل قيمًا للحقول. تؤدي بادئتان وظيفة مختلفة:

  • تُنسخ خصائص data-* إلى العنصر الجذر للكتلة المعروضة.
  • تُنسخ خصائص html-* إلى العنصر الجذر بعد إزالة البادئة، لذا تصبح html-id="intro" id="intro".
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<article data-track="card" id="intro" class="featured">
  <h3>Hi</h3>
  <p>There</p>
</article>

يضبط html-class الخاصية ولا يضيف إليها؛ فتُزال فئات acme-card wp-block-acme-card الخاصة بالكتلة. إذا كان ينبغي للجهة المستدعية إضافة فئات إلى كتلة، فأعلن حقلًا لها وادمجه في القالب.

تُحذف أي خاصية أخرى لم تُعرّف كحقل. يؤدي وجود class="wide" عادي على <bs:acme-card> إلى عرض البطاقة من دونه. ويُبلغ Blockstudio 7.7 عن هذه الخصائص بتنبيه _doing_it_wrong() عند تفعيل WP_DEBUG.

الوسوم نفسها في مصادر الصفحات

في الصفحات المعتمدة على الملفات والأنماط وقوالب المواقع، لا تُعرض الوسوم. بل تتحول إلى كتل عند تحليل المصدر، فتظهر في المحرر. يُحلل مصدر الصفحة هذا:

HTML
<bs:acme-section heading="Why Acme">
  <p>Everything below is a real block.</p>
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

إلى ترميز الكتل التالي (أُضيفت فواصل أسطر لتسهيل القراءة):

HTML
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->

توضع قيم الحقول تحت blockstudio.attributes، حيث تحتفظ بها كتل Blockstudio، ويصبح كل من الفقرة والكتلتين الداخليتين كتلة داخلية للقسم. تُحل البادئات والأسماء المستعارة هنا بالطريقة نفسها المتبعة في القوالب.

الوسوم في محتوى المنشورات

لا يُفحص افتراضيًا المحتوى المكتوب في المحرر أو المخزّن في الودجات. فعّل العرض على مستوى الصفحة في blockstudio.json:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

بعد ذلك، تُعرض الوسوم في the_content وwidget_text عند أولوية 5. ويسجل الخيار نفسه مرشحًا لعرض الوسوم في أي سلسلة نصية:

PHP
$html = apply_filters( 'blockstudio/block_tags/render', $content );

قيّد الوسوم التي يمكن عرضها باستخدام نمطي allow وdeny، اللذين يقبلان أحرف البدل fnmatch() وينطبقان على كل الصيغ وكلا نمطي العرض:

JSON
{
  "blockTags": {
    "enabled": true,
    "deny": ["acme-ui/*"]
  }
}

بعد تطبيق هذه القاعدة، يُترك <acme-ui-button> و<bs:acme-ui-button> في الناتج دون عرض. وتكون الأولوية لـdeny على allow. ويغيّر المرشحان blockstudio/block_tags/allow وblockstudio/block_tags/deny القائمتين نفسيهما من PHP.

يتحقق التحليل من الصيغة القياسية

يتحقق امتداد PHPStan من وسوم الكتل في قوالب PHP وTwig وBlade. ويُبلّغ عن اسم حقل أو كتلة مكتوب خطأ مع اسم الكتلة التي حُلّ إليها:

Text
  3      Block tag "acme/card" has unknown attribute "txt" in index.php
         🪪  blockstudio.blockTag.attribute
  4      Block tag references unknown block "acme/cards" in index.php
         🪪  blockstudio.blockTag.unknown

في الإصدار 7.6، يشمل ذلك وسوم <bs:> و<block>. أما وسم البادئة مثل <acme-card txt="..."> فيُتجاوز دون تحقق. ويوسع Blockstudio 7.7 القاعدة لتشمل وسوم البادئات ومصادر الصفحات وعناصر HTML المعيّنة، كما تعرض تلميحاته الخصائص العامة التي يمكن للوسم تمريرها.

تحويل الصيغ المختصرة إلى الصيغة القياسية

وسوم البادئات والأسماء المستعارة تسهّل العمل داخل المشروع. ولا تُحل إلا عند تحميل مرشحات المشروع وإعداداته، لذا يفقد قالب منسوخ إلى مشروع آخر أو مكتبة كتل أو سياق وكيل برمجي معناه. يسجل <bs:namespace-slug> اسم الكتلة الحقيقي ويُحل في أي مكان، ولهذا تستخدمه أمثلة Blockstudio نفسها وتشخيصاتها ومخرجاتها المُنشأة.

يعيد أمر مستقل كتابة الصيغ المختصرة بهذه الصيغة. افترض مشروعًا لا تزال مصادره تستخدم الصيغ القصيرة، بما فيها اسم مستعار ووسم لكتلة لم تعد موجودة ومثال داخل مقطع برمجي:

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <acme-card title="Example" /></code></pre>

لا يحمّل الأمر WordPress، لذا يأخذ إعدادات المشروع من ملفات JSON المحفوظة خارج شجرة الملفات المفحوصة:

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

ابدأ بتشغيل تجريبي، وهو الوضع الافتراضي أيضًا:

سطر الأوامر
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/acme-tags/prefixes.json \
  --known-blocks=/tmp/acme-tags/blocks.json \
  --aliases=/tmp/acme-tags/aliases.json \
  --report=/tmp/acme-tags/report.json \
  --dry-run
Text
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.

يسرد التقرير كل تعيين سيطبقه وكل حالة لن يخمّن بشأنها:

JSON
{
  "mappings": [
    { "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
    { "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
    { "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
    { "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
  ],
  "unknown": [
    { "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
  ],
  "manual": [
    { "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
  ]
}

التقرير مختصر هنا. كما يسجل الإعدادات وبصمات الملفات قبل التغيير وبعده. ويُحتسب وسما فتح القسم وإغلاقه كموضعين. يطابق acme-quote بادئة acme لكنه لا يسمي أي كتلة معروفة، لذا فهو مجهول. أما acme-card داخل <pre><code> فهو مثال لا ترميز، لذلك يُدرج للمراجعة اليدوية ولا يُعادَت كتابته مطلقًا؛ وينطبق الأمر نفسه على التعليقات HTML والشفرة المضمنة.

يُرفض التطبيق ما دامت هناك وسوم مجهولة أو ملتبسة أو ديناميكية:

Text
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.

ينتهي الأمر بالرمز 2. أصلح الوسم المجهول، بإزالته هنا، وشغّل الأمر باستخدام --apply بدلًا من --dry-run:

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

تتغير أسماء الوسوم وحدها. وتُحفظ الخصائص بايتًا ببايت:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>

يؤدي تشغيل الوضع التجريبي مجددًا على النتيجة إلى الإبلاغ عن 0 changed, 0 replacements. ويمكن إبقاء البادئات مسجلة بعد ذلك، فلا يتعطل شيء بينما تظل فروع أخرى تستخدم الصيغة القصيرة.

الخطوات التالية