أخطاء تحقق بلوكات Gutenberg: تشخيص Block Validation وحلها

أهلاً بيك يا صديقي المطور في الدليل التشريحي لأكتر كابوس مرعب بيقابل أي مبرمج ووردبريس شغال على محرر المكونات Gutenberg: رسالة “This block contains unexpected or invalid content” (أو بالواجهة العربية: “يحتوي هذا البلوك على محتوى غير متوقع أو غير صالح”) مصحوبة بزرارين يثيرون الرعب أكتر: “Attempt Block Recovery” و “Resolve”!

الرسالة دي لما بتظهر في بيئة تجريبية بتكون مجرد إزعاج بسيط، لكن لما تصحى الصبح تلاقي عميلك بيكلمك في التليفون صوته بيرجف لإن محرري الموقع فتحوا 2,000 مقال ولقوا كل المقالات مطلعة الرسالة دي، ومحرر منهم داس على زرار “Attempt Block Recovery” فقام جوتنبرج مسح نص المحتوى وحوله لكتل HTML ميتة، ساعتها بتعرف إن “Block Validation” مش موضوع هزار، بل هو صمام الأمان المعماري اللي بنته نواة ووردبريس لحماية تكامل البيانات. في المقال ده، هنشرح خوارزمية التحقق خطوة بخطوة، هنفكك أسباب الفشل الخمسة الأكثر شيوعاً، إزاي تقرأ الـ Console Diff باحترافية، وإزاي تعالج الأخطاء بدون فقدان حرف واحد من المقالات بالعامية المصرية التقنية الأصيلة.

تشريح خوارزمية التحقق: كيف يفحص ووردبريس البلوك في المتصفح؟

عشان تحل المشكلة، لازم تفهم محرر جوتنبرج بيفكر إزاي لما تيجي تفتح مقال محفوظ في لوحة التحكم. العملية بتمر بالخطوات الرياضية التالية في حزمة @wordpress/blocks:

1. استخراج كود الـ HTML المحفوظ مسبقاً (Raw Content Extraction):

   محلل النواة (Gutenberg Parser) بيقرأ المقال من قاعدة البيانات، وبيقطع تعليق البلوك ويستخرج كود الـ HTML اللي متخزن بين وسم الفتح ووسم الإغلاق؛ النص ده بنسميه rawContent.

2. توليد كود الـ HTML المفترض برمجياً (Generated Content Simulation):

   المحرر بياخد الخصائص (Attributes) المستخرجة من تعليق البلوك، وبيرميها داخل دالة save( { attributes } ) المسجلة حالياً في ملفات الجافاسكريبت بتاعة موقعك، ويشوف الـ JSX هينتج عنه كود HTML شكله إيه؛ النص ده بنسميه generatedHTML.

3. مرحلة التطبيع المعياري (String Normalization):

   جوتنبرج مش غبي؛ هو عارف إن المتصفحات ممكن تغير ترتيب الـ Attributes (مثلاً تحط class قبل id أو العكس). فبيقوم بتمرير النصين على خوارزمية تطبيع بتوحد ترتيب السمات، وتزيل الفراغات الميتة في أطراف الوسوم.

4. المقارنة الصارمة (Strict Equality Check):

   بيقارن النصين بحرفية تامة: rawContent === generatedHTML. لو طلعوا متطابقين بنسبة 100%، البلوك بيعدي بسلام ويفتح في شاشة التحرير كأنه لم يكن هناك شيء.

5. فحص الترحيل البديل (Fallback Deprecations):

   لو فشلت المقارنة، جوتنبرج ما بيستسلمش فوراً! بيبدأ يلف على مصفوفة deprecated المعرفة في البلوك واحدة ورا التانية، وينفذ دوال الـ save القديمة. لو لقى واحدة منهم مطابقة، بيشغل دالة migrate() ويرقي البلوك في صمت تام بدون أي رسائل خطأ للمحرر!

6. إطلاق صافرة الإنذار (Validation Failure):

   لو فشلت المقارنة مع الكود الحالي ومع كل الـ Deprecations المسجلة، ساعتها جوتنبرج بيرفع الراية الحمراء ويطبع تفاصيل الفشل في الـ Browser Console ويعرض الرسالة المرعبة للمستخدم.

فن قراءة الـ Console Diff: كيف تصطاد الخطأ في 30 ثانية؟

أول ما تشوف الخطأ، افتح أدوات المطور في متصفحك (Inspect Element -> Console). هتلاقي جوتنبرج طابع رسالة تحذيرية مفصلة جداً بتبدأ بـ:

Block validation: Block validation failed for `enterprise/custom-banner` ({...}).

Content generated by `save` function:
عنوان البلوك

Content retrieved from post body:
عنوان البلوك

بص على السطور دي بعين الصقر:

• Content generated by 'save' function: ده الكود اللي ملف الجافاسكريبت بتاعك الحالي بيحاول يولده النهاردة.
• Content retrieved from post body: ده الكود القديم اللي اتخزن في قاعدة البيانات زمان لما المقال اتنشر لأول مرة.
• المقارنة السريعة: هتلاحظ فوراً إن الكود الجديد فيه كلاس إضافي اسمه az-banner-v2، بينما المقال القديم مفهوش الكلاس ده! هنا السبب واضح وضوح الشمس: أنت عدلت الكلاس في ملف الـ JS بس نسيت تعرف جوتنبرج إن المقالات القديمة لسه بالكلاس القديم عبر مصفوفة deprecated.

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

1. النموذج الكارثي: إدراج بيانات ديناميكية غير قطعية في save()

// ❌ كود كارثي يسبب Block Validation Error لكل من يفتح المقال في المستقبل!
import { useBlockProps } from '@wordpress/block-editor';

export default function save( { attributes } ) {
    const blockProps = useBlockProps.save();
    
    // خطأ قاتل: Date.now() تعطي رقماً مختلفاً مع كل ملي ثانية!
    const renderTimestamp = Date.now(); 
    
    // خطأ قاتل: Math.random() ينتج ID عشوائياً مختلفاً عند كل مقارنة!
    const uniqueId = 'box-' + Math.floor( Math.random() * 10000 );

    return (
        

            
تم حفظ هذا المحتوى في التوقيت: { renderTimestamp }
        
    );
}

لماذا يتدمر هذا البلوك حتماً؟
لأنك لما حفظت المقال الساعة 5:00، اتخزن الرقم 1730000000. لما تفتح المقال الساعة 6:00، دالة save هتتنفذ عشان تقارن، فهتولد الرقم 1730003600! المقارنة تفشل، ويضرب البلوك في الحال!

2. النموذج السليم: خصائص قطعية محفوظة في الـ Attributes

// ✅ الكود الهندسي المحصن والمستقر بنسبة 100%
import { useBlockProps } from '@wordpress/block-editor';

export default function save( { attributes } ) {
    const { uniqueId, createdTimeText } = attributes;
    const blockProps = useBlockProps.save();

    return (
        

            
تاريخ النشر المعتمد: { createdTimeText }
        
    );
}

التصحيح المعماري: قمنا بتوليد المعرف الفريد والوقت داخل دالة التحرير (edit.js) مرة واحدة فقط عند إدراج البلوك، وحفظناهم كـ attributes صريحة في المقال. دالة save() أصبحت دالة نقية (Pure Deterministic Function) تقرأ فقط من الـ attributes وتخرج نفس الـ HTML للأبد!

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

لو عندك بلوك ضارب في شاشة التحرير ومش عارف تطلع تفاصيله بدقة، افتح الـ Console في المتصفح وانسخ السكربت التشخيصي ده، هيديك تقرير كامل عن حالة البلوك المختار حالياً:

// انسخ هذا الكود في كونسول المتصفح أثناء فتح المقال المتضرر
(function diagnoseActiveBlock() {
    const editor = wp.data.select( 'core/block-editor' );
    const selectedBlock = editor.getSelectedBlock();
    
    if ( ! selectedBlock ) {
        console.warn( '⚠️ من فضلك حدد البلوك التالف أولاً بالضغط عليه داخل المحرر.' );
        return;
    }
    
    console.group( '🔍 تقرير الفحص المعماري للبلوك: ' + selectedBlock.name );
    console.log( 'معرف البلوك (Client ID):', selectedBlock.clientId );
    console.log( 'هل البلوك صالح (isValid):', selectedBlock.isValid );
    console.log( 'الخصائص الحالية (Attributes):', selectedBlock.attributes );
    console.log( 'كود الـ HTML الأصلي (Original Content):', selectedBlock.originalContent );
    
    // محاولة محاكاة كود الـ Save برمجياً
    const blockType = wp.blocks.getBlockType( selectedBlock.name );
    if ( blockType && blockType.save ) {
        const simulatedHTML = wp.blocks.getSaveContent( blockType, selectedBlock.attributes, selectedBlock.innerBlocks );
        console.log( 'كود الـ HTML المولد حالياً (Simulated Save):', simulatedHTML );
        
        if ( selectedBlock.originalContent === simulatedHTML ) {
            console.info( '✅ كود الـ HTML متطابق تماماً! لا يوجد خطأ في الـ Markup.' );
        } else {
            console.error( '❌ تضارب مؤكد بين المحتوى المحفوظ والمولد! هذا هو سبب رسالة الخطأ.' );
        }
    }
    console.groupEnd();
})();

دراسة حالة واقعية: كارثة منصة دروس الثانوية العامة والجامعات في مصر

الوصايا العشر لمنع وتصحيح أخطاء Block Validation

1. دالة save() هي دالة نقية (Pure Function): لا تضع بداخلها أي متغيرات عشوائية، تواريخ لحظية، أو قراءات من الـ LocalStorage أو الـ Cookies.
2. إياك والضغط العشوائي على “Attempt Block Recovery”: هذا الزر يقوم بمحاولة ترقيع قاسية غالباً ما تنتهي بحذف العناصر المتداخلة أو تحويل البلوك إلى كود خام ميت.
3. افحص Browser Console أولاً: هو المصباح الذي يكشف لك بالسطر والمسافة أين يكمن التضارب بين الـ Generated والـ Retrieved HTML.
4. أي تعديل في الـ HTML يتطلب Deprecation فوراً: إذا قمت بتغيير كلاس أو نقل وسم في بلوك منشور بالفعل، اكتب قاعدة ترحيل في مصفوفة deprecated قبل رفع الكود.
5. استخدم RichText.Content دائماً في الحفظ: لا تطبع نصوص الـ RichText كمتغيرات JSX عادية؛ استخدم المكون المخصص للحفاظ على سلامة تنسيق الحروف.
6. احذر من أدوات تنسيق الأكواد التلقائية (Prettier): اضبط إعدادات Prettier بحيث لا تضع فواصل أسطر ومسافات زائدة داخل وسوم النصوص في الـ JSX.
7. لا تعدل محتوى المقالات بـ SQL Queries عشوائية: عمليات البحث والاستبدال المباشرة في عمود post_content هي أسرع طريقة لتخريب تطابق البلوكات.
8. حول البلوك إلى ديناميكي إذا كانت بياناته متغيرة: إذا كنت تحتاج لعرض بيانات تتجدد دورياً، اعتمد على render.php واجعل save() { return null; } وتخلص من الصداع للأبد.
9. اكتب اختبارات Jest Block Fixtures: قم بإنشاء اختبارات تقارن مخرجات الـ Save مع نماذج HTML تاريخية في نظام الـ CI/CD الخاص بفريقك.
10. درب محرري الموقع على الإبلاغ الفوري: علم فريق كتابة المحتوى ألا يقوموا بحل المشاكل بأنفسهم، بل يبلغون الفريق البرمجي فور ظهور أول راية تحذيرية صفراء.

هندسة الفحص التلقائي في خطوط الإنتاج (Automated CI/CD Block Testing)

يا صديقي المطور، الفرق الجوهري بين المطور الهاوي والمهندس المحترف في الشركات الكبرى هو أن المحترف لا ينتظر حتى يشتكي العملاء من أخطاء الـ Validation في السيرفر الحي، بل يقوم ببناء درع أمني آلي في خطوط التكامل المستمر (CI/CD Pipeline) يمنع دمج أي كود (Pull Request) يكسر التوافق مع المقالات السابقة!

باستخدام حزمة @wordpress/jest-preset-default، يمكنك إنشاء ما يسمى بـ Fixture Testing: وهو الاحتفاظ بنماذج HTML حقيقية لمقالات منشورة مسبقاً، واختبار ما إذا كانت دالة validateBlock() تنجح في مطابقتها مع كود الـ JavaScript الجديد أم تفشل.

كود عملي: اختبار التحقق الآلي للبلوكات عبر Jest

/**
 * اختبار التحقق المعماري للبلوك في بيئة Jest
 * File: test/block-validation.test.js
 */
import { registerBlockType, unregisterBlockType } from '@wordpress/blocks';
import { validateBlock } from '@wordpress/blocks';

// استيراد إعدادات البلوك الحالي
import metadata from '../src/block.json';
import edit from '../src/edit';
import save from '../src/save';
import deprecated from '../src/deprecated';

describe( 'فحص سلامة واستقرار بلوك البانر (enterprise/custom-banner)', () => {
    beforeAll( () => {
        registerBlockType( metadata.name, {
            ...metadata,
            edit,
            save,
            deprecated,
        } );
    } );

    afterAll( () => {
        unregisterBlockType( metadata.name );
    } );

    it( 'يجب أن ينجح في التحقق من صحة كود HTML المسجل في مقال تم نشره في عام 2023', () => {
        // نص الـ HTML الحقيقي المخزن في قاعدة بيانات السيرفر الحي
        const historicalRawHTML = '
أهلاً بكم في مصر
';
        
        const historicalAttributes = {
            title: 'أهلاً بكم في مصر'
        };

        // تشغيل خوارزمية التحقق الرسمية لنواة ووردبريس
        const isValid = validateBlock( {
            name: metadata.name,
            attributes: historicalAttributes,
            originalContent: historicalRawHTML,
        } );

        // التأكد من أن البلوك صالح بنسبة 100% ولا يظهر راية التحذير الصفراء
        expect( isValid ).toBe( true );
    } );
} );

لو أحد المطورين في فريقك قام بتعديل كلاس في ملف save.js بدون كتابة قاعدة ترحيل في deprecated.js، سيفشل هذا الاختبار فوراً على GitHub Actions ولن يتم دمج الكود إطلاقاً، مما يحمي قاعدة بيانات موقعك من أي تلف محتمل للأبد!

معضلة تشفير الحروف العربية والتشكيل (Arabic UTF-8 Entities & Unicode Normalization)

في المواقع العربية، كثيراً ما يظهر خطأ Block Validation غامض جداً، تفتح الـ Console وتجد أن الكود المتوقع والمحفوظ متطابقان في كل حرف باللغة العربية! كيف يحدث ذلك؟

السر يكمن في ما يسمى بالـ Unicode Normalization والرموز الخاصة:

• التشكيل والحركات (Diacritics): في لغة البرمجة، حرف “أَ” (ألف فوقها همزة وفتحة) يمكن كتابته برمز يونيكود واحد مدمج (NFC)، أو برمزين منفصلين: رمز الألف ويليه رمز الفتحة (NFD). لو كان المتصفح يرسل أحدهما ووردبريس يحفظ الآخر، فإن المقارنة النصية ستفشل برمجياً رغم تطابقهما البصري تماماً في عين القارئ!
• المسافات غير المرئية (Zero-Width Non-Joiner – ZWNJ): بعض لوحات المفاتيح تدرج مسافات غير مرئية تفصل الحروف، واختلاف وجودها بين محرر React وقاعدة البيانات يفشل المقارنة.
• علامات التنصيص الذكية (Smart Quotes): ووردبريس يمتلك فلتر داخلي قديم اسمه wptexturize يقوم بتحويل علامات التنصيص العادية " " إلى علامات مائلة ذكية “ ”. إذا قام هذا الفلتر بتعديل النص المحفوظ أثناء دورة الحفظ ولم يتم استدعاؤه في دالة الـ Save بالجافاسكريبت، يحدث تضارب فوري في التحقق!

الحل الهندسي: الاعتماد الدائم على مكونات RichText و RichText.Content الرسمية، وتجنب عمل نصوص معدلة يدوياً عبر دوال استبدال النصوص البسيطة (Regex String Replacements) في الأكواد.