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

wp_localize_script() یکی از توابع مهم وردپرس برای ارسال داده‌های PHP به فایل‌های جاوااسکریپت است. اگرچه نام آن «محلی‌سازی» (localize) را نشان می‌دهد، اما عملاً برای عبور دادن متغیرهای پویا مثل آدرس AJAX، nonce، پیام‌ها و تنظیمات استفاده می‌شود. در این مقاله به‌صورت دقیق و کاربردی کارکرد، پارامترها، مثال‌های واقعی، خطاهای معمول و بهترین شیوه‌ها را توضیح می‌دهیم.

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

• امکان ارسال داده‌های PHP (آدرس‌ها، nonce، پیام‌ها) به JS بدون hard-code کردن در فایل JS.
• حفظ امنیت از طریق تولید nonce و جلوگیری از افشای اطلاعات حساس.
• تطابق با فرایند enqueue وردپرس و جلوگیری از مشکلات وابستگی اسکریپت‌ها.

امکانات اصلی

با wp_localize_script شما می‌توانید یک شیء JS در صفحه تعریف کنید که شامل کلید/مقدارهایی است که در PHP تعریف کرده‌اید. این شیء قبل از فایل جاوااسکریپتِ موردنظر در خروجی HTML قرار می‌گیرد.

آرگومان‌ها و نحوه کار تابع

مثال ساده — ارسال آدرس AJAX و nonce

add_action( 'wp_enqueue_scripts', 'myplugin_enqueue_scripts' );
function myplugin_enqueue_scripts() {
    wp_enqueue_script( 'my-script', plugin_dir_url( __FILE__ ) . 'js/my-script.js', array('jquery'), '1.0', true );

    $data = array(
        'ajax_url' => admin_url( 'admin-ajax.php' ),
        'nonce'    => wp_create_nonce( 'my_action_nonce' ),
        'greeting' => __( 'سلام! عملیات با موفقیت انجام شد.', 'my-text-domain' ),
    );

    wp_localize_script( 'my-script', 'MyScriptData', $data );
}

توضیح: این کد ابتدا اسکریپت «my-script» را enqueue می‌کند و سپس با wp_localize_script آرایهٔ PHP را به یک شیء JS به نام MyScriptData تبدیل می‌کند. در فایل js/my-script.js می‌توانید از MyScriptData.ajax_url و MyScriptData.nonce استفاده کنید. تابع __() برای ارسال پیام قابل ترجمه استفاده شده است.

مثال در سمت جاوااسکریپت

(function($){
    $(document).ready(function(){
        console.log('AJAX URL:', MyScriptData.ajax_url);
        $.post(MyScriptData.ajax_url, {
            action: 'my_action',
            _ajax_nonce: MyScriptData.nonce,
            data: { foo: 'bar' }
        }, function(response){
            console.log('Response:', response);
        });
    });
})(jQuery);

توضیح: در این فایل JS ما به شیء MyScriptData دسترسی داریم و از ajax_url و nonce برای ارسال درخواست AJAX به وردپرس استفاده می‌کنیم. توجه کنید که MyScriptData باید قبل از اجرای این فایل در خروجی صفحه تعریف شده باشد که wp_localize_script این ترتیب را تضمین می‌کند.

خطاهای رایج و نحوه رفع آن‌ها

• عدم ثبت یا enqueue شدن handle: اگر handle وجود نداشته باشد پیام خطا دریافت می‌کنید یا شیء JS چاپ نمی‌شود. همیشه مطمئن شوید wp_enqueue_script فراخوانی شده است.
• استفاده از نام غیرمجاز برای $object_name: نام باید با حرف آغاز شود و شامل فاصله یا کاراکترهای غیرمجاز نباشد.
• افشای اطلاعات حساس: هر داده‌ای که مستقیماً به JS فرستاده شود در مرورگر دیده می‌شود؛ از ارسال اطلاعات حساس خودداری کنید.

نمونه مشکل و اصلاح

// غلط: استفاده از handle نادرست
wp_localize_script( 'wrong-handle', 'MyData', $data );

توضیح: اگر handle اشتباه باشد، داده در خروجی قرار نمی‌گیرد. راه‌حل ثبت و enqueue اسکریپت با نام صحیح قبل از فراخوانی wp_localize_script است.

بهترین شیوه‌ها و نکات امنیتی

• از wp_create_nonce برای تولید nonce و تایید آن در سمت سرور با check_ajax_referer استفاده کنید.
• تنها داده‌های ضروری را به JS ارسال کنید؛ اطلاعات حساس را به کلاینت نفرستید.
• برای رشته‌های قابل ترجمه در فایل‌های JS، از wp_set_script_translations و توابع i18n مناسب استفاده کنید. wp_localize_script برای مقادیر راه‌حل سریع است اما جایگزین کامل ترجمهٔ JS نیست.
• در نسخه‌های مدرن وردپرس می‌توانید برای افزودن کدهای inline سفارشی از wp_add_inline_script و wp_json_encode استفاده کنید، اما wp_localize_script هنوز راه ساده و امنی برای عبور آرایه دارد.

روش جایگزین با wp_add_inline_script

add_action( 'wp_enqueue_scripts', 'myplugin_enqueue_with_inline' );
function myplugin_enqueue_with_inline() {
    wp_enqueue_script( 'my-script', plugin_dir_url( __FILE__ ) . 'js/my-script.js', array(), '1.0', true );

    $data = array(
        'ajaxUrl' => admin_url( 'admin-ajax.php' ),
        'nonce'   => wp_create_nonce( 'my_action_nonce' )
    );

    $inline = 'var MyScriptData = ' . wp_json_encode( $data ) . ';';
    wp_add_inline_script( 'my-script', $inline, 'before' );
}

توضیح: این روش از wp_json_encode برای تبدیل آرایه به JSON استفاده می‌کند و سپس با wp_add_inline_script متغیر را قبل از اسکریپت اصلی در خروجی چاپ می‌کند. این روش کنترل دقیق‌تری روی قرارگیری و نوع داده‌ها می‌دهد، اما wp_localize_script هنوز خروجی امن و سازگار با وردپرس را تضمین می‌کند.

نتیجه‌گیری

wp_localize_script یک ابزار ساده و کاربردی برای ارسال داده‌های PHP به جاوااسکریپت در وردپرس است. با رعایت نکات امنیتی، استفادهٔ صحیح از handle و نام‌گذاری مناسب، و در نظر داشتن گزینه‌های مدرن مثل wp_add_inline_script و wp_set_script_translations می‌توانید رابط امن و قابل نگهداری بین PHP و JS ایجاد کنید. همیشه قبل از ارسال داده‌ به کلاینت از ضرورت آن اطمینان حاصل کنید و از nonce و توابع وردپرس برای امنیت استفاده نمایید.

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

ارسال