شرح InnerBlocks API: حاوية تحرير وحفظ متطابقتان في جوتنبرج

أهلاً بيك يا صديقي المطور في المحطة الحاسمة اللي هتنقل فهمك لمحرر المكونات (Gutenberg) من مجرد مطور بيعمل بلوكات نصوص وصور منفصلة، لمهندس برمجيات بيبني “تخطيطات مركبة متكاملة” (Complex Composite Layouts). لو بتسأل نفسك إزاي بلوك الأعمدة (Columns) أو بلوك المجموعة (Group) في ووردبريس بيقدر يشيل جواه أي عدد من البلوكات التانية بسلاسة، ويحتفظ بنفس التنسيق والشكل في شاشة التحرير وفي الموقع الحقيقي بدون أدنى تعارض، فالإجابة بكلمة واحدة: InnerBlocks API.

الـ InnerBlocks مش مجرد كومبوننت بنحطه في كود الـ React؛ دي المعمارية التحتية اللي بتخلي ووردبريس يفهم مفهوم “الحاوية” (Container Architecture). زمان قبل ظهور الـ InnerBlocks Props الحديثة، كان المطورين بيلجأوا لحيل صعبة زي تكرار الـ Shortcodes أو تخزين كائنات JSON معقدة جوة خصائص فردية، وده كان بينتهي بكوارث في التوافق وتجربة كتابة مرعبة للمحررين. في المقال ده، هنفكك الـ InnerBlocks حتة حتة، وهنعرف الفرق الجوهري بين استخدامه في البلوكات الثابتة (Static Blocks) والبلوكات الديناميكية (Dynamic Blocks)، مع التركيز على نمط useInnerBlocksProps الحديث، وكيفية قفل القوالب وضمان التوافق التام بنسبة 100% بين شاشة التحرير وشاشة العرض في الواجهة الأمامية بالعامية المصرية التقنية الأصيلة.

المعمارية العميقة للـ InnerBlocks API: إزاي جوتنبرج بيدير الحاويات؟

عشان تفهم InnerBlocks بعمق يفرقك عن المطورين الهواة، لازم تسأل نفسك: هو إيه اللي بيحصل في قاعدة بيانات ووردبريس وفي الذاكرة لما بنحط بلوك جوة بلوك؟

في الذاكرة (Client-side Memory)، محرر جوتنبرج بيتعامل مع كل مقال كشجرة كائنات برمجية (Block Tree AST). لما البلوك يعلن إنه بيستخدم InnerBlocks، المحرر بيفهم فوراً إن البلوك ده مش مجرد عقدة ورقية نهائية (Leaf Node)، بل هو عقدة فرعية (Branch Node) تقدر تشيل مصفوفة فرعية كاملة اسمها innerBlocks. كل عنصر في المصفوفة دي هو كائن بلوك كامل عنده clientId، name، attributes، وكمان ممكن يكون عنده innerBlocks خاصة بيه في تداخل غير محدود!

أما عند الحفظ في جدول wp_posts داخل عمود post_content، ووردبريس بيترجم الشجرة دي لنص تسلسلي (Serialized HTML with Block Delimiters). البلوك الأب بيفتح بالتعليق الشكلي:

<!-- wp:my-plugin/container {"layout":"grid"} -->
<div class="wp-block-my-plugin-container">
    <!-- wp:paragraph -->
    <p>هذا نص الابن الأول المتداخل</p>
    <!-- /wp:paragraph -->

    <!-- wp:image {"id":42} -->
    <figure class="wp-block-image"><img src="..." alt=""/></figure>
    <!-- /wp:image -->
</div>
<!-- /wp:my-plugin/container -->

لاحظ الدقة هنا يا هندسة: ووردبريس بيحفظ وسوم تعليقات الأبناء مباشرة بين وسم فتح الحاوية ووسم إغلاقها! دالة InnerBlocks.Content في دالة الحفظ ما بتعملش أي سحر معقد؛ كل وظيفتها إنها تحط “علامة حجز مكان” (Placeholder) في الـ JSX بتقول لمحرر جوتنبرج: “هنا بالضبط اطبع المحتوى المتسلسل لجميع الأبناء بالترتيب”.

ثورة useInnerBlocksProps Hook: وداعاً للطبقات الزائدة

في الإصدارات الأولى من Gutenberg، كنا مضطرين نكتب:

// ❌ الأسلوب القديم الذي كان يضيف وسم div غير مرغوب فيه
export function Edit() {
    const blockProps = useBlockProps();
    return (
        <div { ...blockProps }>
            <h2>عنوان الحاوية</h2>
            <InnerBlocks />
        </div>
    );
}

المشكلة كانت إن كومبوننت <InnerBlocks /> كان بيولد تلقائياً وسم <div class="block-editor-block-list__layout"> إضافي داخلي، وده كان بيكسر تماماً رغبتك في استخدام CSS Grid مباشرة بين الأبناء وبين العناصر المجاورة لهم.

لذلك، فريق ووردبريس قدم الخطاف العبقري useInnerBlocksProps. الخطاف ده بياخد خصائص البلوك ويدمج معاها خصائص الحاوية في كائن واحد، فتقدر تحول أي وسم HTML عندك (سواء كان <div>، <section>، <ul>، أو حتى <main>) لحاوية أبناء فورية بدون وسوم حشو وسيطة!

تطبيق عملي كامل: بناء بلوك كروت شبكية متقدمة (Enterprise Grid Container)

تعال نبني مع بعض كود إنتاجي لبلوك حاوية اسمه (enterprise/feature-grid) بيحتوي على كروت مميزات (enterprise/feature-card). الحاوية دي فيها قفل قالب مرن، وأزرار إضافة مخصصة، وتطابق بنسبة 100% بين واجهة التحرير والواجهة الأمامية للموقع.

1. إعداد ملف التعريف: block.json

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/feature-grid",
  "version": "1.0.0",
  "title": "شبكة الميزات المتقدمة",
  "category": "design",
  "icon": "grid-view",
  "description": "حاوية احترافية مبنية بـ InnerBlocks لعرض بطاقات الخدمات والميزات بتنسيق شبكي متطور.",
  "supports": {
    "html": false,
    "align": [ "wide", "full" ],
    "color": {
      "background": true,
      "text": true
    },
    "spacing": {
      "margin": true,
      "padding": true
    }
  },
  "attributes": {
    "columnsCount": {
      "type": "number",
      "default": 3
    },
    "templateLocked": {
      "type": "string",
      "default": "none"
    }
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

تفكيك الخصائص التقنية:

• apiVersion: 3: يضمن استخدام المعمارية الحديثة وعزل سياق التنسيقات في بيئة معزولة (Iframe) داخل المحرر.
• supports.html: false: خطوة أمنية وتنظيمية تمنع المحرر من العبث بكود الـ HTML الخاص بالحاوية يدوياً عبر خيار “Edit as HTML”، لحماية بنية الحاوية من التلف.
• columnsCount: خاصية تتحكم في توزيع الأعمدة الشبكية في الـ CSS في الواجهتين.

2. كود واجهة التحرير: edit.js باستخدام useInnerBlocksProps

import { useBlockProps, useInnerBlocksProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, RangeControl, SelectControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
import './editor.scss';

// تحديد البلوكات المسموح بإدراجها فقط داخل هذه الحاوية
const ALLOWED_BLOCKS = [ 'enterprise/feature-card', 'core/heading', 'core/paragraph' ];

// تعريف القالب الافتراضي المبدئي عند إدراج البلوك لأول مرة
const TEMPLATE = [
    [ 'core/heading', { level: 2, placeholder: 'اكتب عنوان قسم المميزات هنا...' } ],
    [ 'enterprise/feature-card', { title: 'ميزة الأداء الفائق', icon: 'performance' } ],
    [ 'enterprise/feature-card', { title: 'الأمان المتقدم', icon: 'shield' } ],
    [ 'enterprise/feature-card', { title: 'دعم العملاء على مدار الساعة', icon: 'headset' } ]
];

export default function Edit( { attributes, setAttributes } ) {
    const { columnsCount, templateLocked } = attributes;

    // استخراج خصائص الغلاف الخارجي للبلوك
    const blockProps = useBlockProps( {
        className: `az-enterprise-grid az-grid-cols-${ columnsCount }`
    } );

    // دمج خصائص الحاوية المتداخلة مع الغلاف مباشرة
    const innerBlocksProps = useInnerBlocksProps( blockProps, {
        allowedBlocks: ALLOWED_BLOCKS,
        template: TEMPLATE,
        templateLock: templateLocked === 'none' ? false : templateLocked,
        orientation: 'horizontal',
        // استخدام زر إضافة مخصص يظهر في نهاية قائمة البلوكات
        renderAppender: innerBlocksProps => (
            

                
            
        )
    } );

    return (
        
            
                
                     setAttributes( { columnsCount: val } ) }
                        min={ 1 }
                        max={ 4 }
                    />
                     setAttributes( { templateLocked: val } ) }
                        help={ __( 'يتحكم في صلاحيات المحررين في تعديل ترتيب وبنية الكروت الداخلية.', 'az-grid' ) }
                    />
                
            

            { /* هنا يكمن السحر: لا يوجد أي وسوم متداخلة حشو! العنصر نفسه هو الحاوية */ }
            

        

شرح أسرار كود التحرير:

• useInnerBlocksProps(blockProps, options): لاحظ هنا إننا مررنا blockProps كأول وسيط! الحركة دي معناها: "خد كلاسات الـ wrapper وهوامش ووردبريس وحطها على نفس الوسم، واجعل الوسم ده نفسه هو حاوية الأبناء". مفيش <div> داخلي زيادة!
• allowedBlocks: حماية معمارية حديدية؛ بتمنع المحرر إنه يحط بلوك غير متوافق (زي ويدجت قديمة أو فورم تكسر التصميم) داخل شبكة الخدمات.
• templateLock: بيوفر 4 أوضاع لقفل القالب: false (حر تماماً)، all (ممنوع تحذف كارت أو تضيف كارت جديد، بس تقدر تغير ترتيبهم أو تعدل نصوصهم)، insert (ممنوع تضيف بس ينفع تحذف أو ترتب)، و contentOnly وهو الوضع الأحدث اللي بيقفل التنسيق تماماً ويسمح بتعديل الكلمات فقط.

3. كود واجهة الحفظ: save.js المتطابق

import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';

export default function save( { attributes } ) {
    const { columnsCount } = attributes;

    const blockProps = useBlockProps.save( {
        className: `az-enterprise-grid az-grid-cols-${ columnsCount }`
    } );

    const innerBlocksProps = useInnerBlocksProps.save( blockProps );

    return (
        

    );
}

// save.js في البلوكات الديناميكية
import { useInnerBlocksProps } from '@wordpress/block-editor';

export default function save() {
    return <useInnerBlocksProps.Content />;
}

<?php
/**
 * ملف render.php لحاوية البلوك الديناميكية
 * 
 * @var array    $attributes خصائص البلوك
 * @var string   $content    مخرجات الـ InnerBlocks مجهزة بالكامل كـ HTML
 * @var WP_Block $block      كائن البلوك الأصلي
 */

$cols = isset( $attributes['columnsCount'] ) ? absint( $attributes['columnsCount'] ) : 3;
$wrapper_attributes = get_block_wrapper_attributes([
    'class' => 'az-enterprise-grid az-grid-cols-' . $cols,
]);
?>

<section <?php echo $wrapper_attributes; ?>>
    <div class="az-grid-dynamic-badge">
        <?php printf( esc_html__( 'عدد الأقسام المعروضة حالياً: %d', 'az-grid' ), count( $block->inner_blocks ) ); ?>
    </div>
    <!-- طباعة محتويات الأبناء التي تم توليدها وتجميعها تلقائياً -->
    <div class="az-grid-items-container">
        <?php echo $content; ?>
    </div>
</section>

import { InnerBlocks } from '@wordpress/block-editor';

// النمط الأول: استخدام الزر المدمج البسيط
const appenderSimple = () => ;

// النمط الثاني: استخدام الزر الافتراضي التفاعلي
const appenderDefault = () => ;

// النمط الثالث: إخفاء زر الإضافة تماماً حتى لو كان القالب مفتوحاً
const appenderHidden = () => false;