分析 wp_localize_script 如何将 PHP 变量注入前端 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

好的，现在开始我们的讲座，主题是：wp_localize_script 如何将 PHP 变量注入前端。

今天我们将深入探讨 WordPress 中的 wp_localize_script 函数，它是一种优雅且安全的方式，将 PHP 变量传递到你的 JavaScript 代码中。理解它的工作原理对于构建动态的 WordPress 主题和插件至关重要。

1. 为什么我们需要 wp_localize_script?

在 WordPress 开发中，我们经常需要在前端 JavaScript 代码中使用来自后端的 PHP 数据。例如，你可能需要：

从数据库中获取的数据。
配置选项的值。
用户角色或权限信息。
翻译文本字符串。

直接在 JavaScript 代码中硬编码这些值是不明智的，原因如下：

可维护性差: 如果值发生变化，你需要在多个文件中进行修改。
安全性风险: 直接在 JavaScript 中暴露敏感信息（例如数据库凭据）是不安全的。
缺乏灵活性: 无法根据不同的环境或用户动态更改值。

wp_localize_script 提供了一个安全且结构化的方式来解决这些问题。

2. wp_localize_script 的工作原理

wp_localize_script 函数将 PHP 变量转换为 JavaScript 对象，并将其附加到已注册的 JavaScript 脚本中。它本质上是在 JavaScript 脚本执行之前，注入一段 JavaScript 代码来定义一个全局 JavaScript 对象，该对象包含你的 PHP 数据。

3. wp_localize_script 的语法

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

$handle (string, required): 已注册的 JavaScript 脚本的句柄 (handle)。这是你使用 wp_register_script 或 wp_enqueue_script 注册脚本时使用的名称。这个句柄必须已经存在，否则 wp_localize_script 将不会生效。
$object_name (string, required): 你将在 JavaScript 中使用的 JavaScript 对象的名称。这将在全局作用域中创建一个 JavaScript 对象，其中包含你的 PHP 数据。建议使用有意义的名称，以避免命名冲突。
$l10n (array, required): 一个关联数组，其中包含你要传递到 JavaScript 的 PHP 数据。数组的键将成为 JavaScript 对象中的属性名，数组的值将成为属性的值。

4. 使用 wp_register_script 和 wp_enqueue_script

在使用 wp_localize_script 之前，你需要先注册并加载你的 JavaScript 脚本。这是通过 wp_register_script 和 wp_enqueue_script 函数完成的。

wp_register_script( string $handle, string $src, array $deps = array(), string|bool|null $ver = false, bool $in_footer = false ): 注册一个 JavaScript 脚本，但不会立即加载它。
- $handle: 脚本的唯一句柄 (handle)。
- $src: 脚本的 URL。
- $deps: 一个数组，包含此脚本所依赖的其他脚本的句柄。 WordPress 会确保在加载此脚本之前加载所有依赖项。
- $ver: 脚本的版本号。用于缓存清除。
- $in_footer: 一个布尔值，指示是否在 wp_footer() 钩子中加载脚本（默认为 false，即在 <head> 中加载）。
wp_enqueue_script( string $handle, string $src = '', array $deps = array(), string|bool|null $ver = false, bool $in_footer = false ): 注册并加载一个 JavaScript 脚本。如果脚本已经注册，则只需加载它。

5. 一个完整的例子

让我们看一个完整的例子，演示如何使用 wp_localize_script 将 PHP 数据传递到 JavaScript。

PHP (functions.php 或插件文件):

<?php

function my_enqueue_scripts() {
    // 1. 注册脚本
    wp_register_script(
        'my-custom-script', // 句柄 (handle)
        get_template_directory_uri() . '/js/my-script.js', // 脚本的 URL
        array( 'jquery' ), // 依赖项 (jQuery)
        '1.0', // 版本号
        true // 在 footer 中加载
    );

    // 2. 传递 PHP 数据到 JavaScript
    wp_localize_script(
        'my-custom-script', // 句柄 (handle) - 必须与注册脚本时使用的句柄相同
        'my_script_vars', // JavaScript 对象的名称
        array(
            'ajax_url' => admin_url( 'admin-ajax.php' ), // WordPress AJAX URL
            'nonce'    => wp_create_nonce( 'my_ajax_nonce' ), // 安全的 nonce 值
            'site_title' => get_bloginfo( 'name' ), // 站点标题
            'is_admin' => is_admin(), // 是否在后台
            'user_id' => get_current_user_id(),  //当前用户ID
            'translations' => array( // 翻译
                'loading' => __( 'Loading...', 'my-theme' ),
                'error'   => __( 'An error occurred.', 'my-theme' ),
            ),
            'post_data' => array( // 示例数据
                'post_id' => get_the_ID(),
                'post_title' => get_the_title(),
            ),
        )
    );

    // 3. 加载脚本
    wp_enqueue_script( 'my-custom-script' );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

// Example AJAX action
add_action( 'wp_ajax_my_action', 'my_ajax_callback' );
add_action( 'wp_ajax_nopriv_my_action', 'my_ajax_callback' );

function my_ajax_callback() {
    check_ajax_referer( 'my_ajax_nonce', 'security' ); // Verify the nonce

    $data = array(
        'message' => 'Hello from the server!',
        'time' => current_time( 'mysql' ),
    );

    wp_send_json_success( $data );
}

?>

JavaScript (js/my-script.js):

jQuery(document).ready(function($) {
    // 使用从 PHP 传递过来的变量
    console.log(my_script_vars.ajax_url); // 输出 WordPress AJAX URL
    console.log(my_script_vars.site_title); // 输出站点标题
    console.log(my_script_vars.is_admin); // 输出是否在后台
    console.log(my_script_vars.user_id); // 输出当前用户ID
    console.log(my_script_vars.translations.loading); // 输出 "Loading..."
    console.log(my_script_vars.post_data.post_id); // 输出 post_id
    console.log(my_script_vars.post_data.post_title); // 输出 post_title

    // 使用 AJAX
    $.ajax({
        url: my_script_vars.ajax_url,
        type: 'POST',
        data: {
            action: 'my_action',
            security: my_script_vars.nonce
        },
        success: function(response) {
            if (response.success) {
                console.log(response.data.message); // 输出 "Hello from the server!"
                console.log(response.data.time); // 输出 服务器时间
            } else {
                console.log('Error:', response);
            }
        },
        error: function(error) {
            console.log('AJAX Error:', error);
        }
    });
});

解释:

注册脚本: 在 my_enqueue_scripts 函数中，我们使用 wp_register_script 注册了一个名为 my-custom-script 的 JavaScript 脚本。我们指定了脚本的 URL、依赖项 (jQuery) 和版本号。 true 参数表示脚本将在 wp_footer() 钩子中加载。
传递 PHP 数据: 我们使用 wp_localize_script 将一个名为 my_script_vars 的 JavaScript 对象附加到 my-custom-script 脚本。 my_script_vars 对象包含 ajax_url、nonce、site_title、is_admin、user_id、translations 和 post_data 属性，这些属性的值来自 PHP 变量。
加载脚本: 我们使用 wp_enqueue_script 加载 my-custom-script 脚本。
在 JavaScript 中使用数据: 在 my-script.js 文件中，我们可以通过 my_script_vars 对象访问从 PHP 传递过来的数据。例如，my_script_vars.ajax_url 包含 WordPress AJAX URL，my_script_vars.site_title 包含站点标题。
AJAX Example: 此示例演示了如何使用 wp_localize_script 传递 AJAX URL 和 nonce 值，以便在 JavaScript 中进行 AJAX 请求。 wp_create_nonce 函数生成一个安全的 nonce 值，用于验证 AJAX 请求的真实性。使用 check_ajax_referer 函数在服务器端验证 nonce。

6. 使用场景及代码示例

使用场景	PHP 代码示例	JavaScript 代码示例
传递配置选项	`php $options = get_option( 'my_plugin_options' ); wp_localize_script( 'my-script', 'my_options', $options );` \| `javascript console.log(my_options.option_name);`
传递翻译文本	`php wp_localize_script( 'my-script', 'my_translations', array( 'hello' => __( 'Hello', 'my-theme' ), 'goodbye' => __( 'Goodbye', 'my-theme' ) ) );` \| `javascript alert(my_translations.hello);`
传递用户信息	`php $user_data = array( 'id' => get_current_user_id(), 'username' => wp_get_current_user()->user_login ); wp_localize_script( 'my-script', 'my_user', $user_data );` \| `javascript console.log(my_user.username);`
传递动态数据 (例如 post ID)	`php wp_localize_script( 'my-script', 'my_post', array( 'id' => get_the_ID() ) );` \| `javascript console.log(my_post.id);`
传递 AJAX URL 和 nonce	`php wp_localize_script( 'my-script', 'my_ajax', array( 'url' => admin_url( 'admin-ajax.php' ), 'nonce' => wp_create_nonce( 'my_ajax_nonce' ) ) );` \| `javascript $.post( my_ajax.url, { action: 'my_action', security: my_ajax.nonce }, function( response ) { console.log( response ); } );`

7. 安全注意事项

永远不要传递敏感信息: 避免传递数据库凭据、API 密钥或任何其他敏感信息到前端。
使用 Nonce 进行 AJAX 请求: 使用 wp_create_nonce 生成 nonce 值，并在 AJAX 请求中使用它们来验证请求的真实性。在服务器端使用 check_ajax_referer 函数验证 nonce。
验证和转义数据: 在使用从前端接收到的数据之前，始终对其进行验证和转义，以防止安全漏洞，例如跨站脚本攻击 (XSS)。
小心处理用户输入: 永远不要信任用户输入。对用户输入进行清理和验证，以防止恶意代码注入。

8. 最佳实践

保持 JavaScript 对象名称简洁明了: 选择描述性但简短的 JavaScript 对象名称，以提高代码的可读性。
组织你的数据: 使用关联数组来组织你的 PHP 数据，使其易于在 JavaScript 中访问。
仅传递必要的数据: 避免传递不必要的数据到前端，以减少 JavaScript 文件的大小并提高性能。
在 wp_enqueue_scripts 钩子中调用 wp_localize_script: 确保在 wp_enqueue_scripts 钩子中调用 wp_localize_script，以便在加载 JavaScript 脚本之前传递数据。
使用条件加载: 仅在需要时才加载 JavaScript 脚本，以提高性能。可以使用 is_page()、is_single() 等条件函数来确定何时加载脚本。
避免全局变量污染：尽量将数据封装在你的对象中，避免创建过多的全局变量。

9. 调试技巧

使用浏览器的开发者工具: 使用浏览器的开发者工具来检查从 PHP 传递到 JavaScript 的数据。你可以在 "控制台" 或 "源代码" 面板中查看 my_script_vars 对象的内容。
使用 console.log() 语句: 在 JavaScript 代码中使用 console.log() 语句来输出变量的值，以便调试问题。
检查 WordPress 错误日志: 如果 wp_localize_script 没有按预期工作，请检查 WordPress 错误日志以获取任何错误消息。
确保句柄匹配: 确保在 wp_register_script、wp_enqueue_script 和 wp_localize_script 中使用的句柄 (handle) 完全匹配。

10. wp_add_inline_script的替代方案

虽然 wp_localize_script 是一个很好的选择，但 wp_add_inline_script 也可以用来注入变量。

wp_add_inline_script( string $handle, string $data, string $position = 'after' )

$handle: 已注册的 JavaScript 脚本的句柄。
$data: 要添加到脚本的 JavaScript 代码。
$position: 指定是将 $data 添加到脚本之前 (before) 还是之后 (after)。

wp_add_inline_script 的优点是它更灵活，允许你添加任何 JavaScript 代码。但是，它也更危险，因为它更容易引入错误。必须确保 $data 是有效的 JavaScript 代码，并且不会与其他脚本冲突。

示例:

<?php
function my_enqueue_scripts() {
    wp_register_script(
        'my-custom-script', // 句柄 (handle)
        get_template_directory_uri() . '/js/my-script.js', // 脚本的 URL
        array( 'jquery' ), // 依赖项 (jQuery)
        '1.0', // 版本号
        true // 在 footer 中加载
    );

    $ajax_url = admin_url( 'admin-ajax.php' );
    $nonce = wp_create_nonce( 'my_ajax_nonce' );

    $inline_script = "
        var my_ajax_url = '$ajax_url';
        var my_ajax_nonce = '$nonce';
    ";

    wp_add_inline_script( 'my-custom-script', $inline_script, 'before' );

    wp_enqueue_script( 'my-custom-script' );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );
?>

在这个例子中，我们使用 wp_add_inline_script 将 my_ajax_url 和 my_ajax_nonce 变量添加到 my-custom-script 脚本之前。在 JavaScript 代码中，我们可以直接访问这些变量。

选择哪个函数取决于你的具体需求。 如果你只需要传递一些简单的变量，那么 wp_localize_script 是一个不错的选择。如果你需要添加更复杂的 JavaScript 代码，那么 wp_add_inline_script 可能更适合你。但是，必须小心使用 wp_add_inline_script，以避免引入错误。

11. 总结

wp_localize_script 是一个强大且安全的方式，可以将 PHP 变量传递到你的 JavaScript 代码中。通过理解它的工作原理和遵循最佳实践，你可以构建动态且可维护的 WordPress 主题和插件。记住安全第一，永远不要传递敏感信息到前端。

发表回复 取消回复

发表回复取消回复