النموذج الذهني لـ React في ووردبريس: الحالة والخصائص وتدفق التحديث في Gutenberg

أهلاً بيك يا صديقي المطور في أهم نقلة عقلية وهندسية هتعملها في حياتك كمطور ووردبريس: النموذج الذهني لـ React (The React Mental Model) داخل محرر Gutenberg.

لو أنت زي ملايين المبرمجين اللي بدأوا رحلتهم مع ووردبريس الكلاسيكي، فأنت متبرمج عصبياً على أسلوب “البرمجة الإجرائية والأمرية” (Imperative Programming) باستخدام PHP و jQuery. النموذج ده كان معتمد على إنك بتمسك عنصر الـ DOM بإيدك وتأمره باللي يعمله: “روح يا جافاسكريبت دور على الزرار اللي الـ ID بتاعه #submit-btn، ولما المستخدم يدوس عليه، غير النص بتاعه لـ ‘جاري التحميل’، وروح للعنصر #alert وشيل منه كلاس hidden وحط كلاس active!”.

أول ما المطور ده بيدخل عالم Gutenberg و React، بيبدأ يتخبط ويصطدم بجدار خرساني؛ لإن React مش بتفكر كده خالص! في React، إنت مبتمسكش الـ DOM ولا بتأمره يعمل حاجة، بل بتتعامل مع معادلة رياضية عبقرية وبسيطة: UI = f(State): واجهة المستخدم هي دالة صافية في حالة البيانات! في الدليل التفصيلي ده، هنفكك النقلة الفكرية من jQuery لـ React، إزاي تفهم تدفق البيانات أحادي الاتجاه (Unidirectional Data Flow)، الفرق الجوهري بين Props و State و Attributes، وأشهر 5 أخطاء كارثية بيقع فيها مطورو PHP مع دراسة حالة مصرية حقيقية بالعامية المصرية التقنية الأصيلة.

الأركان الثلاثة لمعمارية React داخل Gutenberg

عشان تبني كود جوتنبرج صلب ومحترف، لازم تفهم التوليفة الخاصة اللي بتجمع React مع نظام ووردبريس الداخلي:

1. المكونات (Components): لبنات البناء النقية

في React، كل شيء عبارة عن “مكون” (Component). المكون هو دالة جافاسكريبت بسيطة بتاخد مدخلات (Props) وبترجع كود JSX (اللي بيترجم لعناصر واجهة). دالة Edit في البلوك هي المكون الرئيسي، وبداخلها بنستخدم مكونات فرعية زي RichText، InspectorControls، ToolbarGroup، و Button.

2. الخصائص (Props): جواز السفر بين المكونات

الـ Props هي البيانات اللي بتتنقل من المكون الأب للمكون الابن. في جوتنبرج، ووردبريس بيغذي دالة Edit بمجموعة Props جاهزة ومقدسة:

• attributes: كائن يحتوي على كافة الخصائص المعرفة في block.json والمحفوظة في قاعدة البيانات.
• setAttributes: الدالة الرسمية الوحيدة المسموح لك باستخدامها لتعديل قيم الـ attributes.
• isSelected: قيمة منطقية (Boolean) تخبرك هل البلوك محدد حالياً بواسطة المحرر أم لا.
• clientId: المعرف الفريد الداخلي للبلوك في الذاكرة الحية لجوتنبرج.
• context: كائن يحتوي على البيانات الموروثة من البلوكات الأب (Block Context API).

3. مستويات الحالة الثلاثة (The Three Levels of State):

هنا تكمن النقطة الفاصلة التي تلخبط 90% من مطوري ووردبريس! في جوتنبرج، هناك ثلاثة أنواع مختلفة تماماً من الحالة (State)، وكل نوع له مكانه واستخدامه:

1. حالة المكون المحلية (Local Component State عبر useState):

   تستخدم للبيانات المؤقتة العابرة الخاصة بواجهة المستخدم داخل المحرر فقط، والتي لا تريد حفظها في المقال! مثل: هل نافذة الـ Modal مفتوحة حالياً؟ هل القائمة منسدلة أم مغلقة؟ بمجرد ما المحرر يقفل الصفحة، البيانات دي بتختفي، وده مكانها الطبيعي.

2. خصائص البلوك الدائمة (Block Attributes عبر setAttributes):

   دي البيانات الحقيقية اللي بتشكل محتوى المقال والمطلوب تخزينها في قاعدة البيانات في جدول wp_posts (مثل: نصوص العناوين، معرفات الصور، ألوان البلوك، إعدادات التخطيط).

3. مخزن البيانات العام (Global Core Store عبر @wordpress/data):

   مخزن Redux مركزي يدير حالة المقال بالكامل وموقع ووردبريس (مثل: هل المقال جاري حفظه حالياً؟ ما هو المعرف التعريفي للكاتب؟ قائمة كافة البلوكات الموجودة في الصفحة).

تدفق البيانات أحادي الاتجاه (Unidirectional Data Flow): دورة الحياة الحقيقية

تعال نتتبع بالملي ثانية إيه اللي بيحصل لما المحرر يكتب حرف واحد في حقل نصي داخل البلوك بتاعك:

1. الكاتب يضغط حرف 'أ' في لوحة المفاتيح
    ↓
2. يتم إطلاق حدث (Event Trigger): onChange
    ↓
3. يتم استدعاء دالة: setAttributes( { title: newTitle } )
    ↓
4. محرر جوتنبرج يرسل Action لمخزن البيانات المركزي (Redux Store)
    ↓
5. المخزن يقوم بتحديث حالة البلوك بالخاصية الجديدة (Immutable Update)
    ↓
6. يقوم React باستدعاء دالة Edit( props ) من جديد وتمرير attributes محدثة!
    ↓
7. دالة Edit ترجع JSX جديد يعكس الحرف الجديد
    ↓
8. خوارزمية Reconciliation تقارن الـ Virtual DOM بالـ Real DOM وتحدث الحرف في الشاشة!

الدرس المعماري الأكبر: أنت لا تغير النص في الشاشة بيدك! أنت تبلغ ووردبريس بالقيمة الجديدة عبر setAttributes، وتترك React هي التي تتولى إعادة طلاء الشاشة بناءً على الحالة الجديدة.

أمثلة برمجية: الكود الكارثي بعقلية jQuery مقابل الكود التصريحي النقي

1. النموذج الكارثي: محاولة تطويع React بأسلوب jQuery العقيم

// ❌ كود كارثي مليء بالأخطاء المعمارية والمفاهيم الخاطئة!
import { useBlockProps } from '@wordpress/block-editor';

export default function Edit( { attributes, setAttributes } ) {
    const blockProps = useBlockProps();

    // خطأ قاتل 1: البحث المباشر في الدوم وتعديل العناصر بالأمر
    const handleButtonClick = () => {
        const titleElement = document.getElementById( 'my-custom-title' );
        if ( titleElement ) {
            titleElement.innerText = 'تم تغيير العنوان بنجاح!';
            titleElement.style.color = 'red'; // تعديل مباشر يكسر React!
        }
        
        // خطأ قاتل 2: تعديل الحالة المباشر بالتحوير (Mutation)
        attributes.items.push( 'عنصر جديد' ); // ممنوع منعاً باتاً!
        setAttributes( { items: attributes.items } ); // لن يشعر React بالتغيير!
    };

    return (
        

            
{ attributes.title }
            اضغط هنا لتعديل العنوان
        
    );
}

لماذا يتدمر هذا البلوك؟

• استخدام document.getElementById يكسر عزل المكونات؛ فلو كرر المحرر نفس البلوك 3 مرات في المقال، الكود سيعدل أول بلوك فقط ويتجاهل الباقي!
• تعديل الـ DOM المباشر يختفي فوراً بمجرد أن تعيد React رسم المكون، لإن React سترسم ما هو مخزن في الـ State وليس ما عدلته في الـ DOM.
• تحوير المصفوفة بـ push يجعل مرجع المصفوفة في الذاكرة كما هو (Same Reference)، وبالتالي React تفترض أن البيانات لم تتغير ولا تعيد رسم الشاشة!

2. النموذج السليم: الكود التصريحي النقي مع الحفاظ على الـ Immutability

// ✅ الكود الهندسي القياسي المتوافق بنسبة 100% مع النموذج الذهني لـ React
import { useBlockProps, RichText } from '@wordpress/block-editor';
import { useState } from '@wordpress/element';
import { Button } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

export default function Edit( { attributes, setAttributes } ) {
    const { title, items } = attributes;
    
    // حالة محلية عابرة للواجهة فقط: هل القائمة مطوية أم مفتوحة؟
    const [ isCollapsed, setIsCollapsed ] = useState( false );

    const blockProps = useBlockProps( {
        className: 'az-pure-react-block'
    } );

    // إضافة عنصر جديد بدون تحوير المصفوفة القديمة (Immutable Update)
    const handleAddItem = () => {
        const newItem = `عنصر إضافي رقم ${ items.length + 1 }`;
        // إنشاء مصفوفة جديدة بالكامل باستخدام مشغل النشر (Spread Operator)
        setAttributes( { items: [ ...items, newItem ] } );
    };

    return (
        

             setAttributes( { title: newTitle } ) }
                placeholder={ __( 'اكتب العنوان هنا تصريحياً...', 'az-mental' ) }
                className="az-block-heading"
            />

            

                 setIsCollapsed( ! isCollapsed ) }>
                    { isCollapsed ? __( 'إظهار العناصر', 'az-mental' ) : __( 'طي القائمة', 'az-mental' ) }
                
                
                    { __( 'إضافة عنصر جديد', 'az-mental' ) }
                
            

            { /* الرندرة الشرطية (Conditional Rendering) تعتمد حصرياً على الحالة */ }
            { ! isCollapsed && (
                

                    { items.map( ( item, index ) => (
                        

                            { item }
                        
                    ) ) }
                
            ) }
        
    );
}

أسرار القوة الهندسية في النموذج السليم:

• [ ...items, newItem ]: لم نقم بلمس المصفوفة القديمة؛ بل أنشأنا مصفوفة جديدة كلياً في الذاكرة، مما يطلق مقارنة المراجع في React ويعيد رسم القائمة بسلاسة وفورية.
• ! isCollapsed && (...): إظهار وإخفاء القائمة يتم برمجياً في الـ JSX بناءً على حالة الـ isCollapsed دون الحاجة لإضافة وإزالة كلاسات CSS يدوياً عبر الـ DOM.

دراسة حالة واقعية: أزمة منصة العيادات الطبية وحجز المواعيد في مدينة نصر

الوصايا العشر للنموذج الذهني لـ React لمطوري Gutenberg

1. UI = f(State) هي عقيدتك الأولى: لا تعدل الـ DOM بيدك أبداً؛ غير الحالة ودع React تتولى طلاء الواجهة.
2. إياك ولمس Real DOM: احظر تماماً استخدام document.getElementById أو querySelector أو دوال jQuery داخل ملفات البلوك.
3. احترم قدسية Immutability: لا تعدل المصفوفات بـ push أو الكائنات مباشرة؛ دائماً أنشئ نسخة جديدة عبر [ ...oldArray, newItem ].
4. استخدم setAttributes للبيانات الدائمة فقط: إذا كانت المعلومة مؤقتة للواجهة ولا تهم المقال، خزنها في useState محلياً.
5. احذر من الحلقات اللانهائية في useEffect: لا تستدعِ setAttributes داخل useEffect دون تحديد مصفوفة اعتماديات دقيقة وصارمة.
6. احسب البيانات المشتقة ولا تخزنها: إذا كان بإمكانك حساب “إجمالي السعر” بجمع المنتجات، فلا تخزنه كـ Attribute منفصل لتجنب عدم اتساق البيانات.
7. اعتمد على مكونات @wordpress/components: وفر على نفسك آلاف الساعات واستخدم الحقول والأزرار القياسية المجهزة لسهولة الوصول.
8. افصل المنطق عن العرض (Custom Hooks): ضع العمليات الحسابية المعقدة والاتصال بالـ API في دوال وخطافات مخصصة خارج جسم الـ JSX.
9. استخدم key فريد وثابت في القوائم: لا تستخدم فهرس المصفوفة index كمفتاح للـ key إذا كانت العناصر قابلة للحذف أو إعادة الترتيب.
10. فكر كمصمم معماري وليس ككاتب سكربتات: انظر للبلوك كنظام متكامل يدير حالته بدقة وليس مجرد كود HTML مكسو ببعض الجافاسكريبت.

المعمارية المتقدمة: رفع الحالة (State Lifting) ونمط useReducer في البلوكات المعقدة

يا صديقي المطور، لما البلوك بتاعك يكبر ويتحول من مجرد حقل نصي بسيط لأداة تفاعلية ضخمة—زي مثلاً “حاسبة قروض بنكية” أو “نظام تخصيص منتجات ووكومرس” يحتوي على 15 حقلاً وخيارات متشابكة—الاعتماد على useState منفصل لكل حقل بيبدأ يتحول لفوضى برمجية تسمى “State Spaghetti”.

هنا بنلجأ لنمطين معماريين من أصول React الاحترافية:

1. رفع الحالة (Lifting State Up):

إذا كان عندك مكونين فرعيين داخل البلوك (مثلاً: مكون منتقي المنتجات ومكون ملخص الفاتورة)، وكلاهما يحتاج لمعرفة المنتج المختار؛ لا تحاول جعل المكونين يتحدثان لبعضهما بشكل جانبي (Sibling-to-Sibling Communication). الحل الهندسي هو “رفع الحالة” للمكون الأب المشترك (دالة Edit الرئيسية)، وتمرير البيانات للأسفل كـ props، مع تمرير دالة تغيير (Callback) يستدعيها الابن عند حدوث تفاعل.

2. نمط useReducer لإدارة التحديثات المعقدة المتشابكة:

عندما يعتمد تعديل حقل معين على قيمة حقل آخر (مثلاً: تغيير مدة القرض يعيد حساب الفائدة الشهرية وإجمالي الأقساط)، فإن نمط useReducer هو الأداة المثالية لعزل منطق العمليات الحسابية عن واجهة الـ JSX.

كود عملي: إدارة حاسبة مالية متقدمة عبر useReducer في Gutenberg

/**
 * إدارة حالة حاسبة التمويل العقاري داخل بلوك جوتنبرج
 */
import { useReducer } from '@wordpress/element';
import { useBlockProps } from '@wordpress/block-editor';
import { TextControl, RangeControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

// 1. الدالة الصافية لإدارة الحسابات (Pure Reducer Function)
function loanCalculatorReducer( state, action ) {
    switch ( action.type ) {
        case 'UPDATE_PROPERTY_PRICE': {
            const price = action.payload;
            const downPayment = price * ( state.downPaymentPercent / 100 );
            const loanAmount = price - downPayment;
            return {
                ...state,
                propertyPrice: price,
                downPaymentAmount: downPayment,
                loanAmount: loanAmount,
            };
        }
        case 'UPDATE_DOWN_PAYMENT_PERCENT': {
            const percent = action.payload;
            const downPayment = state.propertyPrice * ( percent / 100 );
            return {
                ...state,
                downPaymentPercent: percent,
                downPaymentAmount: downPayment,
                loanAmount: state.propertyPrice - downPayment,
            };
        }
        default:
            return state;
    }
}

export default function Edit( { attributes, setAttributes } ) {
    const blockProps = useBlockProps( { className: 'az-loan-calculator-box' } );

    // 2. ربط الـ Reducer بحالة البلوك المبدئية
    const [ state, dispatch ] = useReducer( loanCalculatorReducer, {
        propertyPrice: attributes.propertyPrice || 2000000,
        downPaymentPercent: attributes.downPaymentPercent || 20,
        downPaymentAmount: 400000,
        loanAmount: 1600000,
    } );

    // مزامنة التحديثات المعقدة مع خصائص البلوك المركزية
    const handlePriceChange = ( newPrice ) => {
        const val = parseFloat( newPrice ) || 0;
        dispatch( { type: 'UPDATE_PROPERTY_PRICE', payload: val } );
        setAttributes( { propertyPrice: val } );
    };

    return (
        

            
{ __( 'حاسبة التمويل العقاري التفاعلية (React Reducer)', 'az-mental' ) }
            
            

             {
                    dispatch( { type: 'UPDATE_DOWN_PAYMENT_PERCENT', payload: val } );
                    setAttributes( { downPaymentPercent: val } );
                } }
                min={ 10 }
                max={ 50 }
            />

            

                
مبلغ الدفعة المقدمة: { state.downPaymentAmount.toLocaleString() } ج.م
                
إجمالي مبلغ التمويل المطلوب: { state.loanAmount.toLocaleString() } ج.م
            
        
    );
}

القيمة المعمارية لنمط useReducer:
لاحظ كيف تم عزل العمليات الحسابية بالكامل داخل دالة loanCalculatorReducer الصافية! هذه الدالة خالية من أي كود DOM أو React، ويمكنك كتابة اختبارات وحدة آلية (Unit Tests) لها في ثوانٍ معدودة للتأكد من دقة حسابات القروض البنكية قبل دمجها في واجهة محرر ووردبريس.