خصائص بلوكات Gutenberg: هندسة الـ Attributes، مصادر استخراج القيم، وحماية التوافقية

يا أهلاً بيك يا هندسة في واحد من أدق وأهم أسرار النضج البرمجي في محرر ووردبريس الحديث: خصائص البلوكات (Block Attributes) وهندسة مصادر استخراج القيم. لما تبدأ تطور بلوك في جوتنبرج، أول حاجة بتفكر فيها هي: “أنا هخزن بيانات البلوك دي فين؟” هل هرمي كل المتغيرات كـ JSON جوة تعليق البلوك <!-- wp:my/block {"title":"..."} -->؟ ولا استخرجها بذكاء من كود الـ HTML الدلالي نفسه؟ ولا أربطها بجدول الـ Postmeta عشان استعلم عنها بـ WP_Query؟ الاختيار اللي هتاخده هنا هو اللي هيحدد هل موقعك هيكون فائق الرشاقة وخفيف زي الريشة، أو هتتسبب في تضخم قاعدة البيانات بجيجابايتات من البيانات المكررة وعشرات أخطاء الـ Block Invalidation عند كل تحديث! في الدليل الشامل ده، هنفكك معمارية الـ Attributes بالكامل، ونفهم محرك الـ DOM Matcher في جوتنبرج، ونبني بلوكات مؤسسية مطابقة لأعلى المعايير العالمية.

ما هي خصائص البلوك (Attributes) ولماذا هي عصب المعمارية؟

في هندسة ووردبريس المعاصرة، البلوك مش مجرد رسمة أو وسم HTML ثابت؛ البلوك هو عبارة عن مكون برمجي ذو حالة (Stateful Component). الـ Attributes هي الحاوية اللي بتحتفظ بحالة هذا المكون: نصوص العناوين، مسار الصورة (Image URL)، ألوان الخلفية، عدد الأعمدة، حالة التفعيل (Toggle State)، وخيارات المحاذاة.

الـ Attributes بتلعب دور “حلقة الوصل” بين 3 عوالم مختلفة:

1. عالم التحرير في React (edit.js): حيث يتم قراءة الخصائص كـ Props وتعديلها عبر setAttributes() في الذاكرة.
2. عالم التخزين في الداتابيز (MySQL Database): حيث يتم حفظها إما كـ JSON Delimiters أو داخل وسوم HTML أو كـ Post Meta.
3. عالم العرض في الفرونت إند (save.js أو render.php): حيث تتحول الخصائص إلى عناصر واجهة يراها الزائر.

استراتيجيات التخزين ومصادر الاستخراج (Attribute Sources)

ووردبريس بيوفر 3 استراتيجيات معمارية لتخزين واسترجاع الـ Attributes:

1. التخزين الافتراضي في تعليقات الـ HTML (Comment Delimiters)

لو عرفت الخاصية في block.json بنوعها وقيمتها الافتراضية فقط بدون تحديد source:

"attributes": {
  "columnsCount": {
    "type": "number",
    "default": 3
  }
}

ووردبريس هيقوم بتخزين القيمة دي كـ JSON صريح داخل تعليق البلوك في قاعدة البيانات: <!-- wp:my/block {"columnsCount":4} -->. الميزة: سهلة ومباشرة وسريعة جداً ومثالية للبيانات الوصفية (Metadata) اللي ملهاش تمثيل بصري في كود الـ HTML (زي عدد الأعمدة، أو حالة تفعيل خيار معين). العيب: لو استخدمتها للنصوص والصور، هتخزن البيانات مرتين (مرة في الـ JSON ومرة في الـ HTML)، مما يضاعف حجم قاعدة البيانات بلا داعٍ.

2. الاستخراج الذكي من شجرة الـ DOM (DOM Source Attributes)

ودي بقى قمة العبقرية الهندسية في جوتنبرج! بدل ما تخزن نص المقال أو رابط الصورة في الـ JSON، أنت بتقول لووردبريس: “أنا هطبع القيمة دي في كود الـ HTML في دالة save.js، ولما المحرر يفتح المقال تاني، استخرج القيمة دي من شجرة الـ DOM مباشرة!” جوتنبرج بيدعم 4 محددات استخراج رئيسية:

• المصدر text: يستخرج النص المجرد من العنصر بدون وسوم:

  "title": {
    "type": "string",
    "source": "text",
    "selector": "h2.az-block-title"
  }

• المصدر html: يستخرج كود الـ HTML الداخلي بما يحتويه من وسوم غنية (Bold, Italic, Links):

  "description": {
    "type": "string",
    "source": "html",
    "selector": "div.az-description-body"
  }

• المصدر attribute: يستخرج قيمة سمة محددة من وسم HTML معين (مثل src أو href أو alt أو data-id):

  "imageUrl": {
    "type": "string",
    "source": "attribute",
    "selector": "img.az-feature-img",
    "attribute": "src"
  }

• المصدر query: يستخرج مصفوفة كائنات متكررة من عناصر الـ DOM (مثالي لقوائم الروابط، عناصر المعارض، أو جداول المقارنة):

  "galleryImages": {
    "type": "array",
    "source": "query",
    "selector": "figure.gallery-item",
    "query": {
      "url": { "type": "string", "source": "attribute", "selector": "img", "attribute": "src" },
      "caption": { "type": "string", "source": "text", "selector": "figcaption" }
    }
  }

3. الربط المباشر مع الحقول المخصصة (Post Meta Attributes)

لو عندك بيانات حساسة أو محتاج تستعلم عنها في فلترات وبحث ووردبريس بـ meta_query (زي سعر المنتج، كود العقار، أو تاريخ انتهاء الدورة التدريبية)، التخزين جوة محتوى المقال مش هيفيدك في الاستعلامات السريعة. هنا بنستخدم "source": "meta":

"attributes": {
  "propertyPrice": {
    "type": "number",
    "source": "meta",
    "meta": "_real_estate_price"
  }
}

بمجرد ما المحرر يغير السعر في البلوك، ووردبريس بيحفظه تلقائياً في جدول wp_postmeta عبر الـ REST API، ويصبح متاحاً للاستعلامات البرمجية فائقة السرعة!

مقارنة معمارية شاملة: استراتيجيات تخزين واستخراج الخصائص

تطبيق برودكشن متكامل: بناء بلوك شهادات عملاء مؤسسي يدمج كافة مصادر الخصائص

تعال نبني كود برودكشن حقيقي لبلوك شهادات العملاء (Enterprise Testimonial Block). البلوك ده بيوظف كل أنواع الـ Attributes بحرفية: استخراج النصوص بـ html و text، استخراج رابط الصورة بـ attribute، وتخزين التقييم النجمي كـ Comment JSON:

1. ملف البيانات الوصفية (block.json)

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "enterprise/client-testimonial",
  "version": "1.0.0",
  "title": "شهادة عميل مؤسسية",
  "category": "widgets",
  "icon": "format-quote",
  "description": "بلوك لعرض آراء وتقييمات العملاء مع استخراج ذكي من شجرة الـ DOM لتوفير الذاكرة.",
  "supports": {
    "color": {
      "background": true,
      "text": true
    },
    "spacing": {
      "padding": true
    }
  },
  "attributes": {
    "clientName": {
      "type": "string",
      "source": "text",
      "selector": "h4.client-name",
      "default": "م. أحمد عبد الرحمن"
    },
    "clientCompany": {
      "type": "string",
      "source": "text",
      "selector": "span.client-company",
      "default": "شركة القاهرة للحلول الرقمية"
    },
    "testimonialText": {
      "type": "string",
      "source": "html",
      "selector": "blockquote.testimonial-quote",
      "default": "التعامل مع المنصة نقل أعمالنا لمستوى آخر من الاحترافية والسرعة الاستثنائية."
    },
    "avatarUrl": {
      "type": "string",
      "source": "attribute",
      "selector": "img.client-avatar",
      "attribute": "src",
      "default": "https://via.placeholder.com/150"
    },
    "avatarAlt": {
      "type": "string",
      "source": "attribute",
      "selector": "img.client-avatar",
      "attribute": "alt",
      "default": "صورة العميل"
    },
    "ratingStars": {
      "type": "number",
      "default": 5
    }
  },
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

2. مكون التحرير التفاعلي (edit.js)

import { __ } from '@wordpress/i18n';
import { 
    useBlockProps, 
    RichText, 
    InspectorControls, 
    MediaUpload, 
    MediaUploadCheck 
} from '@wordpress/block-editor';
import { 
    PanelBody, 
    RangeControl, 
    Button 
} from '@wordpress/components';

export default function Edit({ attributes, setAttributes }) {
    const { 
        clientName, 
        clientCompany, 
        testimonialText, 
        avatarUrl, 
        avatarAlt, 
        ratingStars 
    } = attributes;

    const blockProps = useBlockProps({
        className: 'az-enterprise-testimonial-block'
    });

    return (
        
            
                
                     setAttributes({ ratingStars: val })}
                        min={1}
                        max={5}
                    />
                
            

            

                

                    
                         setAttributes({ 
                                avatarUrl: media.url, 
                                avatarAlt: media.alt || clientName 
                            })}
                            allowedTypes={['image']}
                            render={({ open }) => (
                                
                                    
                                    {__('تغيير الصورة', 'text-domain')}
                                
                            )}
                        />
                    

                    

                         setAttributes({ clientName: val })}
                            placeholder={__('اسم العميل...', 'text-domain')}
                        />
                         setAttributes({ clientCompany: val })}
                            placeholder={__('الشركة أو المنصب...', 'text-domain')}
                        />
                        

                            {'★'.repeat(ratingStars)}{'☆'.repeat(5 - ratingStars)}
                        
                    
                

                 setAttributes({ testimonialText: val })}
                    placeholder={__('اكتب نص الشهادة أو التوصية هنا...', 'text-domain')}
                />
            
        

3. دالة الحفظ والتصيير (save.js)

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

export default function save({ attributes }) {
    const { 
        clientName, 
        clientCompany, 
        testimonialText, 
        avatarUrl, 
        avatarAlt, 
        ratingStars 
    } = attributes;

    const blockProps = useBlockProps.save({
        className: 'az-enterprise-testimonial-block'
    });

    return (
        

            

                

                

                    
                    
                    

                        {'★'.repeat(ratingStars)}{'☆'.repeat(5 - ratingStars)}
                    
                
            

            
        
    );
}

import { useEntityProp } from '@wordpress/core-data';

export default function Edit({ context: { postId, postType } }) {
    // قراءة وتعديل عنوان المقال الأصلي مباشرة من داخل البلوك!
    const [ title, setTitle ] = useEntityProp('postType', postType, 'title', postId);

    return (
         setTitle(e.target.value)} 
            className="direct-post-title-editor"
        />
    );
}