إهمال كتلة غوتنبرغ: التحديث دون كسر المحتوى

ملخص

غالبًا ما يؤدي تحديث كتلة غوتنبرغ إلى كسر المنشورات الحالية التي تستخدم الإصدار القديم. توضح لك هذه المقالة كيفية استخدام خاصية deprecated في block.json للحفاظ على التوافق مع الإصدارات السابقة. ستتعلم الخطوات الدقيقة لالتقاط ترميز الكتلة الحالي، وتحديد إصدار واحد أو أكثر مهملة، وتعيين السمات بشكل صحيح. سنغطي الكتل الثابتة والديناميكية، مع أمثلة عملية. كما تتناول المقالة الافتراض بأن الإهمال هو دائمًا أفضل نهج، وتناقش متى قد يكون الفصل الكامل أفضل. في النهاية، ستتمكن من تحديث كتلك بثقة دون كسر محتوى مستخدميك.

سيناريو التغيير الكاسر

أطلقت كتلة شهادة مخصصة قبل ستة أشهر. كانت تنتج عنصر <div> بسيطًا يحتوي على اقتباس واسم المؤلف. الآن يريد عميلك تصميمًا جديدًا: يجب أن يظهر المؤلف فوق الاقتباس، مع فئة CSS مختلفة. قمت بتحديث دالة save للكتلة و render_callback. اختبرت على منشور جديد – يبدو رائعًا. ثم انتقلت إلى منشور قديم يستخدم الكتلة. كارثة: نص الاقتباس اختفى، المؤلف في المكان الخطأ، والتنسيق معطل. لقد كسرت كل صفحة تستخدم الكتلة.

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

ما هو إهمال الكتلة؟

إهمال الكتلة هو الآلية المضمنة في غوتنبرغ للتعامل مع تغييرات الإصدار. من خلال تعريف مصفوفة deprecated في ملف block.json الخاص بكتلتك، تخبر المحرر: "إذا واجهت كتلة تطابق أحد هذه الإصدارات القديمة، فقم بتحويلها إلى الإصدار الحالي." يحدد كل إدخال مهمل السمات السابقة، supports، ودالة save (أو render_callback). عندما يقوم المحرر بتحميل كتلة قديمة، يمر عبر المصفوفة المهملة بالترتيب ويطبق أول تحويل مطابق.

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

الخطوة 1: التقاط الحالة الحالية

قبل إجراء أي تغييرات، سجل مخرجات save الدقيقة (أو render_callback للكتل الديناميكية) والسمات التي تستخدمها كتلتك حاليًا. اعتبرها كأخذ لقطة سريعة. للكتل الثابتة، احفظ JSX الذي ترجعه دالة save. للكتل الديناميكية، احفظ ترميز PHP الذي يولده render_callback.

أنشئ ملفًا جديدًا في إضافتك باسم deprecated.js (أو ما شابه) وخزن دالة save القديمة هناك. بدلاً من ذلك، يمكنك الاحتفاظ بالإصدارات المهملة مباشرة في ملف جافاسكريبت الرئيسي للكتلة. المفتاح هو الحفاظ على هذا الكود تمامًا كما كان عندما تم نشر الكتلة لأول مرة.

الخطوة 2: تعريف إصداراتك المهملة

في ملف block.json الخاص بك، أضف مصفوفة deprecated. كل إدخال هو كائن يمكن أن يتضمن:

• attributes (كائن): تعريفات السمات السابقة.
• supports (كائن): أي إعدادات دعم سابقة تغيرت.
• save (دالة أو نص): دالة الحفظ السابقة. للكتل التي تعتمد فقط على جافاسكريبت، ستستورد الدالة القديمة. للكتل الديناميكية المعروضة عبر PHP، يمكنك استخدام migrate و render_callback بدلاً من ذلك.
• migrate (دالة): دالة تقوم بتعيين السمات القديمة إلى الجديدة (اختياري).

مثال:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className=\"testimonial-legacy\"><p className=\"quote\">{attributes.quote}</p><p className=\"author\">{attributes.author}</p></div>"
  }
]

ملاحظة: دالة save في block.json تُعرف عادة في جافاسكريبت. إذا كنت تستخدم سكريبت خارجي، ستحتاج إلى ربطه والإشارة إلى اسم الدالة. بدلاً من ذلك، يمكنك تضمين الدالة كنص (على الرغم من أن هذا غير موصى به للكتل المعقدة).

الخطوة 3: تعيين السمات

غالبًا، لا تغير الترميز فحسب بل أيضًا أسماء السمات أو مصادرها. على سبيل المثال، قد تتحول من تخزين المؤلف كنص عادي إلى حقل نص منسق. في هذه الحالات، استخدم خاصية migrate لتحويل السمات القديمة إلى الجديدة.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

إذا لم تقدم دالة migrate، فسيقوم المحرر ببساطة بتمرير السمات القديمة مباشرة إلى الكتلة الجديدة. قد يتسبب ذلك في أخطاء إذا تغيرت أسماء السمات.

الخطوة 4: الاختبار بمحتوى حقيقي

بعد تعريف الإصدار المهمل، اختبر بدقة. أنشئ منشورًا جديدًا، وأدرج الكتلة القديمة (يمكنك المحاكاة بلصق كود الكتلة المسلسل من منشور موجود)، وتحقق من أنها تتحول إلى الإصدار الجديد دون أخطاء تحقق. كما اختبر تحرير وحفظ الكتلة المحولة. كرر ذلك لعدة إصدارات مهملة إذا كان لديك.

بالنسبة لـ الكتل الديناميكية، العملية مشابهة ولكن مع اختلاف: دالة save للكتلة الديناميكية عادة ما ترجع null (يتم عرض الكتلة عبر PHP). في الإدخال المهمل، يمكنك إما تعيين save إلى الترميز الثابت السابق الذي كان مستخدمًا قبل التبديل إلى العرض الديناميكي، أو استخدام render_callback في PHP يتعامل مع هياكل السمات القديمة والجديدة. هذا أكثر تعقيدًا ولكنه ممكن.

تحذيرات ومقايضات

الإهمال قوي، لكن له جوانب سلبية. كل إصدار مهمل يضيف كودًا إلى إضافتك. بمرور الوقت، قد ينتهي بك الأمر بسلسلة من خمسة أو ستة إصدارات قديمة نادرًا ما تستخدم ولكن يجب صيانتها. توصي فريق ووردبريس الأساسي بالاحتفاظ بإصدارين سابقين على الأقل، ولكن بعد ذلك، قد تفكر في فصل كامل إذا كان عدد المنشورات المتأثرة صغيرًا.

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

أخيرًا، لا يتعامل الإهمال مع المحتوى الذي تم تحريره باستخدام تغيير نمط على مستوى الموقع (مثل عبر theme.json). إذا كان مظهر كتلتك يعتمد على أنماط عالمية تغيرت منذ ذلك الحين، فلن يضبط الإهمال ذلك. قد تحتاج إلى إضافة سكريبت ترحيل يعمل عند الحفظ أو عبر خطاف تحديث الإضافة.

متى لا يكون الإهمال هو الحل

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

نقطة أخرى مخالفة: لا ينبغي استخدام الإهمال كبديل للتصميم الجيد. إذا كنت تتوقع تغييرات متكررة، صمم كتلتك مع وضع التحكم في الإصدارات منذ البداية – على سبيل المثال، عن طريق تخزين سمة version واستخدام العرض الشرطي. هذا النهج، الذي تمت مناقشته في ما وراء الكتل الأساسية، أخف من الإهمال ولكنه يتطلب بصيرة.

الخلاصة

إهمال الكتلة هو أداة أساسية لأي مطور غوتنبرغ جاد. يسمح لك بتطوير كتلك دون كسر محتوى المستخدمين. الخطوات الرئيسية هي: التقاط الحالة الحالية، تعريف الإصدار المهمل في block.json، تعيين السمات إذا لزم الأمر، والاختبار بمحتوى حقيقي. لكن تذكر أن الإهمال يأتي بتكاليف صيانة. أحيانًا يكون الفصل الكامل أو تصميم الكتلة بإصدارات أكثر عملية. استخدم الإهمال بشكل استراتيجي، ليس تلقائيًا، وستبقى كتلك قوية خلال العديد من التحديثات.

للحصول على منظور أوسع حول بناء إضافات قابلة للصيانة، راجع بناء إضافات ووردبريس قوية. وإذا كنت جديدًا في تطوير الكتل، سيساعدك ما وراء الكتل الأساسية على البدء.