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

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

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

get_theme_file_uri( $file ) یک URI کامل نسبت به پوشه قالب (theme) بازمی‌گرداند. اگر پارامتر $file مشخص نشود، URI پوشه قالب را برمی‌گرداند. این تابع از نظر پشتیبانی از child themeها هوشمند است و در صورت وجود فایل در child theme ابتدا آن را بررسی می‌کند.

امضای تابع

تابع به این صورت فراخوانی می‌شود:

get_theme_file_uri( $file = '' )

پارامتر $file مسیری نسبی به داخل فولدر قالب است، برای مثال ‘assets/css/style.css’. بازگشتی تابع یک رشته (string) است که آدرس کامل فایل را می‌دهد.

نمونه ساده: لود کردن تصویر از قالب

$logo_url = get_theme_file_uri( 'images/logo.png' );

در این مثال آدرس فایل images/logo.png در قالب فعلی (در صورت وجود در Child Theme ابتدا آن‌جا را چک می‌کند) برگشت داده می‌شود. سپس می‌توانید از آن در تگ img یا CSS استفاده کنید.

استفاده در enqueue کردن استایل و اسکریپت

یکی از رایج‌ترین کاربردها، استفاده در توابع wp_enqueue_style و wp_enqueue_script است. به مثال زیر توجه کنید:

function mytheme_enqueue_assets() {
    wp_enqueue_style( 'mytheme-style', get_theme_file_uri( 'assets/css/main.css' ), array(), filemtime( get_theme_file_path( 'assets/css/main.css' ) ) );
    wp_enqueue_script( 'mytheme-script', get_theme_file_uri( 'assets/js/main.js' ), array('jquery'), filemtime( get_theme_file_path( 'assets/js/main.js' ) ), true );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_assets' );

در این کد، استایل و اسکریپت از پوشه assets قالب بارگذاری می‌شوند و مقدار نسخه (version) با استفاده از filemtime تنظیم شده تا کش مرورگر هنگام تغییر فایل بروزرسانی شود.

توضیح کامل کد بالا

wp_enqueue_style: اولویت، نام هندل، آدرس فایل با get_theme_file_uri، آرایه وابستگی‌ها و نسخه (filemtime)
get_theme_file_path: مسیر فیزیکی فایل در سرور را برمی‌گرداند که برای filemtime لازم است.
پارامتر true در wp_enqueue_script باعث می‌شود اسکریپت در فوتر قرار گیرد.

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

تابع	بازگشت	حمایت از Child Theme	کاربرد
get_theme_file_uri()	URI	بله — ابتدا Child Theme را چک می‌کند	دریافت آدرس فایل قالب (URI) برای استفاده در فرانت‌اند
get_theme_file_path()	مسیر فایل (path)	بله	برای توابعی که نیاز به مسیر فیزیکی دارند (مثل filemtime)
get_template_directory_uri()	URI	خیر — همیشه به parent theme اشاره می‌کند	دسترسی مستقیم به parent theme
get_stylesheet_directory_uri()	URI	بله — به قالب فعال (Child یا Parent) اشاره می‌کند	مشابه get_theme_file_uri در بسیاری موارد اما بدون بررسی locate

زمانی که باید از get_theme_file_uri() استفاده کنید

وقتی می‌خواهید فایلی را از قالب فعال (و در صورت وجود فایل در Child Theme) بار کنید.
هنگام enqueue کردن اسکریپت‌ها و استایل‌ها برای اطمینان از سازگاری با Child Theme.
وقتی می‌خواهید آدرس یک تصویر یا asset دیگر را در تمپلیت‌ها جایگذاری کنید.

نکات و ریزه‌کاری‌ها (Best Practices)

همیشه enqueue را داخل هوک مناسب مثل wp_enqueue_scripts (فرانت‌اند) یا admin_enqueue_scripts (داشبورد) فراخوانی کنید.
برای کنترل کش از filemtime( get_theme_file_path( $file ) ) به‌عنوان نسخه استفاده کنید، اما در محیط‌های تولیدی اگر از build tools (مثل webpack یا Gulp) استفاده می‌کنید، بهتر است نسخه‌بندی را توسط این ابزارها انجام دهید.
از load مشروط (conditional loading) برای کاهش بار صفحه استفاده کنید؛ فقط فایل‌هایی که در آن صفحه نیاز است enqueue شوند.
در child theme اگر می‌خواهید به فایل parent دسترسی مستقیم داشته باشید، از get_template_directory_uri() استفاده کنید.

نمونه: بارگذاری مشروط فقط در صفحه آرشیو

function mytheme_archive_assets() {
    if ( is_archive() ) {
        wp_enqueue_style( 'archive-style', get_theme_file_uri( 'assets/css/archive.css' ), array(), '1.0.0' );
    }
}
add_action( 'wp_enqueue_scripts', 'mytheme_archive_assets' );

در این مثال تنها وقتی صفحه آرشیو نمایش داده می‌شود، فایل archive.css بارگذاری می‌شود که باعث کاهش درخواست‌ها و بهبود سرعت می‌شود.

مثال پیشرفته: استفاده همراه با locate_template

گاه لازم است قبل از بارگذاری یا include یک فایل، اطمینان پیدا کنیم چه نسخه‌ای (Child یا Parent) استفاده می‌شود. locate_template می‌تواند مفید باشد:

$template = locate_template( 'partials/header-custom.php', false, false );
if ( $template ) {
    $uri = get_theme_file_uri( 'partials/header-custom.php' );
    // میتوانید از $uri یا include $template استفاده کنید
}

locate_template مسیر فیزیکی فایل را پیدا می‌کند و سپس می‌توانید با get_theme_file_uri آدرس فایل را برای استفاده در فرانت به‌دست آورید.

خلاصه و جمع‌بندی

get_theme_file_uri() تابعی ساده اما قدرتمند برای به‌دست آوردن آدرس فایل‌های قالب است که به‌صورت پیش‌فرض از Child Theme پشتیبانی می‌کند. هنگام enqueue کردن منابع، مدیریت نسخه و بارگذاری مشروط از آن استفاده کنید. در صورت نیاز به مسیر فیزیکی، از get_theme_file_path() کمک بگیرید. توجه به نکات بهینه‌سازی و سازگاری با Child/Parent themes باعث می‌شود قالب شما قابل توسعه و نگهداری‌پذیرتر باشد.

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

خیر

بله