深入理解 WordPress `wp_ajax_{action}` 钩子的源码：如何处理 AJAX 请求并返回响应。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

WordPress AJAX 讲座：深入挖掘 `wp_ajax_{action}` 的奥秘

大家好，我是你们今天的WordPress探险向导。今天，咱们要一起深入WordPress的腹地，扒一扒wp_ajax_{action}这个钩子的底裤，看看它到底是怎么处理AJAX请求，又是怎么把响应返回给我们的。

我们都喜欢用AJAX，它能让我们的网页“动”起来，不用刷新整个页面就能更新部分内容，用户体验那是蹭蹭往上涨。WordPress当然也支持AJAX，而wp_ajax_{action}就是它的核心武器之一。

一、AJAX，你好！先来点基础知识热热身

在深入WordPress之前，咱们先复习一下AJAX的基础知识。毕竟，磨刀不误砍柴工嘛。

AJAX是啥？ Asynchronous JavaScript and XML，翻译过来就是“异步 JavaScript 和 XML”。实际上，现在更多用JSON来替代XML。
AJAX能干啥？ 简单来说，就是允许网页在不重新加载整个页面的情况下，与服务器交换数据并更新部分网页内容。
AJAX的流程是啥？
1. 用户在页面上触发一个事件 (比如点击按钮)。
2. JavaScript 创建一个 XMLHttpRequest 对象 (现在更多用 fetch API 或者 jQuery 的 $.ajax)。
3. XMLHttpRequest 对象向服务器发送请求。
4. 服务器处理请求。
5. 服务器返回响应。
6. JavaScript 处理响应，并更新页面内容。

二、WordPress AJAX：admin-ajax.php 这位老朋友

在WordPress中，所有的AJAX请求都会经过一个特殊的“中转站”：wp-admin/admin-ajax.php。这个文件就像一个总调度室，负责接收请求，然后根据请求中的action参数，找到对应的处理函数。

为啥要用 admin-ajax.php？

安全： WordPress 可以通过它来验证用户的权限，确保只有有权限的人才能执行某些操作。
统一入口： 所有的 AJAX 请求都通过一个入口，方便管理和维护。
方便： WordPress 提供了一套方便的API，让开发者可以轻松地处理 AJAX 请求。

三、wp_ajax_{action}：主角登场！

wp_ajax_{action} 和 wp_ajax_nopriv_{action} 是两个非常重要的钩子，它们分别用于处理已登录用户和未登录用户的 AJAX 请求。

wp_ajax_{action}： 用于处理已登录用户的 AJAX 请求。其中 {action} 是一个占位符，你需要用你自定义的动作名称来替换它。
wp_ajax_nopriv_{action}： 用于处理未登录用户的 AJAX 请求。同样，{action} 也是一个占位符，你需要用你自定义的动作名称来替换它。

举个栗子：

假设我们想创建一个 AJAX 请求，用于更新用户的个人资料。我们可以定义一个名为 update_profile 的动作。

对于已登录用户，我们需要使用 wp_ajax_update_profile 钩子。
对于未登录用户，我们需要使用 wp_ajax_nopriv_update_profile 钩子。

四、代码实战：一步一步教你玩转 wp_ajax_{action}

接下来，咱们通过一个实际的例子，来演示如何使用 wp_ajax_{action} 处理 AJAX 请求并返回响应。

场景： 用户点击一个按钮，向服务器发送一个请求，服务器返回一句问候语。

步骤1：定义 AJAX 动作

首先，在你的插件或主题的 functions.php 文件中，定义 AJAX 动作的处理函数。

<?php

add_action( 'wp_ajax_my_ajax_action', 'my_ajax_handler' );
add_action( 'wp_ajax_nopriv_my_ajax_action', 'my_ajax_handler' ); // 如果允许未登录用户访问

function my_ajax_handler() {
  // 1. 安全检查 (Nonce 验证)
  check_ajax_referer( 'my_ajax_nonce', 'security' );

  // 2. 获取数据 (可选)
  $name = isset( $_POST['name'] ) ? sanitize_text_field( $_POST['name'] ) : 'World';

  // 3. 处理数据 (核心逻辑)
  $greeting = 'Hello, ' . $name . '!';

  // 4. 返回响应
  $response = array(
    'success' => true,
    'data'    => $greeting,
  );

  wp_send_json( $response );

  // **重要：** 一定要 `wp_die()` 退出，否则 WordPress 会继续执行，导致返回不完整的数据。
  wp_die();
}

?>

代码解释：

add_action( 'wp_ajax_my_ajax_action', 'my_ajax_handler' ); 和 add_action( 'wp_ajax_nopriv_my_ajax_action', 'my_ajax_handler' );：
- 这两行代码将 my_ajax_action 动作与 my_ajax_handler 函数关联起来。
- wp_ajax_my_ajax_action 用于处理已登录用户的请求。
- wp_ajax_nopriv_my_ajax_action 用于处理未登录用户的请求。如果你的action只允许登录用户访问，那么可以省略wp_ajax_nopriv_my_ajax_action。
function my_ajax_handler() { ... }：
- 这是 AJAX 动作的处理函数。
- 它负责接收请求，处理数据，并返回响应。
check_ajax_referer( 'my_ajax_nonce', 'security' );：
- 这是一个非常重要的安全检查。
- 它用于验证 AJAX 请求的来源，防止跨站请求伪造 (CSRF) 攻击。
- my_ajax_nonce 是你定义的 nonce 名称。
- security 是前端传递 nonce 值的字段名，在前端代码中要对应.
$name = isset( $_POST['name'] ) ? sanitize_text_field( $_POST['name'] ) : 'World';：
- 这行代码从 $_POST 数组中获取 name 参数。
- sanitize_text_field() 函数用于对输入的数据进行清理，防止 XSS 攻击。
- 如果 name 参数不存在，则默认值为 'World'。
$greeting = 'Hello, ' . $name . '!';：
- 这行代码生成问候语。
$response = array( 'success' => true, 'data' => $greeting, );：
- 这行代码创建一个包含响应数据的数组。
- success 字段表示请求是否成功。
- data 字段包含实际的响应数据。
wp_send_json( $response );：
- 这是 WordPress 提供的函数，用于将响应数据编码为 JSON 格式并发送回客户端。
wp_die();：
- 务必记住！ 在 AJAX 处理函数结束时，一定要调用 wp_die() 函数。
- wp_die() 函数会立即停止 WordPress 的执行，防止返回不完整的数据。

步骤2：前端代码

接下来，我们需要编写前端代码，用于发送 AJAX 请求并处理响应。这里以JQuery为例，如果你的主题或者插件没有加载JQuery，请先加载JQuery。

<!DOCTYPE html>
<html>
<head>
  <title>WordPress AJAX Example</title>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
  <script>
    $(document).ready(function() {
      $('#my-button').click(function() {
        // 1. 创建数据对象
        var data = {
          'action': 'my_ajax_action', // AJAX 动作名称
          'name': $('#my-name').val(), // 获取输入框中的名字
          'security': '<?php echo wp_create_nonce( 'my_ajax_nonce' ); ?>' // 创建 Nonce
        };

        // 2. 发送 AJAX 请求
        $.ajax({
          url: '<?php echo admin_url( 'admin-ajax.php' ); ?>', // admin-ajax.php 的 URL
          type: 'POST', // 请求方法
          data: data, // 请求数据
          dataType: 'json', // 返回的数据类型
          success: function(response) { // 请求成功的回调函数
            if (response.success) {
              $('#my-message').text(response.data); // 显示问候语
            } else {
              alert('请求失败：' + response.data); // 显示错误信息
            }
          },
          error: function(jqXHR, textStatus, errorThrown) { // 请求失败的回调函数
            console.log('AJAX 请求失败：' + textStatus + ' (' + errorThrown + ')');
          }
        });
      });
    });
  </script>
</head>
<body>
  <input type="text" id="my-name" placeholder="请输入你的名字">
  <button id="my-button">发送问候</button>
  <p id="my-message"></p>
</body>
</html>

代码解释：

$('#my-button').click(function() { ... });：
- 这行代码监听 id 为 my-button 的按钮的点击事件。
- 当按钮被点击时，会执行回调函数。
var data = { ... };：
- 这行代码创建一个包含 AJAX 请求数据的对象。
- action: 必须设置为你在 add_action 中定义的动作名称 (my_ajax_action)。
- name: 获取输入框中的名字。
- security: 使用 wp_create_nonce( 'my_ajax_nonce' ) 函数创建一个 nonce，并将其传递给服务器。 重要： 前后端 nonce 的名称(my_ajax_nonce)要保持一致。
$.ajax({ ... });：
- 这行代码使用 jQuery 的 $.ajax 函数发送 AJAX 请求。
- url: 设置为 admin-ajax.php 的 URL。使用 admin_url( 'admin-ajax.php' ) 函数可以获取 admin-ajax.php 的完整 URL。
- type: 设置为 POST，表示使用 POST 方法发送请求。
- data: 设置为包含请求数据的对象。
- dataType: 设置为 json，表示期望服务器返回 JSON 格式的数据。
- success: 设置为请求成功的回调函数。
- error: 设置为请求失败的回调函数。
success: function(response) { ... }：
- 这行代码处理服务器返回的响应。
- 如果 response.success 为 true，表示请求成功，将 response.data 显示在 id 为 my-message 的段落中。
- 如果 response.success 为 false，表示请求失败，显示错误信息。
error: function(jqXHR, textStatus, errorThrown) { ... }：
- 这行代码处理 AJAX 请求失败的情况。
- 它会将错误信息输出到控制台。

步骤3：将前端代码添加到 WordPress 页面

将上面的 HTML 代码添加到你的 WordPress 页面或文章中。你可以使用 HTML 编辑器或者代码块来实现。注意，确保你的主题或插件已经加载了 jQuery 库。

五、wp_localize_script()：优雅地传递数据

虽然直接在 JavaScript 代码中嵌入 PHP 代码可以工作，但这并不是最佳实践。更好的方法是使用 wp_localize_script() 函数将 PHP 数据传递给 JavaScript。

wp_localize_script() 的用法：

<?php

add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

function my_enqueue_scripts() {
  // 1. 注册脚本
  wp_register_script( 'my-script', get_template_directory_uri() . '/js/my-script.js', array( 'jquery' ), '1.0', true );

  // 2. 本地化脚本
  wp_localize_script( 'my-script', 'my_ajax_object', array(
    'ajax_url' => admin_url( 'admin-ajax.php' ),
    'nonce'    => wp_create_nonce( 'my_ajax_nonce' ),
  ) );

  // 3. 加载脚本
  wp_enqueue_script( 'my-script' );
}

?>

代码解释：

wp_register_script()：
- 注册你的 JavaScript 脚本。
- my-script: 脚本的句柄 (handle)。
- get_template_directory_uri() . '/js/my-script.js': 脚本的 URL。
- array( 'jquery' ): 脚本的依赖项 (这里依赖 jQuery)。
- '1.0': 脚本的版本号。
- true: 将脚本加载到页面底部。
wp_localize_script()：
- 将 PHP 数据传递给 JavaScript 脚本。
- my-script: 脚本的句柄 (必须与 wp_register_script() 中使用的句柄相同)。
- my_ajax_object: JavaScript 对象的名称 (你可以在 JavaScript 代码中使用 my_ajax_object.ajax_url 和 my_ajax_object.nonce 来访问数据)。
- array( ... ): 包含要传递的数据的数组。
  - ajax_url: admin-ajax.php 的 URL。
  - nonce: 使用 wp_create_nonce( 'my_ajax_nonce' ) 函数创建的 nonce。
wp_enqueue_script()：
- 加载你的 JavaScript 脚本。

修改后的 JavaScript 代码：

$(document).ready(function() {
  $('#my-button').click(function() {
    var data = {
      'action': 'my_ajax_action',
      'name': $('#my-name').val(),
      'security': my_ajax_object.nonce // 从 my_ajax_object 对象中获取 nonce
    };

    $.ajax({
      url: my_ajax_object.ajax_url, // 从 my_ajax_object 对象中获取 AJAX URL
      type: 'POST',
      data: data,
      dataType: 'json',
      success: function(response) {
        if (response.success) {
          $('#my-message').text(response.data);
        } else {
          alert('请求失败：' + response.data);
        }
      },
      error: function(jqXHR, textStatus, errorThrown) {
        console.log('AJAX 请求失败：' + textStatus + ' (' + errorThrown + ')');
      }
    });
  });
});

六、总结：wp_ajax_{action} 的核心要点

为了方便大家记忆，我把 wp_ajax_{action} 的核心要点整理成一个表格：

步骤	说明	代码示例
1. 定义动作	使用 `add_action()` 函数将 AJAX 动作与处理函数关联起来。对于已登录用户使用 `wp_ajax_{action}`，对于未登录用户使用 `wp_ajax_nopriv_{action}`。	`add_action( 'wp_ajax_my_ajax_action', 'my_ajax_handler' );` `add_action( 'wp_ajax_nopriv_my_ajax_action', 'my_ajax_handler' );`
2. 处理函数	创建 AJAX 动作的处理函数。在函数中，你需要：进行安全检查 (Nonce 验证)。获取和处理数据。返回响应 (使用 `wp_send_json()` 函数)。使用 `wp_die()` 函数退出。	`php function my_ajax_handler() { check_ajax_referer( 'my_ajax_nonce', 'security' ); $name = isset( $_POST['name'] ) ? sanitize_text_field( $_POST['name'] ) : 'World'; $greeting = 'Hello, ' . $name . '!'; $response = array( 'success' => true, 'data' => $greeting, ); wp_send_json( $response ); wp_die(); }`
3. 前端代码	编写前端代码，用于发送 AJAX 请求并处理响应。在前端代码中，你需要：创建一个包含 AJAX 请求数据的对象 (包括 `action` 和 nonce)。使用 `$.ajax()` 函数发送 AJAX 请求。 * 处理服务器返回的响应。	`javascript var data = { 'action': 'my_ajax_action', 'name': $('#my-name').val(), 'security': my_ajax_object.nonce }; $.ajax({ url: my_ajax_object.ajax_url, type: 'POST', data: data, dataType: 'json', success: function(response) { ... }, error: function(jqXHR, textStatus, errorThrown) { ... } });`
4. 传递数据	使用 `wp_localize_script()` 函数将 PHP 数据传递给 JavaScript 代码。这样可以避免在 JavaScript 代码中直接嵌入 PHP 代码。	`php wp_localize_script( 'my-script', 'my_ajax_object', array( 'ajax_url' => admin_url( 'admin-ajax.php' ), 'nonce' => wp_create_nonce( 'my_ajax_nonce' ), ) );`

七、常见问题与注意事项

Nonce 验证失败： 确保前后端 nonce 的名称一致，并且在发送 AJAX 请求时包含了正确的 nonce 值。
admin-ajax.php 返回 400 错误： 检查你的 AJAX 请求是否包含了 action 参数，并且 action 参数的值是否与你在 add_action() 中定义的动作名称一致。
AJAX 请求没有响应： 确保你的 AJAX 处理函数中包含了 wp_die() 函数，并且在函数结束时调用了它。
安全问题： 始终对用户输入的数据进行清理和验证，防止 XSS 和 SQL 注入攻击。

八、进阶技巧

使用 wp_parse_args() 函数处理请求参数： wp_parse_args() 函数可以将请求参数合并到一个数组中，并设置默认值。
使用 WP_REST_Request 对象： WordPress REST API 提供了 WP_REST_Request 对象，可以更方便地处理 AJAX 请求。

总结：

wp_ajax_{action} 钩子是 WordPress 中处理 AJAX 请求的核心机制。掌握它，你就可以轻松地创建各种动态的 WordPress 插件和主题。记住，安全第一，代码规范，才能写出高质量的 WordPress 代码。

今天的讲座就到这里，希望大家有所收获！祝大家编程愉快！

WordPress AJAX 讲座：深入挖掘 wp_ajax_{action} 的奥秘

发表回复 取消回复

WordPress AJAX 讲座：深入挖掘 `wp_ajax_{action}` 的奥秘

发表回复取消回复