云策 WordPress 开发者社区

函数文档

wp_ajax_nopriv_heartbeat()

查看官方原文 ↗
💡 云策文档标注

概述

wp_ajax_nopriv_heartbeat() 是 WordPress 中处理未登录用户 Heartbeat API 的 AJAX 回调函数。它通过接收和发送数据，并应用相关过滤器与动作，来管理无权限环境下的心跳机制。

关键要点

  • 函数在用户未登录时运行，处理 Heartbeat API 的 AJAX 请求。
  • 接收并处理 POST 数据，包括 screen_id 和 data 参数，使用 sanitize_key() 和 wp_unslash() 进行安全处理。
  • 提供两个过滤器：heartbeat_nopriv_received（当有数据时）和 heartbeat_nopriv_send（当无数据时），用于修改响应。
  • 触发一个动作：heartbeat_nopriv_tick，允许替换传输机制（如长轮询）。
  • 在响应中添加服务器时间，并通过 wp_send_json() 返回 JSON 格式响应。

代码示例

function wp_ajax_nopriv_heartbeat() {
    $response = array();

    if ( ! empty( $_POST['screen_id'] ) ) {
        $screen_id = sanitize_key( $_POST['screen_id'] );
    } else {
        $screen_id = 'front';
    }

    if ( ! empty( $_POST['data'] ) ) {
        $data = wp_unslash( (array) $_POST['data'] );
        $response = apply_filters( 'heartbeat_nopriv_received', $response, $data, $screen_id );
    }

    $response = apply_filters( 'heartbeat_nopriv_send', $response, $screen_id );
    do_action( 'heartbeat_nopriv_tick', $response, $screen_id );
    $response['server_time'] = time();
    wp_send_json( $response );
}

注意事项

  • 确保在无权限环境中正确使用过滤器来定制响应，避免安全风险。
  • screen_id 默认为 'front'，需根据实际页面设置。
  • 函数自 WordPress 3.6.0 引入，兼容性需考虑。
📄 原文内容

Handles the Heartbeat API in the no-privilege context via AJAX .

Description

Runs when the user is not logged in.

Source

function wp_ajax_nopriv_heartbeat() {
	$response = array();

	// 'screen_id' is the same as $current_screen->id and the JS global 'pagenow'.
	if ( ! empty( $_POST['screen_id'] ) ) {
		$screen_id = sanitize_key( $_POST['screen_id'] );
	} else {
		$screen_id = 'front';
	}

	if ( ! empty( $_POST['data'] ) ) {
		$data = wp_unslash( (array) $_POST['data'] );

		/**
		 * Filters Heartbeat Ajax response in no-privilege environments.
		 *
		 * @since 3.6.0
		 *
		 * @param array  $response  The no-priv Heartbeat response.
		 * @param array  $data      The $_POST data sent.
		 * @param string $screen_id The screen ID.
		 */
		$response = apply_filters( 'heartbeat_nopriv_received', $response, $data, $screen_id );
	}

	/**
	 * Filters Heartbeat Ajax response in no-privilege environments when no data is passed.
	 *
	 * @since 3.6.0
	 *
	 * @param array  $response  The no-priv Heartbeat response.
	 * @param string $screen_id The screen ID.
	 */
	$response = apply_filters( 'heartbeat_nopriv_send', $response, $screen_id );

	/**
	 * Fires when Heartbeat ticks in no-privilege environments.
	 *
	 * Allows the transport to be easily replaced with long-polling.
	 *
	 * @since 3.6.0
	 *
	 * @param array  $response  The no-priv Heartbeat response.
	 * @param string $screen_id The screen ID.
	 */
	do_action( 'heartbeat_nopriv_tick', $response, $screen_id );

	// Send the current time according to the server.
	$response['server_time'] = time();

	wp_send_json( $response );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘heartbeat_nopriv_received’, array $response, array $data, string $screen_id )

Filters Heartbeat Ajax response in no-privilege environments.

apply_filters( ‘heartbeat_nopriv_send’, array $response, string $screen_id )

Filters Heartbeat Ajax response in no-privilege environments when no data is passed.

do_action( ‘heartbeat_nopriv_tick’, array $response, string $screen_id )

Fires when Heartbeat ticks in no-privilege environments.

Uses Description
wp_send_json()wp-includes/functions.php

Sends a JSON response back to an Ajax request.
wp_unslash()wp-includes/formatting.php

Removes slashes from a string or recursively removes slashes from strings within an array.
sanitize_key()wp-includes/formatting.php

Sanitizes a string key.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.

Show 3 moreShow less

Changelog

Version Description
3.6.0 Introduced.