شرح معمارية @wordpress/data في جوتنبرج: الحالة المشتركة والاشتراك في تغييرات المحرر

أهلاً بيك يا صديقي المطور في العقل المدبر ومحطة التحكم المركزية لمحرر Gutenberg بالكامل: حزمة @wordpress/data.

لو أنت مبرمج واجهات وكتبت تطبيقات React متوسطة أو كبيرة، فأنت أكيد قابلت مكتبة Redux وعارف فكرتها: مخزن حالة مركزي (Single Source of Truth)، مع Actions و Reducers و Selectors. لكن لما فريق ووردبريس قرر يبني محرر جوتنبرج، اكتشفوا إن تطبيق Redux التقليدي بأسلوبه القديم مش هيكون كافي لمنظومة ضخمة ومفتوحة المصدر بيشتغل فيها مئات الإضافات والقوالب في نفس الوقت!

فريق النواة قرر يبني حزمة مخصصة اسمها @wordpress/data، وهي إعادة هندسة عبقرية لـ Redux مبنية على مفهوم سجل المخازن المعياري (Modular Store Registry). في المعمارية دي، مفيش مخزن وحيد عملاق بيبتلع كل حاجة، بل فيه “سجل مركزي” بيحتوي على عشرات المخازن المستقلة (زي مخزن المقال core/editor، مخزن البلوكات core/block-editor، مخزن الإشعارات core/notices)، مع نظام وسيط عبقري اسمه Resolvers بيجلب البيانات من الـ REST API في الخلفية تلقائياً أول ما تطلبها بدون وجع دماغ! في المقال ده، هنفكك المعمارية التحتية لـ @wordpress/data، إزاي تشترك في أحداث المحرر (زي حفظ المقال أو تغيير البلوك المحدد)، وإزاي تقفل زرار النشر برمجياً لو فيه أخطاء، مع كود إنتاجي ودراسة حالة حقيقية لشركة سياحة بالبحر الأحمر بالعامية المصرية التقنية الأصيلة.

منظومة المخازن الرئيسية في محرر Gutenberg (Core Stores)

عشان تعرف من أين تؤكل الكتف، لازم تكون عارف أسماء المخازن الرسمية المدمجة في ووردبريس ومسؤولية كل مخزن:

1. مخزن المقال العام (core/editor):

   المسؤول عن دورة حياة التدوينة المعروضة حالياً. يحتوي على معلومات: عنوان المقال، المحتوى الخام، حالة الحفظ (هل جاري الحفظ؟ isSavingPost)، هل المقال به تعديلات غير محفوظة؟ (isEditedPostDirty)، وإمكانية قفل زر النشر عبر lockPostSaving.

2. مخزن محرر البلوكات (core/block-editor):

   المسؤول عن شجرة البلوكات التفاعلية. يحتوي على قائمة كافة البلوكات الموجودة في المقال، من هو البلوك المحدد حالياً (getSelectedBlock)، ويوفر دوال إدراج وحذف ونقل وتكرار البلوكات برمجياً.

3. مخزن كيانات ووردبريس المركزية (core):

   المسؤول عن جلب وتحديث السجلات والبيانات من قاعدة البيانات والـ REST API (مثل: المنشورات، المستخدمين، التصنيفات، التعليقات، والوسائط) عبر دوال سحرية مثل getEntityRecord.

4. مخزن التنبيهات والإشعارات (core/notices):

   المسؤول عن إظهار رسائل التحذير والنجاح العائمة في أعلى المحرر أو أسفل الشاشة عبر createErrorNotice و createSuccessNotice.

سحر الـ Resolvers: كيف تجلب البيانات من السيرفر في صمت؟

في Redux العادي، لما تحب تجلب بيانات مستخدم، بتضطر تشغل Action اسمها FETCH_USER_REQUEST، وتعمل fetch، ولما يرجع تطلق FETCH_USER_SUCCESS. في @wordpress/data، أنت مش محتاج تعمل أي حاجة من دول في مكوناتك!

أنت بتطلب المعلومة مباشرة من الـ Selector:

const user = useSelect( ( select ) => {
    return select( 'core' ).getEntityRecord( 'root', 'user', 1 );
}, [] );

ما الذي يحدث في الخلفية برمجياً؟

• الـ Selector بيفحص الذاكرة: “هل بيانات المستخدم رقم 1 موجودة عندي في الكاش؟”.
• لو مش موجودة، الـ Selector بيطلق تلقائياً الـ Resolver المرتبط بيه.
• الـ Resolver بيروح يكلم الـ WordPress REST API (/wp/v2/users/1)، يسحب البيانات، ويخزنها في الـ Store المركزي.
• بمجرد ما البيانات توصل، الـ Selector بيعيد استدعاء نفسه، والكومبوننت بتاعك بيستلم كائن الـ user الكامل ويبدأ يعرضه فوراً بدون كتابة سطر fetch واحد!

تطبيق عملي كامل: قفل زر نشر المقال برمجياً إذا كانت البيانات غير مكتملة

تعال نبني معمارية حقيقية لإضافة تراقب محتوى المقال؛ لو المقال يحتوي على بلوك عروض سياحية، وكاتب المحتوى نسي يحدد “تاريخ انتهاء الخصم”، نقوم فوراً بقفل زر “نشر” (Publish) في ووردبريس، ونعرض شريط تحذير أحمر في لوحة الإشعارات المركزية:

1. كود المكون الرقابي المتصل بمخزن البيانات: PublisherGuard.js

import { useEffect } from '@wordpress/element';
import { useSelect, useDispatch } from '@wordpress/data';
import { __ } from '@wordpress/i18n';

export default function PublisherGuard() {
    // 1. استخراج دوال التحكم من المخازن المركزية
    const { lockPostSaving, unlockPostSaving } = useDispatch( 'core/editor' );
    const { createErrorNotice, removeNotice } = useDispatch( 'core/notices' );

    // 2. قراءة بيانات المقال والبلوكات عبر Selectors دقيقة
    const { isOfferIncomplete, isSaving } = useSelect( ( select ) => {
        const { getBlocks } = select( 'core/block-editor' );
        const { isSavingPost } = select( 'core/editor' );

        const allBlocks = getBlocks();
        
        // البحث عن بلوك العروض السياحية في شجرة المقال
        const offerBlock = allBlocks.find( ( b ) => b.name === 'enterprise/travel-offer' );
        
        // التحقق مما إذا كان البلوك موجوداً وتاريخ الانتهاء فارغ
        const incomplete = offerBlock && ! offerBlock.attributes?.expiryDate;

        return {
            isOfferIncomplete: incomplete,
            isSaving: isSavingPost(),
        };
    }, [] );

    // 3. مراقبة الحالة واتخاذ القرار المعماري بقفل أو فتح النشر
    useEffect( () => {
        const lockKey = 'az-travel-offer-missing-expiry';
        const noticeId = 'az-missing-expiry-notice';

        if ( isOfferIncomplete ) {
            // قفل زر الحفظ والنشر في لوحة تحكم ووردبريس
            lockPostSaving( lockKey );

            // إظهار إشعار خطأ أحمر بارز في أعلى المحرر
            createErrorNotice(
                __( 'تنبيه إداري: لا يمكن نشر المقال؛ برجاء تحديد تاريخ انتهاء العرض السياحي أولاً لحماية حقوق الحجز.', 'az-data' ),
                {
                    id: noticeId,
                    isDismissible: false,
                }
            );
        } else {
            // فك قفل النشر فور إكمال البيانات
            unlockPostSaving( lockKey );
            removeNotice( noticeId );
        }

        // تنظيف القفل عند إلغاء تحميل المكون
        return () => {
            unlockPostSaving( lockKey );
            removeNotice( noticeId );
        };
    }, [ isOfferIncomplete, lockPostSaving, unlockPostSaving, createErrorNotice, removeNotice ] );

    // هذا المكون وظيفي خالص ولا يعرض أي عناصر HTML بصرية في المقال
    return null;
}

2. كود الاشتراك الأمري المستقل: wp.data.subscribe (Vanilla JS Listener)

إذا كنت تريد مراقبة المحرر من سكربت جافاسكريبت خارجي دون الحاجة لكتابة مكون React كامل، يمكنك استخدام دالة subscribe المباشرة:

/**
 * مراقبة تغييرات حالة المقال بأمر مباشر من الكونسول أو سكربت خارجي
 */
let wasSaving = false;

const unsubscribe = wp.data.subscribe( () => {
    const editorSelect = wp.data.select( 'core/editor' );
    if ( ! editorSelect ) return;

    const isSaving = editorSelect.isSavingPost();
    const isAutosaving = editorSelect.isAutosavingPost();

    // رصد لحظة انتهاء عملية الحفظ اليدوي الفعلي للمقال
    if ( wasSaving && ! isSaving && ! isAutosaving ) {
        console.info( '🎉 تم حفظ وتحديث المقال في قاعدة البيانات بنجاح تام!' );
        const currentPost = editorSelect.getCurrentPost();
        console.log( 'معرف المقال المحفوظ:', currentPost.id, 'العنوان:', currentPost.title );
    }

    wasSaving = isSaving;
} );

// لإلغاء الاشتراك عند عدم الحاجة:
// unsubscribe();

دراسة حالة واقعية: كارثة منصة حجز رحلات شرم الشيخ والغردقة

الوصايا العشر لمعمارية @wordpress/data في جوتنبرج

1. استخدم useSelect بحكمة وترشيد: لا تستخرج كائن المقال بالكامل إذا كنت تحتاج لعنوان المقال فقط؛ ترشيد الـ Selectors يحمي المتصفح من إعادة الرسم غير الضروري.
2. اقفل زر النشر بـ lockPostSaving عند الخطر: لا تعتمد على حسن نية الكاتب؛ احمِ موقعك وأعمالك بقفل النشر برمجياً إذا كانت البيانات الإلزامية غير مكتملة.
3. حدد مفتاحاً فريداً لكل قفل (Lock Key): استخدم دائماً معرفاً فريداً مثل vendor/lock-reason حتى لا تلغي قفلاً وضعه مكون آخر بالخطأ.
4. نظف القفل دائماً عند الـ Unmount: تأكد من فك القفل في دالة التنظيف المرتجعة لـ useEffect حتى لا يظل المقال معلقاً إذا تم حذف البلوك.
5. اعتمد على Resolvers ولا تكتب fetch يدوياً: استخدم getEntityRecord في مخزن core ودع ووردبريس يتولى التخزين المؤقت والاتصال بالشبكة.
6. وظف core/notices للإشعارات الرسمية: لا تبنِ أشرطة تنبيه مخصصة في الـ DOM؛ استخدم لوحة تنبيهات ووردبريس الموحدة لضمان تجربة مستخدم قياسية.
7. احذر من استدعاء dispatch داخل دالة useSelect: خطاف useSelect مخصص للقراءة فقط (Read-only)؛ أي استدعاء لتعديل الحالة بداخله سيطلق حلقة لانهائية قاتلة!
8. استخدم wp.data.select في الكونسول للتنقيح السريع: افتح DevTools واكتب wp.data.select('core/editor').getCurrentPost() لاكتشاف البيانات في ثوانٍ.
9. افصل المخازن المخصصة لنطاقات واضحة: إذا قمت بإنشاء مخزن مخصص عبر registerStore، سمه باسم واضح مثل my-plugin/cart.
10. اختبر سلوك الحفظ التلقائي (Autosave): تأكد من أن شفرتك البرمجية تفرق بين الحفظ التلقائي في الخلفية والحفظ اليدوي الصريح بواسطة المستخدم.

معمارية بناء مخزن مخصص بالكامل عبر createReduxStore

يا صديقي المطور، عندما تبني نظاماً معقداً داخل ووردبريس—مثل نظام إدارة دورات تدريبية متقدم، أو نظام سلة مشتريات تفاعلية، أو حاسبة أسعار شحن مخصصة لشركات التوصيل في مصر—فإن الاعتماد على مخازن النواة فقط قد لا يكون كافياً. أنت بحاجة لإنشاء مخزن بيانات مخصص (Custom Redux Store) يمتلك حالة خاصة به، ويوفر Selectors و Actions يستفيد منها كل بلوك وكل نافذة في موقعك.

في الإصدارات الأولى، كنا نستخدم دالة registerStore القديمة. أما في ووردبريس الحديث، المعيار الذهبي هو استخدام دالة createReduxStore ثم تسجيلها في السجل المركزي register.

كود عملي متكامل: بناء مخزن سلة مشتريات مخصص (Enterprise Cart Store)

/**
 * ملف تسجيل مخزن سلة المشتريات المركزي
 * File: store/cart-store.js
 */
import { createReduxStore, register } from '@wordpress/data';

// 1. الحالة المبدئية للمخزن
const DEFAULT_STATE = {
    items: [],
    couponCode: '',
    discountAmount: 0,
    isUpdating: false,
};

// 2. معالجات الإجراءات (Actions)
const actions = {
    addItem( item ) {
        return {
            type: 'ADD_ITEM',
            payload: item,
        };
    },
    removeItem( itemId ) {
        return {
            type: 'REMOVE_ITEM',
            payload: itemId,
        };
    },
    applyCoupon( code, discount ) {
        return {
            type: 'APPLY_COUPON',
            payload: { code, discount },
        };
    },
    setUpdating( isUpdating ) {
        return {
            type: 'SET_UPDATING',
            payload: isUpdating,
        };
    },
};

// 3. الدالة الصافية لإدارة الحالة (Reducer)
function reducer( state = DEFAULT_STATE, action ) {
    switch ( action.type ) {
        case 'ADD_ITEM':
            return {
                ...state,
                items: [ ...state.items, action.payload ],
            };
        case 'REMOVE_ITEM':
            return {
                ...state,
                items: state.items.filter( ( item ) => item.id !== action.payload ),
            };
        case 'APPLY_COUPON':
            return {
                ...state,
                couponCode: action.payload.code,
                discountAmount: action.payload.discount,
            };
        case 'SET_UPDATING':
            return {
                ...state,
                isUpdating: action.payload,
            };
        default:
            return state;
    }
}

// 4. محددات القراءة (Selectors)
const selectors = {
    getItems( state ) {
        return state.items;
    },
    getItemsCount( state ) {
        return state.items.length;
    },
    getTotalPrice( state ) {
        const subtotal = state.items.reduce( ( sum, item ) => sum + ( item.price * ( item.qty || 1 ) ), 0 );
        return Math.max( 0, subtotal - state.discountAmount );
    },
    isCartUpdating( state ) {
        return state.isUpdating;
    },
};

// 5. إنشاء وتسجيل المخزن في سجل ووردبريس المركزي
const STORE_NAME = 'enterprise/cart';

export const cartStore = createReduxStore( STORE_NAME, {
    reducer,
    actions,
    selectors,
} );

// تسجيل المخزن رسمياً في سجل wp.data
register( cartStore );

كيف تستهلك هذا المخزن داخل أي بلوك في موقعك؟

بمجرد تسجيل هذا المخزن، يصبح متاحاً فورياً لكافة مكونات React بنفس أسلوب مخازن النواة تماماً:

import { useSelect, useDispatch } from '@wordpress/data';
import { Button } from '@wordpress/components';
import { cartStore } from './store/cart-store';

export function CartSummaryWidget() {
    // قراءة البيانات من المخزن المخصص
    const { total, count } = useSelect( ( select ) => {
        const store = select( cartStore ); // أو select('enterprise/cart')
        return {
            total: store.getTotalPrice(),
            count: store.getItemsCount(),
        };
    }, [] );

    // سحب دوال التحديث
    const { addItem } = useDispatch( cartStore );

    return (
        

            عدد العناصر: { count }
            الإجمالي: { total.toLocaleString() } ج.م
             addItem( { id: Date.now(), name: 'منتج تجريبي', price: 250, qty: 1 } ) }
            >
                إضافة منتج سريع
            
        
    );
}

معمارية التحديثات التفاؤلية (Optimistic Updates in Data Stores)

في تجربة المستخدم الحديثة، عندما يضغط المستخدم على زر “حفظ” أو “إعجاب”، الانتظار حتى يرد السيرفر بعد 500 مللي ثانية يشعر الزائر بالبطء والتردد.

تعتمد ووردبريس في مخزن core على ما يسمى بـ Optimistic Updates:

1. يقوم المخزن فورياً بتحديث الواجهة في الذاكرة الحية وإظهار النتيجة للمستخدم فور النقر (وكأن السيرفر وافق بالفعل).
2. في الخلفية، يقوم الـ Control بإرسال طلب الـ HTTP الفعلي لنقطة النهاية في الـ REST API.
3. إذا نجح الطلب، يتم تأكيد الحالة بهدوء دون أي وميض.
4. إذا فشل الطلب (مثل انقطاع الإنترنت أو حدوث خطأ 500)، يقوم المخزن تلقائياً بـ Rollback والتراجع عن التغيير، مع إطلاق إشعار خطأ في core/notices لإعلام المستخدم بسبب الفشل.

هذا المستوى الرفيع من النضج الهندسي هو ما يجعل تطبيقات ووردبريس ومحرر Gutenberg تنافس أرقى تطبيقات الـ Single Page Applications العالمية في السرعة وسلاسة الاستجابة.

معايير توثيق واختبار مخازن البيانات في بيئة الإنتاج

عندما تطور مخازن بيانات مركزية للمؤسسات الكبرى، احرص دائماً على كتابة اختبارات وحدة آلية (Unit Tests) للـ Reducers والـ Selectors بشكل منفصل عن مكونات الواجهة. بما أن الـ Reducer دالة صافية خالية من أي آثار جانبية، يمكنك اختبار كافة الحالات الممكنة لسلة المشتريات أو إدارة الحجوزات بدقة حاسوبية 100%، مما يضمن أمان المعاملات المالية واستقرار موقعك في كافة الظروف.