描述
仅当脚本已注册时有效。
接受关联数组$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_scripts和admin_enqueue_scripts)将脚本排队引入,但在排队时,想在稍后使用未确定的数据进行本地化,这将产生一些重大影响。
在这种情况下,请考虑使用 in_footer 参数设置为true,要延迟打印脚本,请将其包含到页面构建的更晚时间(即:wp_enqueue_script( $slug, $URL, $deps, $ver, true );
)。
最后一次本地化脚本的机会将出现在‘wp_print_footer_scripts’钩子。
源码
更新日志
版本 | 描述 |
---|---|
2.2.0 | 开始引入 |
使用示例
要从主题文件发送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); }, }); });
`wp_localize_script()`通常用于将通用数据从PHP传递到JavaScript,因为它最初是唯一的官方方式。
wp_add_inline_script()是在WP v4.5中引入的,现在是该用例的最佳实践。`wp_localize_script()`仅应在实际需要本地化字符串时使用。
实例
// 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)。如果您试图传递整数,则需要调用JavaScript
parseInt()
函数。// Call a function that needs an int. FinalZoom = map.getBoundsZoomLevel( bounds ) - parseInt( object_name.a_value, 10 );
注意,在单个会话中使用相同的对象名称多次调用此函数将覆盖前面的值,
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 );