قالب البلوكات لا يُطبَّق في ووردبريس؟ ابدأ من قاعدة البيانات

ملف قالبك يجري تجاهله في شبه المؤكد لأن نسخة في قاعدة البيانات هي الفائزة. في اللحظة التي تفتح فيها قالبًا في محرر الموقع وتضغط حفظ، يكتب ووردبريس سجل مقالة من نوع wp_template، ومن تلك اللحظة يُقدَّم ذلك السجل بدل ملف .html الموجود في مجلد قالبك — فيصبح كل تعديل تجريه على الملف بعد ذلك غير مرئي على الواجهة الأمامية. مسح ذلك السجل هو الحل، وهو أول ما ينبغي فحصه قبل أن تلمس الهرمية أو اسم الملف أو التخزين المؤقت.

تأكّد من وجود نسخة قاعدة البيانات

اذهب إلى المظهر ← المحرر ← القوالب. أي قالب يقدّمه ووردبريس من قاعدة البيانات يكون مؤشَّرًا في القائمة — وبحسب إصدار ووردبريس لديك تقرأ الشارة «مخصَّص» أو يظهر القالب ضمن مرشِّح «مخصَّص». تلك الشارة هي الجواب كله. فإن كانت موجودة، فملفك ليس مستخدَمًا.

ويمكنك فحص الأمر نفسه من سطر الأوامر، وهو أسرع ويعمل حتى حين يسيء محرر الموقع التصرّف:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

كل صف هو تجاوز في قاعدة البيانات. والقيمة post_name تطابق الاسم اللطيف للقالب، فالصف المسمّى single يحجب templates/single.html.

وتفصيل واحد يوقع الناس في الخطأ: هذه السجلات مرتبطة بالقالب عبر مصطلح تصنيفي، لا عبر مسار. فإن أعدت تسمية مجلد قالبك، تبقى القوالب المحفوظة في قاعدة البيانات لكنها تتوقف عن مطابقة القالب النشط، فيرتد الموقع فجأة إلى الملفات. ويبدو ذلك وكأن «تخصيصاتي اختفت» لا وكأن «ملفي يجري تجاهله» — الآلية ذاتها والعَرَض معكوس.

امسحه

في محرر الموقع، افتح قائمة خيارات القالب (النقاط الثلاث بجانبه) واختر مسح التخصيصات — وبعض الإصدارات تسمّيها إعادة ضبط. هذا يحذف سجل قاعدة البيانات فيعود التحكم إلى الملف الموجود على القرص.

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

ومن WP-CLI، باستخدام معرّف من القائمة أعلاه:

wp post delete 482 --force

وكن صريحًا مع نفسك بشأن الكلفة هنا: مسح التخصيصات يتخلّص نهائيًا من كل ما بنيته في محرر الموقع لذلك القالب، ولا يمكن التراجع عنه. فإن كانت نسخة محرر الموقع تحوي عملًا حقيقيًا، فانسخ وسوم البلوكات منها أولًا — افتح القالب في المحرر، وبدّل إلى عرض الشيفرة، والصق الناتج في ملف .html لديك. وبذلك يصبح الملف هو مصدر الحقيقة ولا يضيع شيء.

كيف يختار ووردبريس القالب

تستخدم قوالب البلوكات منطق الهرمية ذاته الذي تستخدمه القوالب الكلاسيكية، غير أن الملفات .html في templates/ بدل ملفات .php في جذر القالب. يمشي ووردبريس من الأكثر تحديدًا إلى الأقل تحديدًا ويستخدم أول ملف موجود.

عند عرض	يُفحَص بهذا الترتيب
مقالة مفردة	single-post-{slug}.html ← single-post.html ← single.html ← singular.html ← index.html
صفحة	page-{slug}.html ← page-{id}.html ← page.html ← singular.html ← index.html
أرشيف تصنيف	category-{slug}.html ← category-{id}.html ← category.html ← archive.html ← index.html
نوع محتوى مخصص	single-{post-type}.html ← single.html ← singular.html ← index.html
صفحة 404	404.html ← index.html

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

والقوالب المعتمدة على الاسم اللطيف هشّة بطريقة تستحق أن ترسخ في ذهنك. فالملف page-about.html يطابق فقط ما دام الاسم اللطيف للصفحة هو about. أعِد تسمية الصفحة إلى about-us فيتوقف القالب عن الانطباق دون تحذير ودون خطأ.

القالب مقابل جزء القالب

القالب يعرض واجهة كاملة وتختاره الهرمية. وجزء القالب شذرة — ترويسة أو تذييل أو شريط جانبي — تستدعيها القوالب. الأجزاء تعيش في parts/ والقوالب في templates/، وتُخزَّن كلٌّ على حدة في قاعدة البيانات كسجلات wp_template_part.

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

والعكس يحدث أيضًا. تضع تخطيط صفحة كاملًا في parts/ ثم تتساءل لماذا لا تلتقطه الهرمية أبدًا. الأجزاء ليست مرشَّحة في الهرمية إطلاقًا؛ ولا شيء سيوجَّه إليها مباشرةً.

تسمية الملفات وموضعها

افحص هذه قبل أن تفترض شيئًا أكثر غرابة:

• المجلد هو templates/، بصيغة الجمع، في جذر القالب. لا template/ ولا block-templates/. وكان block-templates/ هو الاسم الصحيح في حقبة إضافة Gutenberg قبل أن تصل قوالب البلوكات إلى النواة، وما زالت شروحات كثيرة تعرضه — وهو لا يعمل في إصدارات ووردبريس الحالية.
• أجزاء القوالب توضع في parts/، لا في template-parts/ (وهذا عرف القوالب الكلاسيكية لأجزاء PHP).
• الامتداد هو .html. وأي ملف .php في templates/ يُتجاهَل.
• أسماء الملفات بحروف صغيرة وبشرطات. فلن يطابق single-Post.html ولا single_post.html. وعلى نظام ملفات لا يفرّق بين حالة الأحرف مثل macOS ينجح هذا محليًا وينكسر على خادم لينكس — وهو إخفاق «يعمل على جهازي» الكلاسيكي.
• يجب أن يوجد templates/index.html. وبدونه لا يصنّف ووردبريس القالب على أنه قالب بلوكات، وقد لا يظهر محرر الموقع إطلاقًا.
• إن كنت تعمل في قالب فرعي، فقوالبه لها الأولوية على قوالب الأصلي. وملف متبقٍّ في القالب الفرعي سيغلب بهدوء الملفَ الأصلي الذي تحرّره.

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

التخزين المؤقت — افحصه أخيرًا

التخزين المؤقت حقيقي لكنه أقل الأسباب احتمالًا، والقفز إليه أولًا هو ما يضيّع على الناس بعد الظهر كله.

امسح ذاكرة الصفحات، وإن كنت تشغّل ذاكرة كائنات دائمة مثل Redis أو Memcached فامسحها أيضًا — إذ يمكن أن تُحفظ فيها نتائج حلّ القوالب. ثم أعد التحميل مع تجاوز ذاكرة المتصفح.

وما لا يفيد: مسح OPcache. فقوالب البلوكات ملفات .html ولا يصرّفها PHP أبدًا، فلا شأن لـ OPcache بها. وإن بدا لك مرةً أن مسح OPcache أصلح هذه المشكلة، فقد تغيّر شيء آخر في الوقت نفسه.

ما زلت عالقًا؟

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

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