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

useBlockProps

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

الاستخدام

أضف السمة useBlockProps ببساطة إلى العنصر الجذر في كتلتك.

PHP
<div useBlockProps class="my-class">
  <!--
  This element will be rendered
  as the root element of your block
  in Gutenberg.
  -->
</div>

ستدمج Blockstudio تلقائيًا الفئات والسمات القادمة من المحرر (مثل فئات المحاذاة) مع ما هو معرّف في قوالب الكتل. ويُستخدم get_block_wrapper_attributes داخليًا لذلك.

يُطبّق المرشح blockstudio/blocks/components/use_block_props/render على الغلاف في مساري العرض، في الواجهة الأمامية والمحرر. لذلك تظهر الفئات التي يضيفها القالب أو تكامل لكل نسخة على لوحة المحرر، وكذلك في الترميز المحفوظ للواجهة الأمامية.

الناتج:

HTML
<div class="my-class wp-block-your-block-name alignright">
</div>

اعتبارات

يمنع Blockstudio التنقل عبر الروابط داخل محرر الكتل، بما في ذلك target="_blank" والنقر مع الضغط على مفتاح تعديل، والنقر بالزر الأوسط، والتنشيط بلوحة المفاتيح. تظل أحداث النقر تصل إلى Gutenberg، لذا تحدد النقرات العادية الكتلة. ويظل RichText قابلاً للتحرير. ينطبق ذلك سواء وُجد useBlockProps أم لا، بما في ذلك استخدام رابط كعنصر جذر للكتلة.

لا تتغير روابط الواجهة الأمامية وأوامر قائمة سياق المتصفح. لا تحتاج إلى إزالة الروابط من القوالب أو التفرع بحسب $isEditor.

العنصر الجذر

بما أنه لا يمكن أن يكون في قالب الكتلة سوى عنصر جذر واحد، يجب أن يحتوي القالب على عنصر جذر واحد عند استخدام useBlockProps. على سبيل المثال، لن يعمل ما يلي، وسيُنشئ Gutenberg غلافًا حول القالب.

PHP
<div useBlockProps>
  First root element.
</div>
<span>
  Second root element.
</span>

وبالمثل، لا يمكن استخدام useBlockProps إلا مرة واحدة في قالب الكتلة.

علامة @

يحوّل Blockstudio قالب الكتلة إلى كود React صالح داخل Gutenberg باستخدام html-react-parser. وينتج عن ذلك قيد يمنع استخدام الحرف @ داخل اسم سمة HTML.

تستخدم مكتبات مثل Alpine.js الأحرف @ لتعريف التوجيهات على عناصر HTML.

PHP
<button useBlockProps @click="console.log('hi')">
  Click me
</button>

داخل Gutenberg، ستُزال سمة @click هذه من العنصر. (لكنها ستظل تعمل في الواجهة الأمامية بالطبع)

لمعالجة هذه المشكلة، يمكنك استخدام الصياغة البديلة التي يوفّرها Alpine.js.

PHP
<button useBlockProps x-on:click="console.log('hi')">
  Click me
</button>

سيعمل ما سبق داخل Gutenberg وفي الواجهة الأمامية.

فئات متن اللوحة

عند تفعيل assets.reset.enabled، ينسخ Blockstudio أيضًا الفئات المنقّحة التي يعيدها مرشح body_class الخاص بـWordPress إلى لوحة محرر الكتل. وهذا يضمن عمل محددات القالب مثل .brand-a .site-card في الموضعين.

رشّح قائمة الفئات النهائية عندما يحتاج المحرر إلى مجموعة أضيق:

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

يتحكم هذا المرشح في الفئات المنسوخة إلى لوحة المحرر فقط. ولا يغيّر فئات متن الواجهة الأمامية.