تشريح بلوك Gutenberg: العلاقة التكاملية بين block.json و edit و save

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

export default function save({ attributes }) {
    const { planName, price, currency, features, isFeatured } = attributes;

    const blockProps = useBlockProps.save({
        className: `az-pricing-card ${isFeatured ? 'is-featured-plan' : ''}`
    });

    return (
        

            {isFeatured && (
                الأكثر شعبية في مصر
            )}

            

            

                {price.toLocaleString()}
                {currency}
                / شهرياً
            

            

            
                اشترك الآن
            
        
    );
}

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

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

• التوافق الحرفي بين edit و save: لو قارنت كود الـ JSX في edit.js والـ JSX في save.js، هتلاقي هيكل الـ DOM مطابق تماماً: نفس الوسوم، نفس الكلاسات، ونفس الترتيب. الفرق الوحيد إن في edit.js بنستخدم RichText القابل للكتابة وتعديل الـ State بـ onChange، وفي save.js بنستخدم RichText.Content المجرد اللي بيطبع كود HTML نقي وثابت. التطابق ده هو الضمان الوحيد إن البلوك عمره ما هيضرب Invalid Content!
• استخدام useBlockProps و useBlockProps.save(): الخطاف ده بيحقن فئات الـ CSS المسؤولة عن الألوان والهوامش اللي المحرر اختارها في شريط الخصائص تلقائياً في الوسم الجذري <div>، بدون ما تضطر تقرأ كلاسات الألوان بإيدك أو تطبقها مانيوال!
• استغلال الـ InspectorControls للمدخلات المعقدة: خلينا السعر وتفعيل الباقة المميزة في الشريط الجانبي (Sidebar)، وخلينا النصوص والعناوين قابلة للتحرير المباشر داخل الصفحة (In-place Editing)، وده بيقدم أعلى تجربة مستخدم (UX) لفريق التحرير في الشركة.

دراسة حالة واقعية من السوق المصري: كارثة الـ Invalid Blocks في 400 صفحة هبوط

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

الخطأ المعماري الفادح

الوكالة بنت حزمة بلوكات مخصصة لعميل عندهم بيدير منصة عقارات وتأجير شاليهات في الساحل الشمالي والعين السخنة. الموقع كان فيه أكثر من 400 صفحة هبوط للمشاريع العقارية كلها مبنية بالبلوك ده. المطور في أول تحديث للبلوك قرر إنه يغير كود الـ HTML في دالة save.js: غير الوسم من <div class="price"> إلى <span class="price-tag">! ورفع الكود المحدث بالـ Git على سيرفر الإنتاج فوراً!

لحظة الذعر في صالة التحرير

تاني يوم الصبح، دخل 30 كاتب ومسؤول مبيعات يعدلوا أسعار الشاليهات وتفاصيل الحجز. أول ما فتحوا أي صفحة من الـ 400 صفحة في لوحة التحكم، اتفاجأوا بالصدمة: كل البلوكات اتحولت لشاشات خطأ صفراء وحمراء بتقول: "This block contains unexpected or invalid content - Attempt Block Recovery"! ولما الموظف كان بيدوس على "Attempt Block Recovery"، جوتنبرج كان بيحول البلوك لكود HTML كلاسيكي ميت مش عارفين يعدلوا فيه ولا يغيروا الصور ولا الأسعار! حملات إعلانات بآلاف الدولارات كانت شغالة على الفيسبوك وجوجل، وتوقف فريق المبيعات تماماً عن العمل لمدة يومين!

خطة الإنقاذ بتطبيق مصفوفة الـ Deprecation

1. إعادة صياغة كود البلوك عبر مصفوفة deprecated: فهمنا الفريق إنك لما تغير كود الـ HTML في دالة save لبلوك مستخدم بالفعل في مقالات منشورة، ممنوع تمسح الكود القديم! لازم توثقه كنسخة قديمة (Deprecated Version) داخل مصفوفة deprecated في ملف index.js:

   deprecated: [
       {
           attributes: oldAttributes,
           save({ attributes }) {
               // كود الـ HTML القديم بالـ div
               return 
   {attributes.price}
   ;
           }
       }
   ]

2. الهجرة التلقائية السلسة: أول ما ووردبريس لقى مصفوفة الـ Deprecation، محرك جوتنبرج قارن الـ HTML بالنسخة القديمة وتعرف عليه، وقام بترقية البلوك تلقائياً للـ <span> الجديد في صمت وبدون ما يظهر أي خطأ أو تحذير للمحررين!
3. اعتماد الاختبارات المؤتمتة للبلوكات (Block Snapshot Testing): أدخلنا نظام اختبارات Jest و Playwright للتأكد من عدم حدوث أي تغيير في كود دالة save مستقبلاً بدون مصفوفة ترقية معتمدة.

جدول مؤشرات التعافي الهندسي

الوصايا العشر لتطوير بلوكات Gutenberg احترافية

1. اعتمد على block.json دائماً: هو المعيار الحديث والوحيد المعتمد؛ لا تسجل البلوكات بالطرق القديمة في JavaScript فقط.
2. اجعل دالة save نقية تماماً (Keep Save Pure): إياك واستدعاء تواريخ حية أو أرقام عشوائية أو طلبات شبكة داخل دالة save لتفادي كابوس الـ Invalidation.
3. استخدم مصفوفة deprecated عند تغيير الـ HTML: إذا قمت بتعديل مخرجات وسم في دالة save لبلوك مستخدم، وثق النسخة السابقة دائماً.
4. استخدم useBlockProps في كل مكان: لا تكتب وسوم الحاويات مجردة؛ احقن useBlockProps() في التحرير و useBlockProps.save() في الحفظ.
5. استثمر في مكونات النواة الجاهزة: استخدم مكونات حزمة @wordpress/components مثل TextControl و ToggleControl لضمان اتساق الواجهة مع لوحة تحكم ووردبريس.
6. حدد أنواع الـ Attributes بدقة: لا تترك نوع الخاصية مجهولاً؛ حدد هل هي string أو number أو boolean أو array.
7. فعل ميزات supports بدلاً من إعادة كتابتها: دع ووردبريس يدير الألوان والهوامش والمحاذاة نيابة عنك عبر ملف block.json.
8. اجعل مخرجات الـ HTML دلالية (Semantic HTML): استخدم الوسوم الصحيحة مثل <figure>، <blockquote>، و <article> لتحسين الـ SEO وإمكانية الوصول (A11y).
9. عطل دالة save للبلوكات الديناميكية: إذا كان البلوك يعتمد على PHP في التصيير اللحظي، اجعل دالة save ترجع null صريحة.
10. احرص على دعم الترجمة والتدويل (i18n): غلف كافة النصوص الظاهرة للمحرر بدوال الترجمة الرسمية __('النص', 'text-domain').

التعمق المعماري: خوارزمية مصادر الخصائص (Attribute Sources) وتوفير حجم الداتابيز

يا صديقي المطور، من أذكى الأفكار المعمارية في ووردبريس هي إنك مش بالضرورة تخزن كل قيمة في الـ JSON بتاع تعليق البلوك! لو عندك بلوك فيه عنوان <h3>الباقة الذهبية</h3>، ليه تخزن كلمة "الباقة الذهبية" مرتين: مرة في كود الـ HTML ومرة تانية كـ JSON جوة <!-- wp:custom/block {"planTitle":"الباقة الذهبية"} -->؟ ده بيضاعف حجم قاعدة البيانات على الفاضي! عشان كده جوتنبرج بيدعم خاصية عبقرية اسمها Attribute Sources في ملف block.json:

"attributes": {
  "planTitle": {
    "type": "string",
    "source": "text",
    "selector": "h3.plan-title"
  },
  "buttonUrl": {
    "type": "string",
    "source": "attribute",
    "selector": "a.cta-button",
    "attribute": "href"
  }
}

إيه اللي بيحصل هنا؟ وقت الحفظ، تعليق البلوك بيتخزن فاضي تماماً: <!-- wp:enterprise/pricing-card /-->! ولما المحرر يفتح المقال تاني، محرك جوتنبرج بيشغل DOM Parser داخلي، يروح يقرا النص اللي جوة وسم <h3 class="plan-title"> ويحطه في attributes.planTitle، ويقرا خاصية href من وسم <a> ويحطها في attributes.buttonUrl! التقنية دي بتوفر أكثر من 50% من حجم جدول wp_posts في المواقع الكبيرة اللي فيها آلاف المقالات.

معمارية التحويل التلقائي (Block Transforms API)

عمرك سألت نفسك إزاي لما بتحدد فقرة نصية في جوتنبرج وتقدر تحولها بضغطة زرار واحدة لاقتباس (Quote) أو قائمة نقطية (List)؟ ده بيتم عبر Block Transforms API المسجل في كود البلوك: تقدر تعرف تحويلات قادمة (from) وتحويلات صادرة (to). مثلاً، تقدر تسمح للمحرر إنه يحول بلوك بطاقة التسعير القديم إلى بلوك جدول مقارنة بضغطة زر واحدة: المحرك بياخد الـ Attributes الحالية (الاسم، السعر، المميزات) وينقلها تلقائياً للبلوك الجديد دون أن يفقد المحرر أي حرف كتبه! ده النضج الحقيقي اللي بيميز البلوكات المؤسسية عن التجارب البرمجية العشوائية.

التعمق المعماري: كتل الحاويات المتداخلة (InnerBlocks) والتحكم في قفل القوالب (Template Locking)

يا صديقي المطور، لما تبني بلوك مركب زي "قسم الخدمات" أو "أكوردين الأسئلة الشائعة" أو "جدول الأسعار المتعدد"، هتحتاج إن البلوك يحتوي على بلوكات تانية حرة يقدر المحرر يضيفها ويحركها جواه. هنا بيجي دور المكون النواتي العبقري <InnerBlocks /> من حزمة @wordpress/block-editor. المكون ده بيسمحلك تحول البلوك بتاعك لحاوية (Container Block). والأجمل من كده، إنك تقدر تتحكم بصرامة هندسية في إيه اللي مسموح للمحرر يضيفه جواه عبر مصفوفة ALLOWED_BLOCKS وقوالب البداية TEMPLATE:

// تحديد قفل صارم للبلوكات المسموح بها داخل الحاوية
const ALLOWED_BLOCKS = ['core/heading', 'core/paragraph', 'core/button'];
const TEMPLATE = [
    ['core/heading', { placeholder: 'عنوان القسم الرئيسي...', level: 2 }],
    ['core/paragraph', { placeholder: 'اكتب وصفاً جذاباً للخدمة هنا...' }],
    ['core/button', { text: 'تواصل معنا الآن' }]
];

export default function Edit() {
    return (
        

            
        
    );
}

خاصية templateLock="all" أو templateLock="insert" دي بتعتبر صمام أمان لا غنى عنه في المواقع المؤسسية الكبيرة؛ لأنها بتسمح للمحرر إنه يعدل النصوص والصور بحرية كاملة، لكن بتمنعه تماماً من إنه يبوظ شبكة التصميم (Layout Grid) أو يمسح أزرار الـ CTA الأساسية، وده اللي بيحافظ على الهوية البصرية للعلامة التجارية في كل صفحات الموقع.