مكونات React في Gutenberg: حقول واضحة وأدوات تحرير قابلة للوصول بـ @wordpress/components

أهلاً بيك يا صديقي المطور في الكنز البرمجي الأكبر في عالم ووردبريس الحديث: حزمة @wordpress/components.

لو سألت أي مبرمج فرونت إند شغال في شركة عالمية عن أصعب حاجة في بناء واجهات المستخدم (UI Design Systems)، هيقولك كلمتين: “إمكانية الوصول (Accessibility – a11y)” و”الاتساق البصري عبر الشاشات المختلفة”. تخيل بقى إنك كمطور ووردبريس، عندك مكتبة عملاقة فيها أكتر من 70 مكون جاهز ومجرب، مبنية ومختبرة بواسطة أفضل مهندسي الويب في العالم، ومصممة خصيصاً عشان تشتغل جوة لوحة تحكم ووردبريس بنفس الخطوط، ونفس الألوان، ونفس سلوك التنقل بلوحة المفاتيح والـ Screen Readers!

المأساة إن في مطورين كتير لسه بيكتبوا وسوم <input type="text"> و <select> عادية بستايلات عشوائية داخل شريط الـ Inspector، وده بيخلق واجهات مشوهة تكسر معايير الويب العالمية وتفشل في اختبارات الجودة الدولية. في المقال ده، هنشرح الفئات الأربعة لمكتبة @wordpress/components، إزاي تبني لوحات تحكم وأشرطة أدوات متطورة وقابلة للوصول 100%، وليه استخدام الحزمة دي بيوفر عليك شهور من التطوير، مع كود إنتاجي ودراسة حالة حقيقية لبوابة خدمات حكومية مصرية بالعامية المصرية التقنية الأصيلة.

التصنيف المعماري لمكونات @wordpress/components

المكتبة منظمة في أربع عائلات رئيسية تغطي كافة احتياجات البلوكات المتقدمة:

1. حقول النماذج والإدخال (Form Controls):

• TextControl: حقل نصي مدعوم بعنوان (Label) ونص إرشادي (Help Text) ومعرف فريد تلقائي.
• TextareaControl: حقل نصوص متعدد الأسطر مع دعم ضبط الارتفاع التلقائي.
• SelectControl: قائمة منسدلة قياسية متوافقة تماماً مع معايير الـ a11y.
• ToggleControl: مفتاح تبديل عصري (Switch) للخيارات المنطقية (Boolean On/Off)، وهو البديل الأرقى لـ Checkbox التقليدي.
• RangeControl: شريط تمرير منزلق (Slider) مع حقل رقمي متزامن لتحديد الأرقام والنسب المئوية.
• ComboboxControl: حقل بحث ذكي وفلترة مع قائمة منسدلة يدعم إكمال النصوص تلقائياً (Autocomplete).

2. التخطيط وهيكلة اللوحات (Layout & Containers):

• PanelBody & PanelRow: اللبنة الأساسية لبناء أقسام الشريط الجانبي (InspectorControls) القابلة للطي والفتح.
• Card, CardBody, CardHeader: بناء بطاقات أنيقة وعصرية داخل واجهة البلوك أو شريط الإعدادات.
• Flex & FlexItem: نظام تخطيط Flexbox تصريحي يغنيك عن كتابة أي قواعد CSS للمحاذاة والتباعد.

3. التفاعل والتنبيهات (Overlays & Feedback):

• Modal: نافذة منبثقة معزولة مع قفل فوكس تلقائي (Focus Lock) لدعم الإعدادات المتقدمة دون زحام الشاشة.
• Notice: شريط تنبيهات ملون (Success, Warning, Error, Info) لتنبيه المحرر للأخطاء والتعليمات.
• Spinner: مؤشر تحميل دائري قياسي أثناء استدعاء بيانات الـ API في الواجهة الخلفية.
• Tooltip: تلميح نصي ذكي يظهر عند تحريك الفأرة فوق الأيقونات لتعريف المحرر بوظيفتها.

4. أشرطة الأدوات والأزرار (Actions & Toolbars):

• Button & ButtonGroup: أزرار قياسية بكافة التنويعات الرسمية (primary، secondary، tertiary، destructive).
• ToolbarGroup & ToolbarButton: المكونات الرسمية لوضع أزرار داخل شريط أدوات البلوك العلوي (BlockControls).

تطبيق عملي كامل: بناء لوحة إعدادات احترافية متوافقة مع إمكانية الوصول (Enterprise Inspector Panel)

تعال نبني مع بعض شريط إعدادات جانبي لبلوك حجز استشارات حكومية وضريبية (enterprise/tax-consultation) يوضح كيف ندمج أكثر من 7 مكونات قياسية في تناغم بصري وهندسي تام:

1. إعداد ملف block.json

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/tax-consultation",
  "version": "1.0.0",
  "title": "حجز استشارة ضريبية معتمدة",
  "category": "widgets",
  "icon": "clipboard",
  "attributes": {
    "consultantName": { "type": "string", "default": "" },
    "serviceType": { "type": "string", "default": "income_tax" },
    "isUrgent": { "type": "boolean", "default": false },
    "estimatedHours": { "type": "number", "default": 2 },
    "requiresInvoice": { "type": "boolean", "default": true }
  },
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

2. كود واجهة التحرير: edit.js بالمكونات القياسية ونوافذ الـ Modal

import { useBlockProps, InspectorControls, BlockControls } from '@wordpress/block-editor';
import {
    PanelBody,
    TextControl,
    SelectControl,
    ToggleControl,
    RangeControl,
    Notice,
    ToolbarGroup,
    ToolbarButton,
    Button,
    Modal,
    Flex,
    FlexItem
} from '@wordpress/components';
import { useState } from '@wordpress/element';
import { __ } from '@wordpress/i18n';
import './editor.scss';

export default function Edit( { attributes, setAttributes } ) {
    const { consultantName, serviceType, isUrgent, estimatedHours, requiresInvoice } = attributes;
    
    // حالة محلية للتحكم في فتح وغلق نافذة الدليل الإرشادي
    const [ isHelpModalOpen, setIsHelpModalOpen ] = useState( false );

    const blockProps = useBlockProps( {
        className: 'az-tax-consultation-editor'
    } );

    return (
        

            { /* 1. شريط أدوات البلوك العلوي (Block Controls) */ }
            
                
                     setIsHelpModalOpen( true ) }
                    />
                
            

            { /* 2. شريط الإعدادات الجانبي الشامل (Inspector Controls) */ }
            
                
                    { isUrgent && (
                        
                            { __( 'تنبيه: الخدمة العاجلة تتطلب اعتماداً فورياً من المستشار المناوب.', 'az-tax' ) }
                        
                    ) }

                     setAttributes( { consultantName: val } ) }
                        placeholder={ __( 'مثلاً: د. أحمد فؤاد', 'az-tax' ) }
                        help={ __( 'الاسم الذي سيظهر في استمارة الحجز الرسمية للعميل.', 'az-tax' ) }
                    />

                     setAttributes( { serviceType: val } ) }
                    />

                     setAttributes( { isUrgent: val } ) }
                    />

                     setAttributes( { estimatedHours: val } ) }
                        min={ 1 }
                        max={ 8 }
                        step={ 1 }
                    />

                     setAttributes( { requiresInvoice: val } ) }
                    />
                
            

            { /* 3. واجهة البلوك المعروضة داخل المقال */ }
            

                
                    
                        
{ consultantName || __( 'يرجى كتابة اسم المستشار في الشريط الجانبي', 'az-tax' ) }
                        
{ serviceType }
                    
                    
                        { estimatedHours } { __( 'ساعات', 'az-tax' ) }
                    
                
            

            { /* 4. نافذة منبثقة للمساعدة (Accessible Modal Dialog) */ }
            { isHelpModalOpen && (
                 setIsHelpModalOpen( false ) }
                    className="az-tax-help-modal"
                >
                    

                        { __( 'وفقاً لقرارات مصلحة الضرائب المصرية الأخيرة، يجب تسجيل رقم التسجيل الضريبي الموحد لكافة الشركات قبل تأكيد حجز جلسة الاستشارة الفنية.', 'az-tax' ) }
                    
                    

                         setIsHelpModalOpen( false ) }>
                            { __( 'فهمت التعليمات ومتابعة الحجز', 'az-tax' ) }
                        
                    
                
            ) }
        
    );
}

هندسة إمكانية الوصول (Accessibility – a11y): لماذا تحميك هذه المكونات؟

لما تستخدم TextControl من حزمة ووردبريس، الكومبوننت ده بيعمل في الخلفية عمليات معقدة لا يراها المستخدم العادي:

• توليد معرف تلقائي (Auto-generated Unique ID): يولد معرفاً عشوائياً مثل inspector-text-control-42 ويربط وسم <label for="..."> بوسم <input id="..."> تلقائياً، وهو شرط إلزامي لقارئات الشاشة.
• إدارة نصوص المساعدة (Aria Describedby): يربط نص الـ Help عبر السمة الدلالية aria-describedby حتى يقرأه موزع الصوت للمكفوفين بمجرد الوقوف على الحقل.
• قفل الفوكس في الـ Modals (Focus Trapping): عندما تفتح نافذة Modal، يقوم المكون بحبس مؤشر لوحة المفاتيح داخل النافذة، لمنع المستخدم الكفيف من التنقل بالخطأ في خلفية الصفحة غير المرئية له!

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

الوصايا العشر لاستخدام مكونات React في جوتنبرج

1. استخدم @wordpress/components دائماً: لا تكتب وسم <input> خام بيدك أبداً؛ اعتمد على المكونات الرسمية الجاهزة.
2. وفر label دقيق وواضح لكل حقل: لا تكتفِ بالـ placeholder؛ العنوان الصريح هو خط الدفاع الأول لإمكانية الوصول.
3. استخدم ToggleControl بدلاً من Checkbox للخيارات المنطقية: هو أكثر عصرية وتفاعلية وسهولة في اللمس على الهواتف.
4. ضع الحقول الإضافية في InspectorControls: لا تزحم مساحة المقال الرئيسية؛ اجعل المقال للنصوص والشريط الجانبي للإعدادات.
5. استخدم RangeControl للقيم الرقمية المقيدة: يمنع الأخطاء المطبعية ويتيح تجربة سحب بصرية ممتازة مع إدخال رقمي مباشر.
6. قدم نصوص مساعدة (help text) ذكية: اشرح للمحرر ما الذي سيتغير في الموقع عند تفعيل هذا الخيار.
7. استخدم Modal للإعدادات المعقدة والنادرة: إذا كان لديك جدول خيارات ضخم، اعرضه في نافذة منبثقة لحماية بساطة الشريط الجانبي.
8. احذر من تكرار Notice دون إمكانية إغلاق: لا تجعل التنبيهات تغطي الواجهة؛ استخدم isDismissible={true} متى أمكن.
9. وظف BlockControls للوظائف الحصرية والسريعة: شريط الأدوات العلوي مخصص للأيقونات السريعة (المحاذاة، الروابط، الحذف).
10. اختبر إمكانية الوصول بمفتاح Tab فقط: ضع الفأرة جانباً وتأكد أنك تستطيع التنقل بين كافة الحقول والضغط على الأزرار بلوحة المفاتيح وحدها.

معمارية رفع الوسائط وإدارة الصلاحيات (MediaUpload & MediaUploadCheck)

يا صديقي المطور، لما تبني بلوك بيتعامل مع الصور أو الفيديوهات أو ملفات الـ PDF (زي كارت شخصي أو بانر رئيسي)، أكبر خطأ معماري تقع فيه هو إنك تستخدم زر <input type="file"> عادي. ووردبريس بيمتلك مكتبة وسائط مركزية ضخمة (Media Library)، والتعامل الصحيح معها بيتطلب مكونين أساسيين من حزم ووردبريس:

1. MediaUploadCheck: مكون أمان لفحص صلاحيات المستخدم الحالي (Permissions Guard). لو كان الكاتب الحالي “مساهم” (Contributor) وليس لديه صلاحية upload_files، هذا المكون يقوم بإخفاء زر رفع الصور تلقائياً حتى لا يتعطل البلوك أو تظهر أخطاء أمنية في الكونسول!
2. MediaUpload: المكون الرسمي الذي يفتح نافذة مكتبة وسائط ووردبريس المنبثقة، ويتيح للمستخدم اختيار صورة موجودة بالفعل أو سحب وإفلات صورة جديدة من جهازه، مع استرجاع كافة أحجام الصورة وبيانات الـ Alt Text الدلالية.

كود عملي: بطاقة وسائط تفاعلية متوافقة مع الصلاحيات

/**
 * تطبيق احترافي لرفع الصور وإدارتها بمكونات ووردبريس الرسمية
 */
import { useBlockProps, MediaUpload, MediaUploadCheck } from '@wordpress/block-editor';
import { Button, ResponsiveWrapper, Spinner } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

export default function MediaCardEdit( { attributes, setAttributes } ) {
    const { mediaId, mediaUrl, mediaAlt } = attributes;
    const blockProps = useBlockProps( { className: 'az-media-card-component' } );

    const onSelectImage = ( media ) => {
        setAttributes( {
            mediaId: media.id,
            mediaUrl: media.url,
            mediaAlt: media.alt || media.title || '',
        } );
    };

    const onRemoveImage = () => {
        setAttributes( {
            mediaId: 0,
            mediaUrl: '',
            mediaAlt: '',
        } );
    };

    return (
        

            

                { mediaUrl ? (
                    

                        
                            
                        
                        

                            
                                 (
                                        
                                            { __( 'استبدال الصورة', 'az-components' ) }
                                        
                                    ) }
                                />
                            
                            
                                { __( 'حذف الصورة', 'az-components' ) }
                            
                        
                    
                ) : (
                    

                        
                             (
                                    
                                        { __( 'رفع واختيار صورة من المكتبة', 'az-components' ) }
                                    
                                ) }
                            />
                        
                    
                ) }
            
        
    );
}

الجيل الجديد من مكونات التخطيط: نظام G2 (HStack, VStack, Surface)

في التحديثات الأخيرة لمكتبة @wordpress/components، قامت ووردبريس بإدخال الجيل الجديد من نظام التصميم البرمجي (المعروف بـ G2 Components). هذا النظام يركز على بناء واجهات أكثر مرونة واحترافية بالاعتماد على مكونات التخطيط الفضائي:

1. مكون HStack و VStack:

بدلاً من كتابة كود CSS Flexbox معقد لكل عنصرين متجاورين، يوفر لك ووردبريس مكونين سحريين:

• <HStack spacing={4} justify="space-between">: يقوم برص العناصر الفرعية أفقياً في سطر واحد مع توزيع المسافات بينها تلقائياً بالاعتماد على نظام شبكة التصميم الموحد.
• <VStack spacing={3} align="stretch">: يقوم برص العناصر رأسياً فوق بعضها مع ضبط الهوامش البينية بصورة متناسقة تماماً دون أي هوامش زائدة في الأسفل.

2. مكون Surface و Elevation:

لبناء بطاقات ثلاثية الأبعاد ولوحات عائمة، يوفر مكون <Surface> إمكانية تحديد درجات الظل والعمق البصري عبر خاصية elevation={2}، مع التكيف التلقائي مع خلفيات لوحة تحكم ووردبريس في الوضعين الفاتح والليلي (Light & Dark Theme).

معمارية القوائم المنسدلة المعقدة: Dropdown و DropdownMenu

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

import { DropdownMenu, MenuGroup, MenuItem } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

function AdvancedActionsMenu( { onExportJSON, onResetDefaults } ) {
    return (
        
            { ( { onClose } ) => (
                
                     {
                            onExportJSON();
                            onClose();
                        } }
                    >
                        { __( 'تصدير البيانات كملف JSON', 'az-components' ) }
                    
                     {
                            onResetDefaults();
                            onClose();
                        } }
                    >
                        { __( 'إعادة تعيين الإعدادات الافتراضية', 'az-components' ) }
                    
                
            ) }
        
    );
}

الميزات الهندسية المدمجة في هذا النمط:

• إغلاق تلقائي عند النقر الخارجي (Click Outside Handler): لا تحتاج لكتابة أي كود لمراقبة نقرات الفأرة خارج القائمة؛ المكون يتولى ذلك تلقائياً.
• حساب الحواف الافتراضية (Smart Boundaries): إذا كانت القائمة قريبة من حافة الشاشة اليسرى أو السفلية، فإنها تعكس اتجاه فتحها تلقائياً لتظل مرئية بالكامل للكاتب دون أن تختفي خارج حدود المتصفح!

بناء حقول مخصصة عبر نمط BaseControl السحري

يا صديقي المطور، في بعض الأحيان قد تحتاج لبناء حقل إدخال غير تقليدي (مثل: منتقي أكواد لونية ثلاثي، أو حقل تحديد نطاق أسعار مركب)؛ في هذه الحالة، إياك أن تبني العنصر من الصفر! ووردبريس يوفر مكوناً أساسياً خارقاً اسمه BaseControl.

مكون <BaseControl> يتكفل بكل أعباء إمكانية الوصول والتنسيق:

import { BaseControl } from '@wordpress/components';

function CustomPriceRangeInput( { label, help, id, children } ) {
    return (
        
            { children }
        
    );
}

بهذا النمط، يحصل حقلك المخصص على نفس خطوط وهوامش وعناوين ونصوص مساعدة حقول ووردبريس الرسمية مع ربط سمة id تلقائياً، مما يضمن احترافية الكود وانسجام تجربة المستخدم بالكامل مع باقي عناصر المحرر.

تحسين رندرة مكونات جوتنبرج عبر React.memo و useMemo

عند بناء كتل تحتوي على قوائم طويلة أو عناصر تحكم متعددة في السايدبار، يؤدي إعادة الرندرة المستمرة لبطء استجابة المحرر. استخدام React.memo على مستوى المكونات واستخدام useMemo للحسابات المعقدة يضمن تفادي الرندرة غير الضرورية وبقاء تجربة التحرير سريعة واستثنائية.