تابع get_template_directory_uri در وردپرس

تابع get_template_directory_uri() یکی از توابع پایه‌ای وردپرس برای بدست آوردن آدرس (URL) قالب یا پوستهٔ فعال است. این تابع زمانی کاربرد دارد که بخواهید مسیر منابع پوسته مثل فایل‌های CSS، جاوااسکریپت یا تصاویر را به‌صورت داینامیک در قالب‌تان استفاده کنید. در این مقاله به صورت عمیق تفاوت‌ها، نمونه‌های کاربردی، بهترین شیوه‌ها و نکات امنیتی پیرامون این تابع را بررسی می‌کنیم.

چیست و چه کاری انجام می‌دهد؟

تابع get_template_directory_uri() آدرس فولدر قالب اصلی (Parent Theme) را برمی‌گرداند. خروجی معمولاً شبیه به این است:

https://example.com/wp-content/themes/your-theme

این تابع فقط آدرس را برمی‌گرداند، بنابراین اگر می‌خواهید آن را چاپ کنید از echo استفاده کنید یا توابعی مانند get_theme_file_uri() را برای فایل‌های درون قالب به کار ببرید.

تفاوت با توابع مشابه

get_stylesheet_directory_uri(): آدرس قالب فعال (child theme در صورت وجود) را برمی‌گرداند.
get_theme_file_uri( $file ): آدرس یک فایل داخل پوسته را برمی‌گرداند و در صورت وجود فایل در child theme ابتدا آن را بررسی می‌کند.
get_template_directory() و get_stylesheet_directory(): مسیرهای فیزیکی (filesystem path) را برمی‌گردانند، نه URL.

وقتی باید از get_template_directory_uri() استفاده کنید

وقتی مطمئنید فایل موردنظر در قالب والد (parent theme) قرار دارد و نمی‌خواهید از نسخهٔ child استفاده شود.
در پلاگین‌ها وقتی می‌خواهید به قالب خاصی که پلاگین روی آن حساب می‌کند اشاره کنید (با احتیاط و مستندسازی).

نمونه‌های عملی و بهترین شیوه‌ها

1. افزودن فایل CSS و JS با enqueue

بهترین روش برای بارگذاری فایل‌های استایل و اسکریپت در وردپرس استفاده از توابع wp_enqueue_style و wp_enqueue_script است. مثال زیر را در فایل functions.php قرار دهید:

function mytheme_enqueue_assets() {
    wp_enqueue_style( 'mytheme-main', get_template_directory_uri() . '/assets/css/main.css', array(), '1.0.0' );
    wp_enqueue_script( 'mytheme-main', get_template_directory_uri() . '/assets/js/main.js', array('jquery'), '1.0.0', true );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_assets' );

در این کد، get_template_directory_uri() مسیر فایل CSS و JS داخل پوشهٔ قالب والد را می‌سازد و سپس با wp_enqueue_* به وردپرس اعلام می‌کند که این فایل‌ها بارگذاری شوند.

2. بهینه‌سازی کش (cache-busting)

برای جلوگیری از لود نسخهٔ کش‌شدهٔ فایل‌ها بعد از بروزرسانی می‌توانید از زمان تغییر فایل استفاده کنید:

function mytheme_enqueue_assets() {
    $css_file = get_template_directory() . '/assets/css/main.css';
    $version = file_exists( $css_file ) ? filemtime( $css_file ) : '1.0.0';
    wp_enqueue_style( 'mytheme-main', get_template_directory_uri() . '/assets/css/main.css', array(), $version );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_assets' );

در این مثال با استفاده از filemtime شماره نسخه بر اساس زمان آخرین تغییر فایل تنظیم می‌شود تا مرورگرها پس از به‌روزرسانی فایل، نسخهٔ جدید را بگیرند.

3. استفاده در تگ تصویر یا لینک‌ها

<img src="<?php echo esc_url( get_template_directory_uri() . '/images/logo.png' ); ?>" alt="Logo">

از esc_url() برای امن‌سازی URL خروجی استفاده کنید تا از تزریق آدرس‌های مخرب جلوگیری شود. این روش مناسب زمانی است که تصویر در قالب والد قرار دارد.

مقایسه جدول: توابع مرتبط

تابع	خروجی	مناسب برای
get_template_directory_uri()	URL قالب والد	فایل‌هایی که فقط در parent theme هستند
get_stylesheet_directory_uri()	URL قالب فعال (child یا parent)	بارگذاری منابع قابل override توسط child theme
get_theme_file_uri( $file )	URL فایل داخل قالب (در اولویت child)	دسترسی امن به فایل‌هایی که ممکن است در child جایگزین شوند

نکات فنی و توصیه‌های امنیتی

همیشه خروجی‌های URL را با esc_url() خروجی دهید.
از wp_enqueue_script/style به جای قرار دادن مستقیم تگ‌ها در header/footer استفاده کنید تا تداخل پلاگین‌ها کاهش یابد.
در قالب‌هایی که child theme پشتیبانی می‌شود، اگر می‌خواهید اجازه دهید کاربر قالب فرزند فایل‌ها را بازنویسی کند از get_stylesheet_directory_uri() یا get_theme_file_uri() استفاده کنید.
هرگز آدرس‌های ثابت با پروتکل (http/https) را هاردکد نکنید؛ از توابع وردپرس استفاده کنید تا پروتکل سایت رعایت شود.

مثال‌ پیشرفته: بارگذاری فایل از parent اگر در child وجود نداشت

تابع get_theme_file_uri() این منطق را به‌صورت پیش‌فرض پیاده می‌کند، اما اگر بخواهید دستی کنترل کنید:

$file_in_child = get_stylesheet_directory() . '/assets/css/custom.css';
if ( file_exists( $file_in_child ) ) {
    $url = get_stylesheet_directory_uri() . '/assets/css/custom.css';
} else {
    $url = get_template_directory_uri() . '/assets/css/custom.css';
}
wp_enqueue_style( 'mytheme-custom', esc_url( $url ), array(), null );

در این مثال ابتدا بررسی می‌کنیم آیا فایل در child theme وجود دارد یا نه؛ اگر وجود داشته باشد از آن استفاده می‌کنیم وگرنه به parent برمی‌گردیم. این الگو برای توسعه‌دهندگان قالب بسیار کاربردی است.

جمع‌بندی

تابع get_template_directory_uri() ابزار ساده و قدرتمندی برای دستیابی به URL قالب والد است، اما باید تفاوت آن با توابع دیگر را بدانید و در موقع مناسب از آن استفاده کنید. برای تعامل صحیح با child theme، مدیریت کش و امنیت خروجی‌ها از توابع و روش‌های معرفی‌شده بهره ببرید تا سازگاری و کیفیت قالب شما افزایش یابد.

آیا این مطلب برای شما مفید بود ؟

خیر

بله