در وردپرس، Child Theme (قالب فرزند) لایه استاندارد و امن سفارشی‌سازی قالب است که از دست رفتن تغییرات در زمان به‌روزرسانی را به‌طور کامل حذف می‌کند. بدون enqueue درست فایل style.css و بدون نسخه‌بندی مشخص، قالب فرزند نه به‌روزرسانی می‌شود و نه کش مرورگر به‌درستی Invalidate می‌شود. ساختار functions.php در قالب فرزند باید از منطق قالب والد جدا باشد و در زمان صحیح اجرا شود تا از تضاد جلوگیری شود. override فایل‌ها در قالب فرزند بر اساس مسیر نسبی انجام می‌شود و بدون درک Template Hierarchy، نتیجه غیرقابل پیش‌بینی خواهد بود. تست قالب فرزند در سه سطح ساختار، رفتار و ریسپانسیو انجام می‌شود و بدون آن، انتشار به تولید ریسک بالایی دارد. در این راهنما از ساختار پایه تا استقرار تولیدی قالب فرزند حرفه‌ای را با نگاه مهندسی و کد عملی پوشش می‌دهیم.

در پروژه‌های واقعی، اولین توصیه من به هر تیمی که می‌خواهد قالب را تغییر دهد، ساخت Child Theme است. بدون این لایه، تغییرات در اولین به‌روزرسانی قالب از بین می‌رود و بازسازی آن هفته‌ها زمان می‌برد. این راهنما همان لایه‌ای است که پیش از هر سفارشی‌سازی باید مستقر شود.

Child Theme چیست و چرا در پروژه‌های حرفه‌ای ضروری است؟

Child Theme یک قالب وردپرس است که از قالب دیگری (Parent Theme) ارث‌بری می‌کند و تغییرات را در لایه‌ای جدا نگه می‌دارد. هسته وردپرس به‌صورت بومی از این ساختار پشتیبانی می‌کند و در Template Hierarchy، ابتدا فایل‌های قالب فرزند را بررسی می‌کند.

برای درک پیش‌زمینه، راهنمای Template Hierarchy و اولویت قالب‌ها را بخوانید. اگر با ساختار فایل‌های قالب آشنایی ندارید، راهنمای ساختار فایل‌های قالب استاندارد وردپرس نقطه شروع مناسبی است.

نشانه‌هایی که Child Theme ضروری است

اگر قالب شما فعال به‌روزرسانی می‌شود، اگر تغییرات CSS یا PHP در قالب اصلی دارید، یا اگر می‌خواهید تغییرات را در Git نگه دارید، Child Theme انتخاب درستی است.

ساختار فایل‌های Child Theme

حداقل ساختار یک Child Theme شامل دو فایل است: style.css با هدر قالب فرزند و functions.php برای بارگذاری استایل والد و منطق اختصاصی. فایل‌های اختیاری شامل screenshot.png، پوشه inc برای منطق، و پوشه assets برای CSS و JS است.

الگوی پوشه‌بندی حرفه‌ای

توصیه می‌کنم در قالب فرزند، ساختاری مشابه قالب والد داشته باشید. این کار، انتقال منطق بین دو قالب را ساده‌تر می‌کند و در زمان دیباگ، مقایسه را آسان می‌کند. راهنمای ساخت ماژول سفارشی در قالب نقطه شروع مناسبی است.

فایل style.css و هدر صحیح قالب فرزند

هدر style.css در Child Theme باید شامل Template با نام پوشه قالب والد باشد. ساختار استاندارد به این شکل است:

/*
Theme Name: WordPressKar Child
Theme URI: https://wordpresskar.ir/
Description: Child theme for customization without breaking parent updates.
Author: WordPressKar Team
Author URI: https://wordpresskar.ir/
Template: parent-theme-folder
Version: 1.0.0
Text Domain: wordpresskar-child
*/

پارامتر Template باید دقیقاً مطابق نام پوشه قالب والد باشد، نه نام نمایشی. اشتباه رایج، استفاده از نام نمایشی است که باعث می‌شود وردپرس قالب فرزند را نشناسد.

نسخه‌بندی در Child Theme

همیشه نسخه را در هدر style.css مشخص کنید. این نسخه در enqueue استفاده می‌شود تا کش مرورگر Invalidate شود. بدون نسخه، تغییرات CSS در مرورگر کاربر دیده نمی‌شود.

functions.php و enqueue صحیح

در functions.php قالب فرزند، باید ابتدا استایل والد و سپس استایل فرزند را enqueue کنید. الگوی صحیح به این شکل است:

add_action( "wp_enqueue_scripts", function() {
    $parent_handle = "parent-theme-style";
    $child_version = wp_get_theme()->get( "Version" );

    wp_enqueue_style(
        "wordpresskar-child",
        get_stylesheet_uri(),
        array( $parent_handle ),
        $child_version
    );
}, 20 );

نکته مهم، استفاده از اولویت ۲۰ یا بالاتر است تا استایل والد قبل از استایل فرزند بارگذاری شود. اشتباه رایج، استفاده از @import در style.css است که عملکرد را کاهش می‌دهد و توصیه نمی‌شود.

برای مطالعه بیشتر، راهنمای تابع wp_enqueue_style در وردپرس و تابع wp_enqueue_script را ببینید.

بارگذاری شرطی CSS و JS در Child Theme

برای کاهش حجم صفحات، توصیه می‌کنم CSS و JS اختصاصی را فقط در صفحاتی که به آن نیاز دارند بارگذاری کنید. راهنمای بارگذاری شرطی CSS و JS در صفحات خاص نقطه شروع مناسبی است.

override فایل‌ها در Child Theme

برای override یک فایل قالب در Child Theme، کافی است فایل با همان مسیر نسبی در پوشه قالب فرزند قرار دهید. هسته وردپرس ابتدا فایل فرزند را بررسی می‌کند و اگر موجود نبود، به فایل والد می‌رود.

این قابلیت برای فایل‌های قالب مثل header.php، footer.php، single.php و فایل‌های partial کاربرد دارد.

محدودیت override در فایل‌های functions.php

فایل functions.php در Child Theme به‌صورت جدا بارگذاری می‌شود و جایگزین والد نمی‌شود. برای تغییر توابع والد، باید از hookها یا فیلترها استفاده کنید. راهنمای تابع do_action در وردپرس و تابع apply_filters در وردپرس را ببینید.

استفاده از هوک‌ها به‌جای override مستقیم

الگوی حرفه‌ای این است که به‌جای override مستقیم فایل‌های والد، از hookها و فیلترها استفاده کنید. این رویکرد، سازگاری با نسخه‌های آینده قالب والد را حفظ می‌کند.

add_filter( "the_content", function( $content ) {
    if ( is_singular( "post" ) ) {
        $content .= "<div class="wpk-note">سفارشی‌سازی از Child Theme</div>";
    }
    return $content;
} );

برای مطالعه بیشتر در مورد هوک‌ها، راهنمای تابع remove_action در وردپرس و تابع remove_filter در وردپرس را ببینید.

حذف توابع والد با remove_action

اگر قالب والد تابعی دارد که می‌خواهید حذف کنید، می‌توانید از remove_action یا remove_filter استفاده کنید. نکته مهم، دانستن اولویت و زمان اجرای hook است.

ترکیب Child Theme با Customizer

Child Theme و Customizer (سفارشی‌ساز) مکمل یکدیگر هستند. تنظیمات کاربر از Customizer در دیتابیس ذخیره می‌شود و Child Theme منطق نمایش را در functions.php مدیریت می‌کند.

برای مطالعه بیشتر، راهنمای Theme Customizer و تنظیمات زنده قالب را ببینید.

افزودن تنظیمات Customizer در Child Theme

می‌توانید تنظیمات Customizer را در Child Theme اضافه کنید بدون اینکه قالب والد را تغییر دهید:

add_action( "customize_register", function( $wp_customize ) {
    $wp_customize->add_section( "wpk_section", array(
        "title"    => "تنظیمات WordPressKar",
        "priority" => 30,
    ) );
    $wp_customize->add_setting( "wpk_footer_text", array(
        "default"           => "",
        "sanitize_callback" => "sanitize_text_field",
    ) );
    $wp_customize->add_control( "wpk_footer_text", array(
        "label"   => "متن فوتر سفارشی",
        "section" => "wpk_section",
        "type"    => "text",
    ) );
} );

Child Theme در قالب‌های بلاکی

در قالب‌های بلاکی، ساختار Child Theme متفاوت است. فایل theme.json در Child Theme به‌صورت خودکار با والد ادغام می‌شود و پوشه templates نیز می‌تواند override شود.

برای مطالعه بیشتر، راهنمای توسعه قالب بلاکی حرفه‌ای و راهنمای theme.json در وردپرس را ببینید.

override قالب در قالب بلاکی

برای override یک قالب بلاکی، فایل HTML مربوطه را در پوشه templates قالب فرزند قرار دهید. وردپرس ابتدا نسخه فرزند را بررسی می‌کند.

تست و دیباگ Child Theme

تست Child Theme در سه سطح انجام می‌شود: سطح ساختار (CSS و HTML)، سطح رفتار (توابع و hookها) و سطح ریسپانسیو. برای تست ساختار، از DevTools و اعتبارسنج W3C استفاده کنید. برای تست رفتار، تست واحد و E2E توصیه می‌شود.

add_action( "wp_footer", function() {
    if ( defined( "WP_DEBUG" ) && WP_DEBUG ) {
        error_log( "Child Theme Active: " . get_stylesheet_directory() );
    }
} );

برای تست‌های خودکار، راهنمای تست E2E وردپرس با Playwright را ببینید.

اشتباهات رایج در تست Child Theme

اشتباه اول، تست فقط در صفحه اصلی. اشتباه دوم، نادیده گرفتن override فایل‌ها. اشتباه سوم، نبود تست با کش فعال. اشتباه چهارم، نبود تست با قالب والد به‌روزرسانی‌شده. اشتباه پنجم، نبود تست ریسپانسیو.

امنیت و Escape در Child Theme

در Child Theme، همه داده‌های خروجی باید Escape شوند. برای متن از esc_html، برای URL از esc_url، برای Attributes از esc_attr و برای محتوای HTML از wp_kses_post استفاده کنید.

برای مطالعه بیشتر، راهنمای Escape کردن خروجی برای جلوگیری از XSS را ببینید. همچنین مفهوم Child Theme را در ویکی‌پدیا مرور کنید.

دسترسی‌پذیری در Child Theme

تغییرات Child Theme نباید ساختار دسترسی‌پذیری والد را خراب کند. برای مطالعه بیشتر، راهنمای ARIA در وردپرس را ببینید.

پرسش‌های پرتکرار درباره Child Theme

آیا Child Theme روی سرعت سایت اثر دارد؟

در حالت عادی خیر، چون فقط یک فایل CSS اضافه بارگذاری می‌شود. اگر منطق پیچیده اضافه کنید، ممکن است اثر داشته باشد.

آیا می‌توان از Child Theme برای قالب بلاکی استفاده کرد؟

بله، اما ساختار و رفتار متفاوت است و باید theme.json و پوشه templates را در نظر بگیرید.

آیا Child Theme روی به‌روزرسانی والد اثر دارد؟

خیر، Child Theme به‌طور خودکار با والد سازگار می‌ماند مگر اینکه فایل‌های override تغییر کنند.

چرا Child Theme من در پنل مدیریت ظاهر نمی‌شود؟

احتمالاً پارامتر Template در هدر style.css اشتباه است یا فایل style.css ناقص است.

آیا می‌توان چند Child Theme برای یک والد داشت؟

بله، اما هر بار فقط یک قالب فعال است.

آیا Child Theme با Polylang و WPML کار می‌کند؟

بله، اگر از توابع ترجمه وردپرس استفاده کنید، سازگاری کامل دارد.

نتیجه و مسیر ادامه

Child Theme لایه استاندارد و امن سفارشی‌سازی قالب در وردپرس است. کلید موفقیت، ساختار درست فایل‌ها، enqueue صحیح با نسخه‌بندی، استفاده از hookها به‌جای override مستقیم، و تست در سه سطح است. اگر این لایه با دقت طراحی شود، نگهداشت پروژه در طول سال‌ها ساده باقی می‌ماند.

پیشنهاد می‌کنم مسیر یادگیری را با Template Hierarchy پیشرفته ادامه دهید و سپس Theme Customizer پیشرفته را به‌عنوان تمرین عملی پیاده کنید.

اگر روی پروژه واقعی خود Child Theme ساخته‌اید، برایم جالب است بدانید کدام بخش — enqueue یا override فایل‌ها — بیشترین چالش را ایجاد کرده است. تجربه خودتان را در دیدگاه‌ها بنویسید.