تابع add_theme_support چطور کار می‌کند؟
تابع add_theme_support برای فعال‌سازی قابلیت‌های قالب در وردپرس؛ بررسی پارامترها، post-thumbnails، title-tag، html5 و نکات کلیدی.
6 دقیقه مطالعه
چرا فعال‌سازی قابلیت‌های قالب اهمیت دارد؟
وردپرس یک هسته غنی دارد، اما قالب باید صریحاً بگوید که از کدام امکانات استفاده می‌کند. برای نمونه، اگر قالب از تصویر شاخص پشتیبانی نکند، پنل ویرایش هیچ فیلدی برای آن نمایش نمی‌دهد. اگر پشتیبانی از تگ عنوان فعال نشود، وردپرس تگ<title> را به‌درستی درج نمی‌کند و ابزارهای سئو نمی‌توانند آن را مدیریت کنند.
تابع add_theme_support() نقطه اتصال قالب به این امکانات است. بدون فراخوانی صحیح آن، بسیاری از قابلیت‌های هسته وردپرس در دسترس قالب قرار نمی‌گیرند و در نتیجه، پنل مدیریت نیز آن‌ها را نمایش نمی‌دهد.
تابع add_theme_support چیست؟
تابعadd_theme_support() یک تابع هسته وردپرس است که در فایل wp-includes/theme.php تعریف شده است. این تابع یک قابلیت (Feature) را به فهرست پشتیبانی‌های قالب اضافه می‌کند تا هسته وردپرس و افزونه‌های وابسته بتوانند از آن مطلع شوند.
نکته مهم این است که این تابع باعث فعال‌شدن خودکار قابلیت نمی‌شود؛ بلکه به وردپرس اعلام می‌کند که قالب می‌خواهد از این قابلیت استفاده کند. هسته وردپرس و افزونه‌ها بر اساس این اعلام، رفتار خود را تنظیم می‌کنند.
امضای تابع و پارامترها
امضای این تابع به‌شکل زیر است:function add_theme_support( $feature, ...$args ) {
global $_wp_theme_features;
// ...
}post-thumbnails: بدون آرگومان یا آرایه‌ای از پست تایپ‌ها
- title-tag: بدون آرگومان
- html5: آرایه‌ای از مواردی مانند comment-list، comment-form، search-form، gallery، caption، style، script
- custom-logo: آرایه‌ای از ابعاد و flex-height و flex-width
- post-formats: آرایه‌ای از فرمت‌ها مانند aside، video، gallery
- custom-header: آرایه‌ای از تنظیمات هدر
- custom-background: آرایه‌ای از تنظیمات پس‌زمینه
- automatic-feed-links: بدون آرگومان
- responsive-embeds: بدون آرگومان
- align-wide: بدون آرگومان
- editor-styles: بدون آرگومان
- wp-block-styles: بدون آرگومان
هوک صحیح فراخوانی
تابعadd_theme_support() باید در هوک after_setup_theme فراخوانی شود. اگر زودتر فراخوانی شود، ممکن است هسته وردپرس هنوز آماده پردازش آن نباشد. اگر دیرتر فراخوانی شود، بخشی از قابلیت‌ها اثر لازم را ندارند.
نمونه صحیح:
add_action( 'after_setup_theme', 'mytheme_setup' );
function mytheme_setup() {
add_theme_support( 'title-tag' );
add_theme_support( 'post-thumbnails' );
add_theme_support( 'html5', array(
'comment-list',
'comment-form',
'search-form',
'gallery',
'caption',
'style',
'script',
) );
add_theme_support( 'custom-logo', array(
'height' => 100,
'width' => 400,
'flex-height' => true,
'flex-width' => true,
) );
}load_theme_textdomain() برای بارگذاری فایل‌های ترجمه و توابع ثبت منو و سایدبار فراخوانی می‌شوند. برای مطالعه بیشتر درباره ثبت منو به راهنمای register_nav_menus و راهنمای wp_nav_menu مراجعه کنید.
قابلیت‌های پرکاربرد
برخی از قابلیت‌هایی که تقریباً همه قالب‌ها باید فعال کنند: -title-tag: مدیریت خودکار تگ عنوان توسط وردپرس. اگر فعال نباشد، قالب باید خودش <title> را درج کند و این کار با افزونه‌های سئو تداخل ایجاد می‌کند.
- post-thumbnails: فعال‌سازی تصویر شاخص برای نوشته‌ها و پست تایپ‌ها.
- html5: تولید نشانه‌گذاری مدرن برای فرم‌ها، گالری و بخش دیدگاه‌ها.
- automatic-feed-links: درج خودکار لینک فید RSS در هدر.
- custom-logo: امکان تعریف لوگوی سفارشی در سفارشی‌ساز قالب.
- responsive-embeds: واکنش‌گرا کردن خودکار iframeهای ویدیو.
- align-wide: فعال‌سازی گزینه‌های عرض کامل در ویرایشگر بلوک.
برای بررسی این پشتیبانی‌ها به‌صورت برنامه‌نویسی، از current_theme_supports() استفاده می‌شود که در ادامه بررسی می‌شود.
بررسی پشتیبانی قابلیت
تابعcurrent_theme_supports() بررسی می‌کند که آیا قالب فعال از یک قابلیت خاص پشتیبانی می‌کند یا نه:
if ( current_theme_supports( 'post-thumbnails' ) ) {
// کد برای زمانی که قالب از تصویر شاخص پشتیبانی می‌کند
}if ( current_theme_supports( 'post-thumbnails', 'book' ) ) {
// تصویر شاخص برای پست تایپ book فعال است
}کاربردهای عملی
یکی از رایج‌ترین کاربردها، استفاده از تصویر شاخص در حلقه است:if ( has_post_thumbnail() ) {
the_post_thumbnail( 'large' );
}post-thumbnails در after_setup_theme فعال شده است. اگر فراموش شود، تصویر شاخص در پنل ویرایش نمایش داده نمی‌شود.
کاربرد دیگر، استفاده از لوگوی سفارشی در قالب است:
if ( has_custom_logo() ) {
the_custom_logo();
} else {
echo '' . esc_html( get_bloginfo( 'name' ) ) . '';
}esc_url() و esc_html() استفاده شده است تا از حملات XSS جلوگیری شود. راهنمای این توابع در صفحه esc_html آمده است.
نقش در Child Theme
در Child Theme، تابعadd_theme_support می‌تواند در فایل functions.php قالب فرزند فراخوانی شود. اما توجه داشته باشید که:
- قابلیت‌هایی که Parent Theme فعال کرده، در Child Theme به‌ارث می‌رسند.
- فراخوانی مجدد در Child Theme معمولاً زائد است، مگر اینکه بخواهید قابلیت جدیدی اضافه کنید یا پارامترها را تغییر دهید.
- برای حذف یک قابلیت، از remove_theme_support() استفاده کنید.
الگوی حذف و افزودن مجدد:
add_action( 'after_setup_theme', 'mychild_override_support', 20 );
function mychild_override_support() {
remove_theme_support( 'custom-header' );
add_theme_support( 'custom-logo', array(
'height' => 80,
'width' => 320,
) );
}نکات امنیتی و اشتباهات رایج
اشتباه اول، نبود هوک درست است. فراخوانیadd_theme_support خارج از after_setup_theme ممکن است در برخی قابلیت‌ها اثر نداشته باشد یا باعث خطای Warning شود.
اشتباه دوم، نبود شرط در بررسی است. اگر افزونه‌ای بر پایه پشتیبانی قالب تصمیم می‌گیرد، باید همیشه current_theme_supports را بررسی کند.
اشتباه سوم، فراخوانی تکراری است. اگر یک قابلیت را چند بار با پارامترهای متفاوت اضافه کنید، آخرین فراخوانی جایگزین قبلی می‌شود و ممکن است نتیجه غیرمنتظره بدهد.
اشتباه چهارم، نبود escape در خروجی است. اگر قابلیتی مانند لوگوی سفارشی را در HTML چاپ می‌کنید، باید از توابع escape استفاده کنید.
اشتباه پنجم، نبود تست در Child Theme است. همیشه باید کد خود را در هر دو حالت Parent و Child Theme آزمایش کنید.
اشتباه ششم، نبود توجه به اولویت هوک است. اگر می‌خواهید فراخوانی شما بعد از Parent Theme اجرا شود، باید اولویت بالاتر (عدد بزرگ‌تر) بدهید.
تحلیل فنی پیشرفته
در نگاه مهندسی، تابعadd_theme_support() یک نقطه معماری در لایه قالب است که بر چند جنبه از سیستم اثر می‌گذارد. لایه اول لایه ثبت قابلیت است. این تابع قابلیت را در آرایه جهانی $_wp_theme_features ذخیره می‌کند که در طول درخواست HTTP باقی می‌ماند. این آرایه مبنای تصمیم‌گیری هسته وردپرس در بخش‌های مختلف است.
لایه دوم لایه افزونه‌پذیری است. با استفاده از current_theme_supports()، افزونه‌ها می‌توانند رفتار خود را بر اساس قابلیت‌های قالب تنظیم کنند. این الگو یکی از اصول طراحی افزونه‌های سازگار است.
لایه سوم لایه امنیت است. قابلیت‌هایی مانند html5 نشانه‌گذاری تولیدشده توسط وردپرس را تغییر می‌دهند. اگر قابلیت به‌درستی فعال نشود، نشانه‌گذاری قدیمی XHTML تولید می‌شود که ممکن است با استانداردهای مدرن ناسازگار باشد.
لایه چهارم لایه کشینگ است. نتیجه current_theme_supports در حافظه کش می‌شود. اگر در طول درخواست، قابلیتی اضافه یا حذف شود، کش باید باطل شود. برای حذف یک قابلیت از remove_theme_support استفاده کنید.
لایه پنجم لایه تست است. تست‌های End-to-End باید همه قابلیت‌های فعال‌شده را پوشش دهند. تست‌های واحد می‌توانند با WP_UnitTestCase و شبیه‌سازی قالب، رفتار این تابع را بررسی کنند.
لایه ششم لایه Multisite است. در شبکه‌های Multisite، هر سایت می‌تواند قالب متفاوتی داشته باشد و این تابع باید در هر سایت جداگانه فراخوانی شود.
لایه هفتم لایه استقرار است. اگر قالب جدیدی نصب شود و قابلیت‌های لازم فعال نشوند، ممکن است بخش‌های پنل مدیریت ناپدید شوند. به همین دلیل، مستندسازی قابلیت‌های فعال‌شده در قالب، یک نیاز جدی در پروژه‌های حرفه‌ای است.
لایه هشتم لایه Editor است. قابلیت‌هایی مانند align-wide، editor-styles و wp-block-styles مستقیماً تجربه ویرایشگر بلوک را تغییر می‌دهند. عدم فعال‌سازی صحیح آن‌ها، تجربه ویرایشگر را محدود می‌کند.
مفاهیم پایه‌ای وردپرس در WordPress در ویکی‌پدیا توضیح داده شده است.
برای مطالعه بیشتر روی ساختار قالب و توابع مرتبط، می‌توانید به راهنمای get_header، راهنمای get_footer، راهنمای get_sidebar و راهنمای body_class مراجعه کنید.
پرسش‌های پرتکرار
در کدام هوک باید add_theme_support را فراخوانی کرد؟ در هوکafter_setup_theme و با اولویت پیش‌فرض ۱۰ یا بالاتر.
آیا فراخوانی در functions.php بدون هوک کار می‌کند؟ خیر، ممکن است بخشی از قابلیت‌ها اثر نکنند.
تفاوت add_theme_support و current_theme_supports چیست؟ اولی قابلیت را اضافه می‌کند و دومی بررسی می‌کند که آیا اضافه شده است.
چطور یک قابلیت را حذف کنیم؟ با remove_theme_support در همان هوک after_setup_theme.
آیا در Child Theme باید همه قابلیت‌ها را دوباره اضافه کرد؟ خیر، قابلیت‌های Parent Theme به‌ارث می‌رسند.
نتیجه و مسیر ادامه
تابعadd_theme_support() نقطه اتصال قالب وردپرس به قابلیت‌های پیشرفته است. استفاده درست از آن یعنی فراخوانی در هوک صحیح، درک دقیق پارامترهای هر قابلیت، توجه به escape در خروجی و تست در Parent و Child Theme. اشتباه‌های کوچک در این تابع اغلب به ناپدید شدن بخش‌های پنل مدیریت یا ناسازگاری با افزونه‌های سئو منجر می‌شوند.
اگر این تابع را در پروژه‌ای واقعی به کار برده‌اید و رفتار غیرمنتظره‌ای دیده‌اید — به‌خصوص در ترکیب با Child Theme یا افزونه‌های سئو — تجربه‌تان می‌تواند راهگشای دیگران باشد. کدام بخش بیشترین زمان را از شما گرفت؟ دیدگاه خود را بنویسید.
سعید کریمه
نویسنده
نویسنده در وردپرس کار.