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

InnerBlocks

تتيح لك الكتل الداخلية إدراج كتل إضافية داخل كتل أخرى. وتحت الغطاء، يستخدم Blockstudio المكوّن InnerBlocks. يُرجى ملاحظة أنه لا يمكن استخدام سوى مكوّن InnerBlocks واحد لكل كتلة؛ فهذا قيد في WordPress.

الاستخدام الأساسي

لاستخدام InnerBlocks، أضف المكوّن <InnerBlocks /> إلى قالب كتلتك:

PHP
<InnerBlocks />

الأمر متروك لك في تركيبها. يمكنك وضع المكوّن InnerBlocks داخل مكونات أخرى بأي عمق تريده، أو استخدامه منفردًا.

الخصائص

allowedBlocks

تتيح الخاصية allowedBlocks تحديد الكتل التي يمكن إدراجها في المكوّن InnerBlocks.

PHP

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode(['core/heading', 'core/paragraph'])); ?>" />

Twig

Twig
<InnerBlocks allowedBlocks="{{ ['core/heading', 'core/paragraph']|json_encode|escape('html_attr') }}" />

يقبل allowedBlocks أيضًا الرموز الموسّعة على الخادم. تُوسّع الرموز قبل وصول القالب إلى المحرر، بينما تظل أسماء الكتل الحرفية دون تغيير.

الرمز الوصف
namespace/* كل كتلة مسجلة ضمن مساحة الأسماء هذه
category:<slug> كل كتلة مسجلة ضمن فئة الكتل WordPress هذه
@theme كل كتلة Blockstudio مسجلة من القالب النشط

تُزال الازدواجية من المدخلات الموسّعة مع الحفاظ على ترتيب المؤلف:

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />

تُتجاهل الرموز التي لا تطابق أي كتل. ولا يتغير الناتج في الواجهة الأمامية، لأن allowedBlocks يُستخدم في المحرر فقط.

الوسم

يُعرض المكوّن InnerBlocks افتراضيًا كعنصر div. ويمكنك تغيير ذلك باستخدام الخاصية tag.

PHP
<InnerBlocks tag="section" />

القالب

تتيح الخاصية template تحديد قالب للمكوّن InnerBlocks.

PHP

PHP
<InnerBlocks template="<?php echo esc_attr(wp_json_encode([
  ['core/heading', ['placeholder' => 'Book Title']],
  ['core/paragraph', ['placeholder' => 'Summary']]
])); ?>" />

Twig

Twig
<InnerBlocks template="{{ [
  ['core/heading', { placeholder: 'Book Title' }],
  ['core/paragraph', { placeholder: 'Summary' }]
]|json_encode|escape('html_attr') }}" />

templateLock

تتيح الخاصية templateLock تحديد ما إذا كان يمكن تعديل القالب.

القيمة الوصف
contentOnly تمنع جميع العمليات. تُخفى أنواع الكتل التي لا تحتوي على محتوى من عرض القائمة. ولا يمكن للعناصر الفرعية تجاوز هذا القفل.
all تمنع جميع العمليات. لا يمكن إدراج الكتل أو نقلها أو حذفها.
insert تمنع إدراج الكتل أو إزالتها، لكنها تتيح نقل الكتل الموجودة.
false تمنع تطبيق القفل، حتى إن احتوت كتلة أصل على قفل.

renderAppender

تتيح الخاصية renderAppender تحديد نوع أداة إضافة الكتل.

القيمة الوصف
default عرض أداة إضافة الكتل الافتراضية (بأسلوب الفقرة إذا كانت كتلة الفقرة مسموحًا بها)
button عرض زر إضافة يحمل أيقونة +

useBlockProps

يزيل useBlockProps الغلاف الخارجي للمكوّن InnerBlocks داخل المحرر. راجع useBlockProps لمزيد من المعلومات.

السياق

التسجيل

يدعم Blockstudio السياق لمكوّن InnerBlocks. يتيح لك ذلك تمرير البيانات من الكتلة الأصلية إلى الكتل الفرعية. وعلى الرغم من استخدامه آلية السياق الأساسية في WordPress آلية السياق داخليًا، يوفر Blockstudio واجهة API أكثر ملاءمة.

بدلًا من تعريف كل سمة ينبغي تمريرها في السياق على حدة، يمكنك ببساطة الاشتراك في جميع سمات الكتلة الأصل.

يتلقى كل عنصر فرعي قيم الكتلة الأصل الخاصة به، بما في ذلك أثناء العرض الأولي المحمّل مسبقًا في المحرر. ويؤدي تحديث حقول الموفّر إلى تحديث العناصر الفرعية في المحرر، حتى أثناء تحميل عرض سابق. وتحتفظ الكتل الفرعية المتطابقة ضمن موفّرات مختلفة بعروض مخزّنة مؤقتًا منفصلة تراعي السياق.

لنفترض أن لديك إعداد كتلة حاوية كما يلي:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/container",
  "title": "Container",
  "category": "design",
  "icon": "star-filled",
  "description": "Container block.",
  "blockstudio": {
    "attributes": [
      {
        "id": "full-width",
        "type": "toggle",
        "label": "Makes section full width"
      }
    ]
  }
}

داخل كتلتك الفرعية، استخدم الخاصية usesContext مع اسم الكتلة الأصل للوصول إلى جميع سمات الكتلة الأصل في قالب كتلتك.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/element",
  "title": "Element",
  "category": "design",
  "icon": "star-filled",
  "description": "Element block.",
  "usesContext": ["blockstudio/container"],
  "parent": ["blockstudio/container"],
  "blockstudio": true
}

القوالب

يتوفر المتغيران $context و$c داخل قوالب الكتل للوصول إلى جميع سمات الكتل الأصل. وتُعاد تلقائيًا إعادة تحميل الكتل الفرعية في المحرر عند تغير بيانات الكتلة الأصل.

PHP

PHP
<?php $container = $context['blockstudio/container']; ?>

<h1>
  <?php echo $container['full-width']
      ? 'is full width'
      : 'no full width'; ?>
</h1>

Twig

Twig
{% set container = context['blockstudio/container'] %}

<h1>
  {{ container['full-width']
      ? 'is full width'
      : 'no full width' }}
</h1>

غلاف الواجهة الأمامية

يجب أن يعرض InnerBlocks عنصر غلاف حول العناصر الفرعية داخل المحرر، لكن يمكن إزالته من الواجهة الأمامية باستخدام المرشّح blockstudio/blocks/components/inner_blocks/frontend/wrap.

PHP
add_filter('blockstudio/blocks/components/inner_blocks/frontend/wrap', function($wrap, $block) {
  return false; // Remove wrapper
}, 10, 2);

الإنهاء المبكر

إذا أردت الإنهاء مبكرًا من الطريقة render في كتلتك، فتحقق مما إذا كان المتغير $innerBlocks فارغًا. يفيد ذلك عندما لا تريد عرض أي شيء في حال عدم وجود كتل داخلية.

PHP
<?php if (strip_tags($innerBlocks) === '') {
  return;
} ?>
<InnerBlocks tag="section" />

بما أن <InnerBlocks/> يعرض دائمًا وسم فقرة فارغًا، يمكنك استخدام الدالة strip_tags للتحقق مما إذا كان المحتوى فارغًا.

القوالب الديناميكية

يدعم نوعا الحقل Select وRadio إنشاء قالب InnerBlocks ديناميكيًا بناءً على قيمة الحقل. يفيد ذلك إذا أردت إتاحة اختيار قالب مختلف للمستخدم لمكوّن InnerBlocks.

لتحقيق ذلك، أضف ببساطة مفتاح innerBlocks إلى مصفوفة الخيارات مع القالب:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/dynamic-layout",
  "title": "Dynamic Layout",
  "blockstudio": {
    "attributes": [
      {
        "id": "layout",
        "type": "select",
        "label": "Layout",
        "options": [
          {
            "value": "1",
            "label": "Two Columns",
            "innerBlocks": [
              {
                "name": "core/columns",
                "innerBlocks": [
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Left Heading",
                          "level": 1
                        }
                      }
                    ]
                  },
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Right Heading",
                          "level": 1
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "value": "2",
            "label": "Single Column",
            "innerBlocks": [
              {
                "name": "core/heading",
                "attributes": {
                  "content": "Main Heading",
                  "level": 1
                }
              },
              {
                "name": "core/paragraph",
                "attributes": {
                  "content": "Main content goes here."
                }
              }
            ]
          }
        ],
        "allowNull": "Select a layout"
      }
    ]
  }
}

سياق الكتل والتواصل

تعرّف على كيفية مشاركة الكتل الأصل والفرعية للبيانات باستخدام السياق.