发布于 由admin

深入理解 WordPress `wp_ajax_{action}` 钩子的源码：如何通过它注册一个 AJAX 处理函数。

老铁们，早上好！ 今天咱们聊聊 WordPress 里一个非常酷炫的东西：wp_ajax_{action} 钩子。 很多人用 AJAX，但真正理解 wp_ajax_{action} 的，可能还真不多。今天咱们就来扒一扒它的源码，看看它是怎么工作的，以及如何用它来注册 AJAX 处理函数，让你的 WordPress 站点更上一层楼。

什么是 AJAX？

在深入 wp_ajax_{action} 之前，先简单回顾一下 AJAX。 AJAX（Asynchronous JavaScript and XML） 是一种创建快速动态网页的技术。 通过在后台与服务器进行少量数据交换，AJAX 可以使网页实现异步更新，这意味着可以在不重新加载整个网页的情况下，对网页的某部分进行更新。

WordPress 中的 AJAX

WordPress 默认情况下是同步的，每次用户交互都需要重新加载页面。 这在用户体验上是很糟糕的。 AJAX 的引入，让 WordPress 可以实现局部刷新，提升用户体验。 WordPress 提供了一套机制来处理 AJAX 请求，其中最重要的就是 wp_ajax_{action} 钩子。

wp_ajax_{action} 钩子：主角登场

wp_ajax_{action} 钩子是 WordPress 提供的一个用于处理 AJAX 请求的核心机制。 它允许你注册一个函数，当 WordPress 接收到一个特定的 AJAX 请求时，就会执行这个函数。 action 部分是你自定义的字符串，用于标识不同的 AJAX 请求。

源码剖析：wp-includes/ajax-actions.php

要理解 wp_ajax_{action} 的工作原理，我们需要深入到 WordPress 的核心文件 wp-includes/ajax-actions.php 中。 这个文件负责处理所有的 AJAX 请求。

让我们从 wp_ajax_action() 函数开始看起。这个函数是 AJAX 处理的核心入口点：

function wp_ajax_action( $action = '' ) {
    if ( empty( $action ) ) {
        $action = $_REQUEST['action'] ?? '';
    }

    /**
     * Fires authenticated Ajax actions for logged-in users.
     *
     * The dynamic portion of the hook name, `$action`, refers to the name
     * of the Ajax action callback to fire.
     *
     * @since 2.1.0
     */
    do_action( 'wp_ajax_' . $action );

    /**
     * Fires authenticated Ajax actions for logged-out users.
     *
     * The dynamic portion of the hook name, `$action`, refers to the name
     * of the Ajax action callback to fire.
     *
     * @since 2.8.0
     */
    do_action( 'wp_ajax_nopriv_' . $action );

    wp_die();
}

这段代码做了几件事：

  1. 获取 action 参数： 首先，它尝试从 $_REQUEST 数组中获取名为 action 的参数。 这个参数是 AJAX 请求中用来指定要执行哪个动作的关键。

  2. 触发钩子： 接下来，它会触发两个钩子：wp_ajax_{action} 和 wp_ajax_nopriv_{action}。

    • wp_ajax_{action}： 这个钩子是为已登录的用户准备的。 如果用户已登录，WordPress 会触发这个钩子，并执行所有绑定到这个钩子的函数。
    • wp_ajax_nopriv_{action}： 这个钩子是为未登录的用户准备的。 如果用户未登录，WordPress 会触发这个钩子，并执行所有绑定到这个钩子的函数。

  3. wp_die()： 最后，它调用 wp_die() 函数。 这个函数会终止 WordPress 的执行，并返回一个响应。 在 AJAX 请求中，通常会返回一个 JSON 格式的数据。

注册 AJAX 处理函数：实战演练

现在我们知道了 wp_ajax_{action} 的工作原理，接下来看看如何使用它来注册一个 AJAX 处理函数。

步骤 1：定义 AJAX 处理函数

首先，我们需要定义一个函数来处理 AJAX 请求。 这个函数会接收一些参数（通常通过 $_POST 传递），执行一些操作，然后返回一个结果。

function my_ajax_handler() {
  // 检查 nonce，防止 CSRF 攻击
  check_ajax_referer( 'my_ajax_nonce', 'security' );

  // 获取传递的数据
  $data = $_POST['data'];

  // 进行一些处理
  $result = '你发送的数据是：' . esc_html( $data );

  // 返回 JSON 格式的响应
  wp_send_json_success( array( 'message' => $result ) );

  // 如果发生错误，可以使用 wp_send_json_error()
  // wp_send_json_error( array( 'message' => '发生错误！' ) );
}

在这个例子中：

  • check_ajax_referer( 'my_ajax_nonce', 'security' )： 这是一个非常重要的安全措施。 它会检查 AJAX 请求中是否包含正确的 nonce（一次性使用的令牌），以防止跨站请求伪造（CSRF）攻击。 稍后我们会介绍如何生成这个 nonce。
  • $_POST['data']： 我们假设 AJAX 请求通过 POST 方法传递了一个名为 data 的参数。
  • esc_html( $data )： 这是一个安全函数，用于转义 HTML 实体，防止 XSS 攻击。
  • wp_send_json_success( array( 'message' => $result ) )： 这个函数会返回一个 JSON 格式的响应，其中包含一个 success 字段（值为 true）和一个 data 字段（包含我们的处理结果）。
  • wp_send_json_error( array( 'message' => '发生错误！' ) )： 如果发生错误，可以使用这个函数返回一个 JSON 格式的错误响应，其中包含一个 success 字段（值为 false）和一个 data 字段（包含错误信息）。

步骤 2：注册 AJAX 处理函数

接下来，我们需要将这个函数注册到 wp_ajax_{action} 钩子上。

add_action( 'wp_ajax_my_action', 'my_ajax_handler' );
add_action( 'wp_ajax_nopriv_my_action', 'my_ajax_handler' );

这两行代码做了两件事：

  • add_action( 'wp_ajax_my_action', 'my_ajax_handler' )： 将 my_ajax_handler 函数注册到 wp_ajax_my_action 钩子上。 这意味着，当 WordPress 接收到一个 action 参数值为 my_action 的 AJAX 请求，并且用户已登录时，就会执行 my_ajax_handler 函数。
  • add_action( 'wp_ajax_nopriv_my_action', 'my_ajax_handler' )： 将 my_ajax_handler 函数注册到 wp_ajax_nopriv_my_action 钩子上。 这意味着，当 WordPress 接收到一个 action 参数值为 my_action 的 AJAX 请求，并且用户未登录时，也会执行 my_ajax_handler 函数。

注意： 你需要将这段代码添加到你的主题的 functions.php 文件中，或者添加到你的插件的主文件中。

步骤 3：生成 Nonce（安全令牌）

为了防止 CSRF 攻击，我们需要在 AJAX 请求中包含一个 nonce。 可以使用 wp_create_nonce() 函数来生成 nonce。

$nonce = wp_create_nonce( 'my_ajax_nonce' );

这段代码会生成一个 nonce，并将其存储在 $nonce 变量中。 你需要将这个 nonce 传递给你的 JavaScript 代码。

步骤 4：编写 JavaScript 代码

最后，我们需要编写 JavaScript 代码来发送 AJAX 请求。

jQuery(document).ready(function($) {
  $('#my_button').click(function() {
    var data = {
      'action': 'my_action',
      'data': 'Hello, AJAX!',
      'security': my_ajax_object.ajax_nonce  // 从 WordPress 传递过来的 nonce
    };

    $.post(my_ajax_object.ajax_url, data, function(response) {
      if (response.success) {
        alert(response.data.message);
      } else {
        alert('Error: ' + response.data.message);
      }
    });
  });
});

在这个例子中：

  • $('#my_button').click(function() { ... })： 当点击一个 ID 为 my_button 的按钮时，会执行这段代码。
  • var data = { ... }： 创建一个包含 AJAX 请求参数的对象。
    • action: 设置为 my_action，这是我们之前在 add_action() 函数中使用的动作名称。
    • data: 设置为要传递的数据。
    • security: 设置为我们之前生成的 nonce。 注意： 这里我们使用了一个名为 my_ajax_object 的 JavaScript 对象来存储 ajax_url 和 ajax_nonce。 我们需要在 WordPress 中将这些变量传递给 JavaScript。
  • $.post(my_ajax_object.ajax_url, data, function(response) { ... })： 使用 jQuery 的 $.post() 函数发送 AJAX 请求。
    • my_ajax_object.ajax_url: 是 WordPress 的 AJAX 处理 URL。 我们需要在 WordPress 中将这个 URL 传递给 JavaScript。
    • data: 是我们之前创建的包含 AJAX 请求参数的对象。
    • function(response) { ... }: 是 AJAX 请求完成后的回调函数。 它会接收一个 response 对象，其中包含服务器返回的数据。 我们检查 response.success 字段，如果为 true，则显示成功消息；否则，显示错误消息。

步骤 5：在 WordPress 中传递变量给 JavaScript

我们需要在 WordPress 中将 ajax_url 和 ajax_nonce 传递给 JavaScript。 可以使用 wp_localize_script() 函数来实现。

function my_enqueue_scripts() {
  wp_enqueue_script( 'my_ajax_script', get_template_directory_uri() . '/js/my_ajax_script.js', array( 'jquery' ), '1.0', true );

  wp_localize_script( 'my_ajax_script', 'my_ajax_object', array(
    'ajax_url' => admin_url( 'admin-ajax.php' ),
    'ajax_nonce' => wp_create_nonce( 'my_ajax_nonce' )
  ));
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

这段代码做了几件事：

  • wp_enqueue_script( 'my_ajax_script', get_template_directory_uri() . '/js/my_ajax_script.js', array( 'jquery' ), '1.0', true )： 注册并加载名为 my_ajax_script 的 JavaScript 文件。 确保你的 JavaScript 文件路径是正确的。
  • wp_localize_script( 'my_ajax_script', 'my_ajax_object', array( ... ))： 将一些变量传递给 JavaScript。
    • 'my_ajax_script': 是我们要传递变量的 JavaScript 文件的句柄。
    • 'my_ajax_object': 是我们将要创建的 JavaScript 对象的名称。
    • array( ... ): 是一个包含我们要传递的变量的数组。
      • 'ajax_url' => admin_url( 'admin-ajax.php' ): 将 WordPress 的 AJAX 处理 URL 传递给 JavaScript。 admin_url( 'admin-ajax.php' ) 会返回 WordPress 的 AJAX 处理 URL。
      • 'ajax_nonce' => wp_create_nonce( 'my_ajax_nonce' ): 生成并传递 nonce 给 JavaScript。

完整示例

让我们把所有代码片段组合起来，创建一个完整的示例。

functions.php (或者插件主文件)

<?php

// AJAX 处理函数
function my_ajax_handler() {
  // 检查 nonce，防止 CSRF 攻击
  check_ajax_referer( 'my_ajax_nonce', 'security' );

  // 获取传递的数据
  $data = $_POST['data'];

  // 进行一些处理
  $result = '你发送的数据是：' . esc_html( $data );

  // 返回 JSON 格式的响应
  wp_send_json_success( array( 'message' => $result ) );

  // 如果发生错误，可以使用 wp_send_json_error()
  // wp_send_json_error( array( 'message' => '发生错误！' ) );
}

// 注册 AJAX 处理函数
add_action( 'wp_ajax_my_action', 'my_ajax_handler' );
add_action( 'wp_ajax_nopriv_my_action', 'my_ajax_handler' );

// 加载 JavaScript 文件并传递变量
function my_enqueue_scripts() {
  wp_enqueue_script( 'my_ajax_script', get_template_directory_uri() . '/js/my_ajax_script.js', array( 'jquery' ), '1.0', true );

  wp_localize_script( 'my_ajax_script', 'my_ajax_object', array(
    'ajax_url' => admin_url( 'admin-ajax.php' ),
    'ajax_nonce' => wp_create_nonce( 'my_ajax_nonce' )
  ));
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

?>

js/my_ajax_script.js

jQuery(document).ready(function($) {
  $('#my_button').click(function() {
    var data = {
      'action': 'my_action',
      'data': 'Hello, AJAX!',
      'security': my_ajax_object.ajax_nonce  // 从 WordPress 传递过来的 nonce
    };

    $.post(my_ajax_object.ajax_url, data, function(response) {
      if (response.success) {
        alert(response.data.message);
      } else {
        alert('Error: ' + response.data.message);
      }
    });
  });
});

HTML (例如：在你的主题的页面或文章中)

<button id="my_button">点击我，发送 AJAX 请求！</button>

总结

wp_ajax_{action} 钩子是 WordPress 中处理 AJAX 请求的强大工具。 通过理解其工作原理并遵循上述步骤，你可以轻松地注册 AJAX 处理函数，并为你的 WordPress 站点添加动态功能。 记住，安全性非常重要，一定要使用 check_ajax_referer() 函数来防止 CSRF 攻击。

表格总结关键步骤

步骤 描述 代码示例 重要性
1 定义 AJAX 处理函数 function my_ajax_handler() { ... } 核心逻辑
2 注册 AJAX 处理函数 add_action( 'wp_ajax_my_action', 'my_ajax_handler' ); add_action( 'wp_ajax_nopriv_my_action', 'my_ajax_handler' ); 将函数与 AJAX 请求关联
3 生成 Nonce $nonce = wp_create_nonce( 'my_ajax_nonce' ); 安全性
4 编写 JavaScript 代码 $.post(my_ajax_object.ajax_url, data, function(response) { ... }); 发送 AJAX 请求和处理响应
5 传递变量给 JavaScript wp_localize_script( 'my_ajax_script', 'my_ajax_object', array( 'ajax_url' => admin_url( 'admin-ajax.php' ), 'ajax_nonce' => wp_create_nonce( 'my_ajax_nonce' ) ) ); 将 AJAX URL 和 Nonce 传递给 JavaScript

希望今天的讲座对大家有所帮助。 掌握 wp_ajax_{action} 钩子，你就能在 WordPress 开发中如鱼得水，创造出更棒的网站！ 记住，多练习，多实践，你也能成为 AJAX 大神！ 下课！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注