البلوكات المتداخلة في Gutenberg: هندسة علاقة الأب والأبناء والتحكم في الحاويات

{
  "name": "enterprise/accordion-item",
  "parent": [ "enterprise/accordion-container" ]
}

{
  "name": "enterprise/accordion-cta",
  "ancestor": [ "enterprise/accordion-container" ]
}

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/accordion-container",
  "version": "1.0.0",
  "title": "حاوية أكورديون الأسئلة الشائعة",
  "category": "design",
  "icon": "list-view",
  "description": "حاوية مؤسسية لتنظيم وتجميع الأسئلة الشائعة في شجرة متداخلة تفاعلية.",
  "supports": {
    "color": {
      "background": true,
      "text": true
    },
    "spacing": {
      "padding": true,
      "margin": true
    }
  },
  "attributes": {
    "allowMultipleOpen": {
      "type": "boolean",
      "default": false
    }
  },
  "providesContext": {
    "enterprise/allowMultiple": "allowMultipleOpen"
  },
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, InnerBlocks, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ToggleControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

const ALLOWED_BLOCKS = ['enterprise/accordion-item'];
const TEMPLATE = [
    ['enterprise/accordion-item', {}],
    ['enterprise/accordion-item', {}]
];

registerBlockType('enterprise/accordion-container', {
    edit({ attributes, setAttributes }) {
        const { allowMultipleOpen } = attributes;
        const blockProps = useBlockProps({ className: 'az-accordion-container' });

        return (
            
                
                    
                         setAttributes({ allowMultipleOpen: val })}
                        />
                    
                

                

                    

                        
                        {__('أكورديون الأسئلة الشائعة (حاوية الأب)', 'text-domain')}
                    
                    
                
            
                
            

3. ملف بلوك السؤال الابن (accordion-item/block.json)

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/accordion-item",
  "version": "1.0.0",
  "title": "سؤال أكورديون فردي",
  "category": "design",
  "icon": "editor-help",
  "parent": [ "enterprise/accordion-container" ],
  "attributes": {
    "question": {
      "type": "string",
      "source": "text",
      "selector": "span.question-title",
      "default": "اكتب السؤال هنا..."
    },
    "isInitiallyOpen": {
      "type": "boolean",
      "default": false
    }
  },
  "usesContext": [ "enterprise/allowMultiple" ],
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

4. ملف كود السؤال الابن (accordion-item/index.js)

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText, InnerBlocks, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ToggleControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

registerBlockType('enterprise/accordion-item', {
    edit({ attributes, setAttributes, context }) {
        const { question, isInitiallyOpen } = attributes;
        const blockProps = useBlockProps({ className: 'az-accordion-item-admin' });

        return (
            
                
                    
                         setAttributes({ isInitiallyOpen: val })}
                        />
                    
                

                

                    

                        ▼
                         setAttributes({ question: val })}
                            placeholder={__('أدخل نص السؤال الشائع...', 'text-domain')}
                        />
                    
                    

                        
                    
                
            
                

                    {question}
                    
                
                

                    
                
            
        );
    }
});

تفكيك الكود وشرح فلسفته المعمارية بالعامية المصرية

بص يا صديقي على السحر المعماري في التكامل ده:

• الحصر المطلق بالـ parent: لما حددنا في بلوك accordion-item إن أبوه هو enterprise/accordion-container، ضمنا إن مفيش كاتب هيغلط ويحط السؤال برة الحاوية. البلوك مبيظهرش في الـ Inserter إلا جوة الحاوية فقط!
• حرية كاملة في الإجابة عبر <InnerBlocks /> داخل الابن: المحرر في خانة الإجابة مش مقيد بنص عادي؛ هو يقدر يحط فقرة، قائمة نقطية، صورة توضيحية، أو جدول أسعار كامل جوة نفس إجابة السؤال! كل ده بيتم تصييره بسلاسة داخل وسم <details> القياسي في الـ HTML5.
• توليد قالب افتراضي بالـ TEMPLATE: أول ما المحرر يدرج بلوك الحاوية، جوتنبرج تلقائياً بيحط جواه سؤالين جاهزين فاضيين، مع زرار أنيق InnerBlocks.ButtonBlockAppender لإضافة أسئلة جديدة بضغطة زر واحدة، وده بيقدم أعلى تجربة تحرير (Editor UX) ممكنة.

الوصايا العشر لتصميم البلوكات المتداخلة في Gutenberg

1. قيد الأبناء بخاصية parent دائماً: لا تترك البلوكات الفرعية تطفو في القائمة العامة؛ احصرها في الأب المصرح له لحماية تجربة المحرر.
2. حدد allowedBlocks في الحاوية: لا تفتح الحاوية على مصراعيها؛ حدد قائمة بيضاء بالبلوكات المسموح بإدراجها لمنع تخريب التخطيط.
3. وفر قوالب بداية ذكية بـ template: اجعل البلوك يبدأ بعناصر افتراضية جاهزة لتوجيه المحرر وتوفير وقته.
4. احرص على تطابق دالة save في استخدام <InnerBlocks.Content />: لا تنسَ استدعاء InnerBlocks.Content في دالة الحفظ لتصيير الأبناء في الـ HTML.
5. استخدم وسوم الـ HTML5 الدلالية (Semantic Tags): اعتمد على وسوم مثل <details> و <summary> للأكورديون لتحسين الـ A11y.
6. استخدم Block Context لتمرير الخيارات العامة: مرر خيارات الألوان والأوضاع التفاعلية من الأب للأبناء دون تكرار الحقول.
7. اختر زر الإضافة المناسب عبر renderAppender: استخدم ButtonBlockAppender لإظهار زر إضافة أنيق وواضح داخل الحاوية.
8. لا تتجاوز مستويين من التداخل في نفس المكون: اجعل هيكلية مكوناتك المركبة بسيطة وتجنب تداخل الأكورديون داخل أكورديون آخر.
9. اختبر إمكانية الوصول والتنقل بلوحة المفاتيح: تأكد من أن القارئات الآلية قادرة على فتح وغلق العناصر والتنقل بين الأبناء بسلاسة.
10. احمِ البلوكات من الحذف العرضي بـ templateLock: إذا كان التصميم يتطلب بنية ثابتة (مثل هيدر وعمودين)، اقفل القالب لحماية التخطيط.

المعمارية المتقدمة لإدارة الحالة التزامنية في البلوكات المتداخلة المركبة (Compound State Architecture)

يا صديقي المطور، لما ننتقل من مرحلة البلوكات المتداخلة البسيطة (زي أكورديون خفيف) لمرحلة الأنظمة المعقدة في المؤسسات الكبرى، مثل “نظام تبويبات تفاعلي متقدم” (Multi-Tabbed Interactive Interface) أو “حاويات السلايدر المتداخلة” (Nested Slider Carousel)، بنواجه معضلة معمارية حقيقية: إزاي البلوك الأب يعرف مين الابن النشط حالياً؟ وإزاي الابن لما يتغير حاله يبلّغ باقي إخوته بدون ما نعمل “Prop Drilling” عشوائي يبهدل أداء المحرر ويثقل على متصفح المحرر؟

في عالم رياكت الكلاسيكي بنلجأ لنمط الـ Compound Components Pattern بالاعتماد على React Context. لكن داخل جوتنبرج، الموضوع بيحصل على مستويين متوازيين:

1. مستوى الـ Data Store (Redux/wp.data): كل بلوك في جوتنبرج يمتلك كود تعريفي فريد (clientId)، ومسجل داخل الـ Block Store المركزي core/block-editor. التعامل مع التغييرات بيتطلب استخدام Selectors دقيقة للغاية لتفادي إعادة رسم (Re-rendering) الشجرة بأكملها.
2. مستوى سياق البلوك (Block Context API): وهو الجسر الرسمي المدمج في نواة ووردبريس لتمرير الخصائص من الأب للأبناء دون الحاجة لحقن Props يدوياً.

نموذج برمجي متكامل: بناء نظام تبويبات (Enterprise Tabs & Tab Panel) بالبلوكات المتداخلة

تعال نبني معمارية حقيقية لنظام تبويبات يتكون من بلوك أب (enterprise/tabs-container) ومجموعة بلوكات أبناء غير محدودة (enterprise/tab-item). الهدف هنا إن الأب يوزع سياق الـ Active Tab على الأبناء، والابن يعرض المحتوى المخصص له فقط في الواجهة الأمامية والمحرر بناءً على التفاعل السلس.

1. تعريف البلوك الأب ومشاركة السياق (Parent block.json)

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/tabs-container",
  "title": "حاوية التبويبات المتقدمة",
  "category": "design",
  "attributes": {
    "activeTabIndex": {
      "type": "number",
      "default": 0
    },
    "tabsLayout": {
      "type": "string",
      "default": "horizontal"
    }
  },
  "providesContext": {
    "enterprise/activeTabIndex": "activeTabIndex",
    "enterprise/tabsLayout": "tabsLayout"
  },
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

شرح تفصيلي للخصائص في البلوك الأب:

• providesContext: هنا الأب بيعلن للعالم الخارجي ولكافة البلوكات المتواجدة أسفله في الشجرة الهرمية إنه بيوفر قيمتين حيويتين: enterprise/activeTabIndex و enterprise/tabsLayout. بمجرد ما المحرر يغير التبويب النشط في الأب، كل الأبناء بيستلموا التحديث اللحظي عبر الـ Context.
• apiVersion: 3: استخدام أحدث واجهات جوتنبرج لضمان أفضل دعم لـ Block Wrapper وخاصية الـ Iframe داخل المحرر.

2. كود تحرير الأب (edit.js للـ Tabs Container)

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

const ALLOWED_BLOCKS = [ 'enterprise/tab-item' ];
const TEMPLATE = [
    [ 'enterprise/tab-item', { title: 'البيانات الشخصية' } ],
    [ 'enterprise/tab-item', { title: 'تفاصيل الشحن والتوصيل' } ],
    [ 'enterprise/tab-item', { title: 'خيارات الدفع' } ]
];

export default function Edit( { attributes, setAttributes, clientId } ) {
    const { activeTabIndex, tabsLayout } = attributes;

    // استخراج معلومات الأبناء من مخزن البيانات لمعرفة عناوين التبويبات الحالية
    const innerBlocks = useSelect( ( select ) => {
        return select( 'core/block-editor' ).getBlock( clientId )?.innerBlocks || [];
    }, [ clientId ] );

    const blockProps = useBlockProps( {
        className: `az-tabs-wrapper az-tabs-${ tabsLayout }`
    } );

    const innerBlocksProps = useInnerBlocksProps(
        { className: 'az-tabs-content-area' },
        {
            allowedBlocks: ALLOWED_BLOCKS,
            template: TEMPLATE,
            templateLock: false,
            orientation: tabsLayout === 'vertical' ? 'vertical' : 'horizontal'
        }
    );

    return (
        

            
                
                     setAttributes( { tabsLayout: val } ) }
                    />
                
            

            { /* شريط أزرار التبويبات في المحرر للتبديل بين التبويبات بسهولة */ }
            

                { innerBlocks.map( ( block, index ) => (
                     setAttributes( { activeTabIndex: index } ) }
                    >
                        { block.attributes.title || `تبويب ${ index + 1 }` }
                    
                ) ) }
            

            { /* حاوية المحتوى المتداخلة */ }
            

        
    );
}

تحليل سطور الكود باحترافية:

• useSelect: قمنا بسحب مصفوفة innerBlocks المرتبطة بالـ clientId للبلوك الأب عشان نعرض أزرار التنقل (Header Tabs) ديناميكياً في شريط الأدوات داخل المحرر بدون ما يضطر المحرر يضغط على كل بلوك ابن يدوياً.
• setAttributes({ activeTabIndex: index }): لما المحرر يضغط على زر تبويب في الشريط العلوي، بنغير قيمة الخاصية في الأب، وتلقائياً الـ Context هيبعت القيمة دي لكل الـ Tab Items.

3. تعريف البلوك الابن واستقبال السياق (Child block.json)

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/tab-item",
  "title": "عنصر التبويب الفردي",
  "category": "design",
  "parent": [ "enterprise/tabs-container" ],
  "usesContext": [
    "enterprise/activeTabIndex",
    "enterprise/tabsLayout"
  ],
  "attributes": {
    "title": {
      "type": "string",
      "default": "تبويب جديد"
    },
    "tabIndex": {
      "type": "number",
      "default": 0
    }
  },
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

4. كود تحرير الابن والتحكم في الظهور (edit.js للـ Tab Item)

import { useBlockProps, useInnerBlocksProps, RichText } from '@wordpress/block-editor';
import { useSelect } from '@wordpress/data';
import { useEffect } from '@wordpress/element';
import { __ } from '@wordpress/i18n';

export default function Edit( { attributes, setAttributes, context, clientId } ) {
    const { title } = attributes;
    const activeTabIndex = context[ 'enterprise/activeTabIndex' ] ?? 0;

    // استخراج ترتيب هذا الابن بين إخوته داخل الأب
    const selfIndex = useSelect( ( select ) => {
        const { getBlockRootClientId, getBlockIndex } = select( 'core/block-editor' );
        const rootId = getBlockRootClientId( clientId );
        return getBlockIndex( clientId, rootId );
    }, [ clientId ] );

    // تحديث رقم الفهرس تلقائياً في خصائص البلوك الابن
    useEffect( () => {
        if ( attributes.tabIndex !== selfIndex ) {
            setAttributes( { tabIndex: selfIndex } );
        }
    }, [ selfIndex, attributes.tabIndex, setAttributes ] );

    const isActive = activeTabIndex === selfIndex;

    const blockProps = useBlockProps( {
        className: `az-tab-item-panel ${ isActive ? 'is-active-tab' : 'is-hidden-tab' }`,
        style: { display: isActive ? 'block' : 'none' }
    } );

    const innerBlocksProps = useInnerBlocksProps(
        { className: 'az-tab-inner-content' },
        {
            templateLock: false // السماح للمستخدم بوضع أي نوع بلوكات داخل التبويب
        }
    );

    return (
        

            

                 setAttributes( { title: val } ) }
                    placeholder={ __( 'اكتب عنوان هذا التبويب هنا...', 'az-tabs' ) }
                    className="az-tab-title-field"
                />
            
            

        
    );
}

أسرار المعمارية في كود الابن:

• getBlockRootClientId و getBlockIndex: استخدمنا الدوال دي عشان نحدد بالضبط ترتيب الابن داخل الحاوية بدون ما نطلب من المستخدم يكتب رقم التبويب بإيده! الحساب أوتوماتيكي بالكامل.
• style: { display: isActive ? 'block' : 'none' }: في المحرر، لما الابن يكون مش هو النشط بنخفيه بصرياً مع الحفاظ على وجوده في شجرة الدوم، وبالتالي المحرر يشوف فقط محتويات التبويب اللي هو شغال عليه حالياً، مع إمكانية التبديل بنقرة واحدة من شريط التبويبات بالأعلى.

تحسين الأداء في شجرات البلوكات المعقدة (Performance Optimization & Memoization)

عندما تحتوي الصفحة على شجرة بلوكات متداخلة عميقة—كأن يكون لديك حاوية أعمدة (Grid) بداخلها حاوية بطاقات (Cards)، وكل بطاقة تحتوي على أكورديون (Accordion) وبداخله وسائط ونصوص—قد يلاحظ المستخدم بطئاً أو تهنيجاً (Lag) أثناء الكتابة السريعة في المحرر. ما هو السبب البرمجي الدقيق وراء هذا البطء، وكيف نتغلب عليه معمارياً؟

السبب هو أن كل ضغطة زر في الـ RichText تقوم بإطلاق Dispatch لتحديث خصائص البلوك في الـ Store. إذا كان البلوك الأب يستمع للـ Store بدون ترشيح دقيق (Selector Filtering)، فسيتم إعادة استدعاء دالة Edit للأب ولكافة الأبناء والأحفاد!

استراتيجيات التسريع المعماري للبلوكات المتداخلة:

1. تطبيق الـ Shallow Comparison في useSelect:

   تجنب إرجاع كائنات جديدة (New Objects) داخل دالة الـ selector بدون الحاجة. دائماً استخرج فقط المعرفات (Client IDs) بدلاً من استخراج كائنات البلوكات كاملة بخصائصها، لأن تغيير خاصية نصية صغيرة في ابن واحد سيعيد رسم الأب إذا كان يستخرج كامل الكائن.

   // ❌ خطأ فادح: يسبب إعادة رسم الحاوية بالكامل مع كل حرف يكتبه المستخدم في أي ابن!
   const allBlocks = useSelect( ( select ) => {
       return select( 'core/block-editor' ).getBlocks( clientId );
   }, [ clientId ] );
   
   // ✅ الأسلوب الأمثل: استخراج مصفوفة الـ Client IDs فقط لمراقبة الهيكل لا الخصائص
   const childClientIds = useSelect( ( select ) => {
       return select( 'core/block-editor' ).getBlockOrder( clientId );
   }, [ clientId ] );

2. استخدام React.memo لعزل محتوى الأبناء:

   تغليف المكونات الفرعية داخل React.memo ومقارنة الـ Props بعناية يمنع المتصفح من هدر دورات المعالج (CPU Cycles) في إعادة رسم بلوكات لم تتغير مدخلاتها إطلاقاً.

3. استخدام templateLock الاستراتيجي:

   إذا كان تصميم الحاوية لا يتطلب إضافة عناصر لا نهائية، فإن تثبيت القالب بقيمة templateLock="all" أو templateLock="insert" يعفي محرر جوتنبرج من حساب احتمالات الإدراج والسحب والإفلات المستمرة، مما يسرع عملية المعالجة بنسبة تصل إلى 40% في الهياكل الضخمة.

دليل حل المشاكل الشائعة في البلوكات المتداخلة (Debugging & Troubleshooting Guide)

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