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

تابع wp_enqueue_script() یکی از توابع کلیدی در وردپرس است که برای افزودن و مدیریت فایل‌های جاوااسکریپت در قالب‌ها و افزونه‌ها استفاده می‌شود. استفاده صحیح از این تابع باعث می‌شود فایل‌های اسکریپت شما به صورت استاندارد، بهینه و بدون تداخل در سایت بارگذاری شوند.

چرا از wp_enqueue_script استفاده می‌کنیم؟

برخلاف روش‌های غیر استاندارد مثل قرار دادن مستقیم تگ <script> در فایل header.php یا footer.php، این تابع به شما کمک می‌کند تا:

وابستگی بین اسکریپت‌ها را مدیریت کنید.
از بارگذاری تکراری فایل‌ها جلوگیری کنید.
بارگذاری اسکریپت‌ها را در زمان مناسب (هدر یا فوتر) کنترل کنید.
سازگاری با افزونه‌ها و دیگر قالب‌ها را افزایش دهید.

ساختار و پارامترهای تابع wp_enqueue_script()

ساختار کلی این تابع به شکل زیر است:

wp_enqueue_script( 
    $handle, 
    $src = '', 
    $deps = array(), 
    $ver = false, 
    $in_footer = false 
);

در ادامه پارامترهای هر بخش را توضیح می‌دهیم:

پارامتر	توضیح
`$handle`	نام یکتای اسکریپت. با این نام وردپرس می‌تواند آن را شناسایی و مدیریت کند.
`$src`	آدرس فایل جاوااسکریپت. می‌تواند مسیر محلی یا URL باشد.
`$deps`	آرایه‌ای از نام اسکریپت‌هایی که این فایل به آن‌ها وابسته است (مثل jQuery).
`$ver`	شماره نسخه فایل. مفید برای مدیریت کش مرورگر.
`$in_footer`	اگر `true` باشد، اسکریپت در فوتر سایت بارگذاری می‌شود. در غیر این صورت در هدر.

نمونه استفاده پایه از wp_enqueue_script()

function my_theme_scripts() {
    wp_enqueue_script(
        'custom-js',
        get_template_directory_uri() . '/js/custom.js',
        array('jquery'),
        '1.0.0',
        true
    );
}
add_action('wp_enqueue_scripts', 'my_theme_scripts');

در مثال بالا:

یک فایل جاوااسکریپت با نام custom-js بارگذاری می‌شود.
فایل در مسیر /js/custom.js قرار دارد.
وابسته به jQuery است.
نسخه فایل 1.0.0 است.
در فوتر بارگذاری می‌شود تا سرعت بارگذاری صفحه افزایش یابد.

توضیح منطق

تابع بالا در زمان اجرای اکشن wp_enqueue_scripts فراخوانی می‌شود که مخصوص بارگذاری فایل‌های CSS و JS در فرانت‌اند وردپرس است. این روش باعث می‌شود اسکریپت شما فقط در زمان مناسب و بدون تداخل با دیگر فایل‌ها اضافه شود.

بارگذاری اسکریپت فقط در صفحات خاص

گاهی نیاز است که فایل جاوااسکریپت فقط در برخی صفحات خاص سایت بارگذاری شود. برای مثال فقط در صفحه خانه یا در صفحه تماس با ما:

function load_homepage_script() {
    if ( is_front_page() ) {
        wp_enqueue_script(
            'home-slider',
            get_template_directory_uri() . '/js/home-slider.js',
            array('jquery'),
            '1.2.1',
            true
        );
    }
}
add_action('wp_enqueue_scripts', 'load_homepage_script');

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

مدیریت وابستگی‌ها بین اسکریپت‌ها

اگر چند فایل دارید که به ترتیب خاصی باید بارگذاری شوند (مثلاً اسکریپتی که به jQuery وابسته است)، پارامتر $deps بسیار مفید است.

wp_enqueue_script(
    'gallery-init',
    get_template_directory_uri() . '/js/gallery-init.js',
    array('jquery', 'lightbox'),
    '1.0.0',
    true
);

در اینجا، اسکریپت gallery-init.js فقط پس از jquery و lightbox بارگذاری می‌شود. وردپرس به صورت خودکار ترتیب را تنظیم می‌کند.

بارگذاری فایل‌های خارجی (CDN)

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

function load_external_js() {
    wp_enqueue_script(
        'bootstrap-js',
        'https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js',
        array('jquery'),
        '5.3.0',
        true
    );
}
add_action('wp_enqueue_scripts', 'load_external_js');

در این مثال، اسکریپت Bootstrap از CDN بارگذاری می‌شود که باعث افزایش سرعت دسترسی کاربران می‌گردد.

تفاوت wp_register_script و wp_enqueue_script

در وردپرس می‌توانید ابتدا یک اسکریپت را ثبت (register) کرده و سپس در زمان مورد نیاز صف (enqueue) کنید:

function register_and_enqueue() {
    wp_register_script(
        'theme-main',
        get_template_directory_uri() . '/js/main.js',
        array('jquery'),
        '1.0.0',
        true
    );

    if ( is_page('contact') ) {
        wp_enqueue_script('theme-main');
    }
}
add_action('wp_enqueue_scripts', 'register_and_enqueue');

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

مقایسه سریع

تابع	کارکرد
`wp_register_script()`	ثبت اسکریپت با نام، مسیر و پارامترها بدون بارگذاری آن.
`wp_enqueue_script()`	افزودن اسکریپت به صف بارگذاری و نمایش در خروجی HTML.

نکات مهم و بهترین شیوه‌ها (Best Practices)

همیشه از wp_enqueue_scripts برای فرانت‌اند و admin_enqueue_scripts برای داشبورد استفاده کنید.
هرگز مستقیماً از <script> در فایل‌های قالب استفاده نکنید.
از نسخه‌دهی دقیق استفاده کنید تا کش مرورگر به درستی مدیریت شود.
اسکریپت‌های غیرضروری را فقط در صفحات لازم بارگذاری کنید.
برای افزایش سرعت سایت، اسکریپت‌ها را در فوتر ($in_footer = true) بارگذاری کنید.

نمونه کامل حرفه‌ای

function theme_load_assets() {
    // ثبت اسکریپت‌ها
    wp_register_script(
        'theme-main',
        get_template_directory_uri() . '/assets/js/main.js',
        array('jquery'),
        '2.5.0',
        true
    );

    wp_register_script(
        'theme-analytics',
        'https://www.googletagmanager.com/gtag/js?id=UA-XXXXXXX-X',
        array(),
        null,
        false
    );

    // بارگذاری شرطی
    wp_enqueue_script('theme-main');

    if ( !is_user_logged_in() ) {
        wp_enqueue_script('theme-analytics');
    }
}
add_action('wp_enqueue_scripts', 'theme_load_assets');

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

جمع‌بندی نکات کلیدی

wp_enqueue_script() روشی استاندارد و امن برای افزودن فایل‌های JS در وردپرس است.
با استفاده از پارامترها می‌توانید نسخه، وابستگی و محل بارگذاری را کنترل کنید.
مدیریت شرطی و وابستگی‌ها عملکرد و سرعت سایت را بهبود می‌دهد.
رعایت این اصول باعث سازگاری قالب یا افزونه شما با اکوسیستم وردپرس می‌شود.

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

خیر

بله