当前浏览:首页 / WordPress函数 / wp_localize_script()

wp_localize_script( string $handle, string $object_name, array $l10n )

本地化脚本

scriptmore...


描述

仅当脚本已注册时有效。

接受关联数组$l10n并创建JavaScript对象:

"$object_name" = {
    key: value,
    key: value,
    ...
}

另见

  • WP_Scripts::localize()

参数

$handle

(string)(必填) 数据将附加到其上的脚本句柄。

$object_name

(string)(必填) JavaScript对象的名称。直接传递,因此它应该是限定的JS变量。例如:'/[a-zA-Z0-9_]+/'。

$l10n

(array)(必填) 数据本身。数据可以是单个或多维数组。


返回

(bool) 如果脚本已成功本地化,则为true,否则为false。


更多信息

此函数使用JavaScript变量的数据本地化已注册的脚本。

这使您可以为脚本中使用的任何字符串提供适当的本地化翻译。这是必要的,因为WordPress目前只提供PHP中的本地化API,而不是直接提供JavaScript(请参见ticket#20491)。

虽然本地化是主要用途,但它通常用于将通用数据从PHP传递到JavaScript,因为它最初是唯一的官方方式。wp_add_inline_script()在WordPress 4.5中引入,现在是该用例的最佳实践。`wp_localize_script()`应该只在你真正想对字符串进行本地化时使用。

$object_name是将包含数据的变量的名称。请注意,这对于脚本和插件或主题都是唯一的。因此,此处的值应正确地以slug或另一个唯一值作为前缀,以防止冲突。但是,由于这是一个JavaScript对象名,因此不能包含破折号。使用下划线或大小写。

$l10n是数据本身。数据可以是单维或多维数组(如3.3)。与json_encode()一样,如果数组是关联数组(映射),则数据将是JavaScript对象,否则数组将是JavaScript数组。

 

很重要!wp_localize_script()必须在已使用wp_register_script()wp_enqueue_script()注册脚本之后调用。

此外,包含本地化变量的JavaScript <script>标签的实际输出发生在引入的脚本被打印(输出/包含在页面上)的时候。当您使用适当的操作(wp_enqueue_scriptsadmin_enqueue_scripts)将脚本排队引入,但在排队时,想在稍后使用未确定的数据进行本地化,这将产生一些重大影响。

在这种情况下,请考虑使用 in_footer 参数设置为true,要延迟打印脚本,请将其包含到页面构建的更晚时间(即:wp_enqueue_script( $slug, $URL, $deps, $ver, true ); )。
最后一次本地化脚本的机会将出现在‘wp_print_footer_scripts’钩子。



源码

查看源码 官方文档


更新日志

版本描述
2.2.0开始引入

使用示例

  • 示例1

    要从主题文件发送ajax请求,我们可以使用wp_localize_script全局声明javascript变量。

    function theme_enqueue_scripts() {
    	/**
    	 * frontend ajax requests.
    	 */
    	wp_enqueue_script( 'frontend-ajax', JS_DIR_URI . 'frontend-ajax.js', array('jquery'), null, true );
    	wp_localize_script( 'frontend-ajax', 'frontend_ajax_object',
    		array( 
    			'ajaxurl' => admin_url( 'admin-ajax.php' ),
    			'data_var_1' => 'value 1',
    			'data_var_2' => 'value 2',
    		)
    	);
    }
    add_action( 'wp_enqueue_scripts', 'theme_enqueue_scripts' );

    在我们的js文件中,我们可以使用任何全局声明的变量frontend_ajax_object.ajaxurl, frontend_ajax_object.data_var_1, frontend_ajax_object.data_var_1.

    jQuery(document).ready(function($) {
    	$.ajax({
            url: frontend_ajax_object.ajaxurl,
            type: 'get',
            data: {
                'action':'states_city_filter'
            },
            success: function( response ) {
            	console.log(response);
            },
        });
    });
  • 示例2

    `wp_localize_script()`通常用于将通用数据从PHP传递到JavaScript,因为它最初是唯一的官方方式。

    wp_add_inline_script()在WP v4.5中引入的,现在是该用例的最佳实践。`wp_localize_script()`仅应在实际需要本地化字符串时使用。

  • 示例3

    实例

    // Register the script
    wp_register_script( 'some_handle', 'path/to/myscript.js' );
    
    // Localize the script with new data
    $translation_array = array(
    	'some_string' => __( 'Some string to translate', 'plugin-domain' ),
    	'a_value' => '10'
    );
    wp_localize_script( 'some_handle', 'object_name', $translation_array );
    
    // Enqueued script with localized data.
    wp_enqueue_script( 'some_handle' );
    

    您可以访问JavaScript中的变量,如下所示:

    // alerts 'Some string to translate'
    alert( object_name.some_string );
    

    注意:结果JavaScript调用中的数据将作为文本传递(请参阅ticket #25280)。如果您试图传递整数,则需要调用JavaScriptparseInt()函数。

    // Call a function that needs an int.
    FinalZoom = map.getBoundsZoomLevel( bounds ) - parseInt( object_name.a_value, 10 ); 
    
  • 示例4

    注意,在单个会话中使用相同的对象名称多次调用此函数将覆盖前面的值,

    wp_localize_script( 'some_handle', 'object_name', $value1 );
    ... code executed again...
    wp_localize_script( 'some_handle', 'object_name', $value2 ); // object_name is now set to $value2.
    

    如果需要将多个数据集与同一脚本(句柄)关联,

    wp_localize_script( 'some_handle', 'object_name1', $value1 );
    ... code executed again...
    wp_localize_script( 'some_handle', 'object_name2', $value2 );