الانتقال إلى المحتوى
القوالب

أنماط القالب الفرعي (Child Theme) لا تُحمّل في ووردبريس

ملف style.css الخاص بقالبك الفرعي لا يُحمّل لأن ووردبريس لا يقوم بإدراجه (enqueue) نيابةً عنك. يجب تسجيل ورقة أنماط القالب الفرعي يدويًا في

نُشر

ملف style.css الخاص بقالبك الفرعي لا يُحمّل لأن ووردبريس لا يقوم بإدراجه (enqueue) نيابةً عنك. يجب تسجيل ورقة أنماط القالب الفرعي يدويًا داخل ملف functions.php الخاص بالقالب الفرعي، وهذا الإدراج يحمل دائمًا تقريبًا أحد خطأين: إما أنه غير موجود من الأساس، أو أنه يُحمّل دون تحديد ورقة أنماط القالب الأصلي (parent) كتبعية (dependency)، فتقع قواعدك في المكان الخاطئ ضمن التتالي (cascade) ويجري تجاوزها. أصلِح الإدراج وتعود الأنماط. أما حيلة @import القديمة التي نسختها على الأرجح من شرح يعود لعام 2013 فهي الحل الخاطئ.

لماذا يحدث ذلك

القالب الفرعي الكلاسيكي يتكوّن من ملفين مطلوبين: ملف style.css يحمل كتلة ترويسة (header) تُسمّي القالب الأصلي، وملف functions.php. سطر Template: في الترويسة يخبر ووردبريس بأي قالب أصلي يرث القوالب (templates) منه. وهذا هو الشيء الوحيد الذي يفعله ووردبريس تلقائيًا. يقرأ الترويسة، ويربط آلية الرجوع للقوالب، ثم يتوقف. لا يقوم أبدًا بإدراج ملف style.css الخاص بقالبك الفرعي في الواجهة الأمامية.

في المقابل، يقوم القالب الأصلي بإدراج ورقة أنماطه هو من ملف functions.php الخاص به، مربوطةً بخطاف wp_enqueue_scripts. ملف functions.php الخاص بقالبك الفرعي يُنفَّذ أولًا، ثم ملف القالب الأصلي، ثم يُطلَق كل ما هو مرتبط بذلك الخطاف. فإن لم يستدعِ قالبك الفرعي أبدًا wp_enqueue_style لملفه الخاص، فلن يطلب المتصفح ذلك الملف مطلقًا. تبدو الصفحة كأنها القالب الأصلي الخام، لأنها كذلك بالضبط.

الفشل الثاني أدقّ. تقوم بإدراج ورقة أنماط القالب الفرعي، وتُحمّل فعلًا، لكن تجاوزاتك لا تفعل شيئًا. هذه مشكلة ترتيب تحميل (load-order). عندما تتساوى خصوصية (specificity) قاعدتين، تفوز القاعدة التي تُحمّل أخيرًا. فإن حُمّلت CSS القالب الفرعي قبل CSS القالب الأصلي، فاز الأصلي في كل تعادل. مصفوفة التبعيات في wp_enqueue_style هي ما يفرض الترتيب.

وأمرٌ آخر يخطئ فيه الناس: get_template_directory_uri() يشير إلى مجلد القالب الأصلي، بينما get_stylesheet_directory_uri() يشير إلى مجلد القالب النشط (الفرعي). إن بدّلت بينهما فإنك تُدرِج ملف style.css الخاص بالقالب الأصلي مرة ثانية ولا تلمس ملف القالب الفرعي إطلاقًا.

الحل، بالترتيب

أولًا، تأكّد مما يُحمّل فعلًا. افتح الصفحة المعطوبة، اعرض مصدر الصفحة (view source)، وابحث عن اسم مجلد قالبك الفرعي. يعرض ووردبريس الأنماط المُدرَجة على هيئة <link id="handle-css" href="..."> — القيمة id هي المُعرِّف (handle) الخاص بك مضافًا إليه -css. إن لم يكن ملف style.css الخاص بقالبك الفرعي موجودًا في <head> إطلاقًا، فإن الإدراج لا يُنفَّذ. وإن كان موجودًا لكن الأنماط لا تُطبَّق، فالمشكلة في التبعية أو الترتيب. هذا الفحص وحده يخبرك بأيٍّ من الخطأين تعاني.

ثانيًا، اعثر على المُعرِّف الحقيقي للقالب الأصلي. معظم القوالب الحديثة (Astra، GeneratePress، قوالب Twenty-*) تُدرِج ورقة أنماطها بالفعل تحت مُعرِّف محدد — astra-theme-css، generate-style-css، twenty-twenty-four-style، وهكذا. أنت بحاجة إلى هذه السلسلة النصية بالضبط. ابحث داخل ملفات القالب الأصلي، أو اقرأها من <link id="...-css"> في مصدر الصفحة (احذف -css من نهايتها).

ثالثًا، اكتب الإدراج. في الحالة الشائعة حيث يُحمّل القالب الأصلي ورقة أنماطه بنفسه، لا تُعِد إدراج القالب الأصلي. تقوم فقط بإدراج القالب الفرعي، وتُدرِج مُعرِّف القالب الأصلي كتبعية كي يُحمّل قالبك بعده:

<?php
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles', 20 );

function child_enqueue_styles() {
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'astra-theme-css' ), // <-- the parent's REAL handle
        wp_get_theme()->get( 'Version' )
    );
}

أما إذا كان القالب الأصلي لا يُدرِج ورقة أنماطه بنفسه (بعض القوالب القديمة أو البسيطة تعتمد على @import)، فأدرِج كليهما، واجعل القالب الفرعي يعتمد على الأصلي:

<?php
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles' );

function child_enqueue_styles() {
    wp_enqueue_style(
        'parent-style',
        get_template_directory_uri() . '/style.css'
    );
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'parent-style' ),
        wp_get_theme()->get( 'Version' )
    );
}

الوسيط wp_get_theme()->get('Version') هو أداة كسر التخزين المؤقت (cache-buster) لديك. ارفع رقم سطر Version: في ترويسة ملف style.css الخاص بالقالب الفرعي فتُعيد المتصفحات جلب الملف. تجاهله وستُعدّل CSS وتُقسم أن لا شيء يتغير، بينما هو مجرد ملف مخزّن مؤقتًا.

وإن كان في ملف functions.php خطأ في بناء الجملة (syntax error)، فسيموت الملف بأكمله بصمت ولن يُنفَّذ أيٌّ من عمليات الإدراج — وهذا يظهر تمامًا مثل “الأنماط لا تُحمّل”. فعّل WP_DEBUG، أو الصق ملف debug.log في أداة فك تشفير سجل أخطاء ووردبريس لدينا لرصد الخطأ الفادح بسرعة.

ما يجب تجنّبه

لا تستخدم @import. كانت النصيحة في عهد الـ Codex هي وضع @import url("../parenttheme/style.css"); في أعلى ملف style.css الخاص بالقالب الفرعي. إنها تعمل، لكنها بطيئة — لا يستطيع المتصفح بدء تنزيل CSS القالب الأصلي حتى ينتهي من تحليل CSS القالب الفرعي، فيعمل الطلبان تباعًا بدلًا من التوازي. حتى الدليل الرسمي لووردبريس ظل يوصي بعدم استخدامها لسنوات. إن أخبرك الشرح الذي اتبعته بفعل هذا، فذلك الشرح هو سبب اضطراب أنماطك.

لا تُثبّت المُعرِّف 'parent-style' يدويًا وتُدرِج ملف القالب الأصلي على العمياء. مقطع Codex الشهير يفعل هذا بالضبط، وهو خاطئ لأي قالب يُسجّل ورقة أنماطه أصلًا تحت مُعرِّف مختلف. ينتهي بك الأمر بتحميل CSS القالب الأصلي مرتين وتبعيتك تشير إلى مُعرِّف قد لا يكون موجودًا أصلًا.

لا تستدعِ wp_enqueue_style في المستوى الأعلى من ملف functions.php. يجب أن يُنفَّذ داخل دالة مربوطة بخطاف wp_enqueue_scripts. فإن استُدعي مبكرًا جدًا، فلن يفعل شيئًا.

لا تنسخ كامل ملف functions.php الخاص بالقالب الأصلي إلى القالب الفرعي. كلاهما يُحمّل؛ وملف القالب الفرعي يُنفَّذ أولًا. نسخه يسبب إعلانات دوال مكررة وخطأ فادح.

تنبيه واحد: كل هذا يخص القوالب الكلاسيكية (ذات قوالب PHP). فإن كان قالبك الأصلي قالب كتل (block theme)، فإن التنسيق يتدفق غالبًا عبر theme.json ومحرر الموقع (Site Editor)، وتتصرف تجاوزات style.css بشكل مختلف — لن أثق بهذا كثيرًا وسأختبره مباشرةً بدلًا من افتراض أن هذا الإدراج هو الحل.

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

تأكّد من أن سطر Template: في ترويسة ملف style.css الخاص بالقالب الفرعي يطابق تمامًا اسم مجلد القالب الأصلي، مع مراعاة حالة الأحرف — لا اسم العرض للقالب الأصلي. ثم أعد فحص مصدر الصفحة: المُعرِّف موجود، يُحمّل بعد القالب الأصلي، وسلسلة استعلام الإصدار (version query string) مرفوعة. فإن كان وسم <link> موجودًا ويُحمّل أخيرًا وما زالت CSS لا تُطبَّق، فلم تعد المشكلة في الإدراج — إنها الخصوصية (specificity)، وينتقل الحل إلى القواعد نفسها.