آموزش تابع get_stylesheet_directory_uri() در وردپرس و کاربرد آن

تابع get_stylesheet_directory_uri() یکی از توابع پایه‌ای وردپرس برای به‌دست آوردن آدرس (URL) پوشهٔ قالب فعال است. این تابع به‌ویژه زمانی اهمیت دارد که از child theme استفاده می‌کنید، زیرا آدرس قالب فرزند را بازمی‌گرداند نه قالب والد.

خلاصهٔ عملکرد

• خروجی: یک رشتهٔ URL به‌صورت مثلاً https://example.com/wp-content/themes/your-child-theme
• زمان استفاده: وقتی می‌خواهید منابع (CSS، JS، تصاویر و فونت‌ها) را از پوشهٔ قالب فعلی بارگذاری کنید.
• تمایز مهم: در قالب فرزند، get_stylesheet_directory_uri() به قالب فرزند اشاره می‌کند؛ اما get_template_directory_uri() همیشه به قالب والد اشاره می‌کند.

تفاوت get_stylesheet_directory_uri() و get_template_directory_uri()

نمونه‌های عملی

1. ارجاع به فایل CSS یا تصویر در قالب

echo get_stylesheet_directory_uri() . '/assets/css/custom.css';

این خط آدرس فایل custom.css در پوشهٔ assets قالب فعال را برمی‌گرداند. در قالب فرزند هم به مسیر قالب فرزند ارجاع می‌دهد.

2. استفادهٔ امن با esc_url()

echo esc_url( get_stylesheet_directory_uri() . '/images/logo.png' );

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

3. enqueue کردن اسکریپت و استایل

function mytheme_enqueue_assets() {
    wp_enqueue_style(
        'mytheme-main',
        get_stylesheet_directory_uri() . '/assets/css/main.css',
        array(),
        filemtime( get_stylesheet_directory() . '/assets/css/main.css' )
    );

    wp_enqueue_script(
        'mytheme-scripts',
        get_stylesheet_directory_uri() . '/assets/js/main.js',
        array('jquery'),
        filemtime( get_stylesheet_directory() . '/assets/js/main.js' ),
        true
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_assets' );

در این مثال:

• از get_stylesheet_directory_uri() برای URL استفاده شده است.
• برای تعیین نسخه از filemtime() همراه با get_stylesheet_directory() (مسیر فایل سیستم) استفاده شده تا کش مرورگر هنگام آپدیت فایل‌ها بریزد.
• تابع به هوک wp_enqueue_scripts متصل شده که بهترین مکان برای قرار دادن enqueue است.

قواعد و بهترین شیوه‌ها

• همیشه enqueue کنید: بجای وارد کردن مستقیم لینک‌های CSS/JS در header/footer، از توابع enqueue وردپرس استفاده کنید تا وابستگی‌ها و نسخه‌ها مدیریت شوند.
• برای مسیر فایل‌های سیستم از get_stylesheet_directory() استفاده کنید. این تابع مسیر فیزیکی را برمی‌گرداند و برای توابعی مثل filemtime() ضروری است.
• اگر کدنویسی برای قالب والد انجام می‌دهید و می‌خواهید همیشه به فایل والد اشاره شود از get_template_directory_uri() استفاده کنید.
• برای استفاده در جاوااسکریپت لوکالایز شده، از wp_localize_script() یا wp_add_inline_script() و ارسال URL با استفاده از esc_url_raw() بهره ببرید.

مثال: ارسال آدرس قالب به جاوااسکریپت

function mytheme_localize_script() {
    wp_enqueue_script('mytheme-scripts');
    wp_localize_script(
        'mytheme-scripts',
        'MyThemeData',
        array(
            'themeUrl' => esc_url_raw( get_stylesheet_directory_uri() ),
            'ajaxUrl'  => admin_url( 'admin-ajax.php' )
        )
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_localize_script' );

در این قطعه، آدرس قالب در متغیر جاوااسکریپتی MyThemeData.themeUrl در دسترس قرار می‌گیرد. esc_url_raw() برای پاکسازی قبل از ارسال به اسکریپت استفاده شده است.

موارد خاص و نکات پیشرفته

• اگر پلاگینی هستید که فایل‌ها را بارگذاری می‌کند از توابع مربوط به پلاگین مثل plugin_dir_url() استفاده کنید؛ استفاده از مسیر قالب ممکن است اشتباه باشد.
• برای بارگذاری فایل‌ها در محیط ادمین از هوک admin_enqueue_scripts استفاده کنید و باز هم از get_stylesheet_directory_uri() استفاده نمایید اگر فایل در قالب قرار دارد.
• در زمان ساخت باندل‌ها یا بسته‌بندی منابع (مانند Webpack) برای کش‌بستینگ بهتر است از نسخه‌دهی تولیدی یا تغییر اسم فایل‌ها به‌جای استفاده از filemtime در محیط تولید استفاده شود.

چند اشتباه رایج

• استفاده از get_stylesheet_directory_uri() برای دسترسی به فایل سیستم — این تابع URL برمی‌گرداند، نه مسیر فیزیکی؛ برای filemtime باید از get_stylesheet_directory() استفاده کنید.
• عدم پاکسازی (escaping) خروجی‌ها — همیشه URLها را با esc_url() یا esc_url_raw() پاک کنید.
• اضافه کردن منابع مستقیماً در قالب بدون enqueue — باعث مشکلات کش و وابستگی می‌شود.

نمونهٔ اصلاح‌شده: اشتباه رایج و رفع آن

// اشتباه
$version = filemtime( get_stylesheet_directory_uri() . '/assets/css/main.css' );

// صحیح
$version = filemtime( get_stylesheet_directory() . '/assets/css/main.css' );

توضیح: در قطعهٔ اول تلاش شد filemtime روی یک URL اجرا شود که منجر به خطا می‌شود. در قطعهٔ دوم مسیر فیزیکی فایل با get_stylesheet_directory() استفاده شده است تا filemtime کار کند.

نتیجه‌گیری

تابع get_stylesheet_directory_uri() ابزاری ساده اما حیاتی برای توسعه‌دهندگان قالب وردپرس است. شناخت تفاوت آن با get_template_directory_uri()، استفادهٔ امن با escaping، و ترکیب آن با توابع مناسب برای مسیر فیزیکی باعث می‌شود منابع قالب به‌درستی و با قابلت نگهداری بالا بارگذاری شوند. با رعایت بهترین شیوه‌ها می‌توانید از مشکلات کش، ناسازگاری قالب فرزند/والد و مشکلات امنیتی جلوگیری کنید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال