wp_send_json_success()

💡 云策文档标注

概述

wp_send_json_success() 函数用于向 Ajax 请求发送一个表示成功的 JSON 响应。它自动构建包含 success 键的响应数组，并可选择性地包含数据、HTTP 状态码和 JSON 编码选项。

关键要点

函数用于处理 Ajax 请求的成功响应，确保返回的 JSON 对象始终包含 success: true。
接受三个可选参数：$value（要编码的数据，默认为 null）、$status_code（HTTP 状态码，默认为 null）和 $flags（json_encode() 选项，默认为 0）。
如果提供了 $value，它将被编码为 data 键的值；否则响应仅包含 success 键。
内部调用 wp_send_json() 来输出 JSON 并终止脚本执行。
广泛用于 WordPress 核心的 Ajax 处理函数中，如插件激活、主题安装、健康检查等场景。

代码示例

// 基本用法：发送成功响应，无额外数据
wp_send_json_success();

// 发送包含数据的成功响应
$data = array('name' => 'Andrew', 'call' => 'From API');
wp_send_json_success($data, 200);

// 函数源码示例
function wp_send_json_success( $value = null, $status_code = null, $flags = 0 ) {
    $response = array( 'success' => true );
    if ( isset( $value ) ) {
        $response['data'] = $value;
    }
    wp_send_json( $response, $status_code, $flags );
}

注意事项

调用此函数后，脚本将自动终止（通过 wp_send_json() 的 die() 调用），确保不会输出额外内容。
参数 $flags 从 WordPress 5.6.0 开始引入，用于传递 json_encode() 的选项，如 JSON_PRETTY_PRINT。
在 Ajax 处理程序中应优先使用此函数而非直接输出 JSON，以保持响应格式一致性和安全性。

📄 原文内容

Sends a JSON response back to an Ajax request, indicating success.

Parameters

$valuemixedoptional: Data to encode as JSON, then print and die.

Default:null
$status_codeintoptional: The HTTP status code to output.

Default:null
$flagsintoptional: Options to be passed to json_encode(). Default 0.

More Information

The response object will always have a success key with the value true. If anything is passed to the function it will be encoded as the value for a data key.

Example arrays such as the following are converted to JSON:

$response = array( 'success' => true );                   //if $data is empty
$response = array( 'success' => true, 'data' => $data );  //if $data is set

Source

function wp_send_json_success( $value = null, $status_code = null, $flags = 0 ) {
	$response = array( 'success' => true );

	if ( isset( $value ) ) {
		$response['data'] = $value;
	}

	wp_send_json( $response, $status_code, $flags );
}

View all references View on Trac View on GitHub

Uses	Description
wp_send_json()`wp-includes/functions.php`	Sends a JSON response back to an Ajax request.

Used by	Description
WP_Plugin_Dependencies::check_plugin_dependencies_during_ajax()`wp-includes/class-wp-plugin-dependencies.php`	Checks plugin dependencies after a plugin is installed via AJAX.
wp_ajax_activate_plugin()`wp-admin/includes/ajax-actions.php`	Handles activating a plugin via AJAX.
locate_block_template()`wp-includes/block-template.php`	Finds a block template with equal or higher specificity than a given PHP template file.
wp_ajax_send_password_reset()`wp-admin/includes/ajax-actions.php`	Handles sending a password reset link via AJAX.
wp_ajax_nopriv_generate_password()`wp-admin/includes/ajax-actions.php`	Handles generating a password in the no-privilege context via AJAX.
wp_ajax_toggle_auto_updates()`wp-admin/includes/ajax-actions.php`	Handles enabling or disable plugin and theme auto-updates via AJAX.
wp_ajax_media_create_image_subsizes()`wp-admin/includes/ajax-actions.php`	Handles creating missing image sub-sizes for just uploaded images via AJAX.
wp_ajax_health_check_get_sizes()`wp-admin/includes/ajax-actions.php`	Handles site health check to get directories and database sizes via AJAX.
wp_ajax_health_check_dotorg_communication()`wp-admin/includes/ajax-actions.php`	Handles site health checks on server communication via AJAX.
wp_ajax_health_check_background_updates()`wp-admin/includes/ajax-actions.php`	Handles site health checks on background updates via AJAX.
wp_ajax_health_check_loopback_requests()`wp-admin/includes/ajax-actions.php`	Handles site health checks on loopback requests via AJAX.
wp_ajax_health_check_site_status_result()`wp-admin/includes/ajax-actions.php`	Handles site health check to update the result status via AJAX.
wp_ajax_wp_privacy_export_personal_data()`wp-admin/includes/ajax-actions.php`	Handles exporting a user’s personal data via AJAX.
wp_ajax_wp_privacy_erase_personal_data()`wp-admin/includes/ajax-actions.php`	Handles erasing personal data via AJAX.
WP_Customize_Manager::handle_load_themes_request()`wp-includes/class-wp-customize-manager.php`	Loads themes into the theme browsing/installation UI.
WP_Customize_Manager::handle_override_changeset_lock_request()`wp-includes/class-wp-customize-manager.php`	Removes changeset lock when take over request is sent via Ajax.
WP_Customize_Manager::handle_dismiss_autosave_or_lock_request()`wp-includes/class-wp-customize-manager.php`	Deletes a given auto-draft changeset or the autosave revision for a given changeset or delete changeset lock.
WP_Customize_Manager::handle_changeset_trash_request()`wp-includes/class-wp-customize-manager.php`	Handles request to trash a changeset.
wp_ajax_edit_theme_plugin_file()`wp-admin/includes/ajax-actions.php`	Handles editing a theme or plugin file via AJAX.
wp_ajax_get_community_events()`wp-admin/includes/ajax-actions.php`	Handles Ajax requests for community events
WP_Customize_Nav_Menus::ajax_insert_auto_draft_post()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for adding a new auto-draft post.
wp_ajax_search_install_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins to install via AJAX.
wp_ajax_delete_plugin()`wp-admin/includes/ajax-actions.php`	Handles deleting a plugin via AJAX.
wp_ajax_search_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins via AJAX.
wp_ajax_install_theme()`wp-admin/includes/ajax-actions.php`	Handles installing a theme via AJAX.
wp_ajax_update_theme()`wp-admin/includes/ajax-actions.php`	Handles updating a theme via AJAX.
wp_ajax_delete_theme()`wp-admin/includes/ajax-actions.php`	Handles deleting a theme via AJAX.
wp_ajax_install_plugin()`wp-admin/includes/ajax-actions.php`	Handles installing a plugin via AJAX.
wp_ajax_get_post_thumbnail_html()`wp-admin/includes/ajax-actions.php`	Handles retrieving HTML for the featured image via AJAX.
WP_Customize_Selective_Refresh::handle_render_partials_request()`wp-includes/customize/class-wp-customize-selective-refresh.php`	Handles the Ajax request to return the rendered partials for the requested placements.
wp_ajax_generate_password()`wp-admin/includes/ajax-actions.php`	Handles generating a password via AJAX.
wp_ajax_save_wporg_username()`wp-admin/includes/ajax-actions.php`	Handles saving the user’s WordPress.org username via AJAX.
WP_Customize_Nav_Menus::ajax_load_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for loading available menu items.
WP_Customize_Nav_Menus::ajax_search_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for searching available menu items.
wp_ajax_crop_image()`wp-admin/includes/ajax-actions.php`	Handles cropping an image via AJAX.
WP_Customize_Manager::refresh_nonces()`wp-includes/class-wp-customize-manager.php`	Refreshes nonces for the current preview.
wp_ajax_update_plugin()`wp-admin/includes/ajax-actions.php`	Handles updating a plugin via AJAX.
wp_ajax_destroy_sessions()`wp-admin/includes/ajax-actions.php`	Handles destroying multiple open sessions for a user via AJAX.
Custom_Background::ajax_background_add()`wp-admin/includes/class-custom-background.php`	Handles Ajax request for adding custom background context to an attachment.
wp_ajax_parse_embed()`wp-admin/includes/ajax-actions.php`	Applies Ajax handlers to a string.
wp_ajax_parse_media_shortcode()`wp-admin/includes/ajax-actions.php`
wp_ajax_set_attachment_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image for an attachment via AJAX.
wp_ajax_save_attachment_order()`wp-admin/includes/ajax-actions.php`	Handles saving the attachment order via AJAX.
wp_ajax_send_attachment_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending an attachment to the editor via AJAX.
wp_ajax_send_link_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending a link to the editor via AJAX.
wp_ajax_get_revision_diffs()`wp-admin/includes/ajax-actions.php`	Handles getting revision diffs via AJAX.
wp_ajax_save_user_color_scheme()`wp-admin/includes/ajax-actions.php`	Handles auto-saving the selected color scheme for a user’s own profile via AJAX.
wp_ajax_query_themes()`wp-admin/includes/ajax-actions.php`	Handles getting themes from themes_api() via AJAX.
wp_ajax_image_editor()`wp-admin/includes/ajax-actions.php`	Handles image editing via AJAX.
wp_ajax_set_post_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image via AJAX.
wp_ajax_wp_fullscreen_save_post()`wp-admin/includes/ajax-actions.php`	Handles saving posts from the fullscreen editor via AJAX.
wp_ajax_get_attachment()`wp-admin/includes/ajax-actions.php`	Handles getting an attachment via AJAX.
wp_ajax_query_attachments()`wp-admin/includes/ajax-actions.php`	Handles querying attachments via AJAX.
wp_ajax_save_attachment()`wp-admin/includes/ajax-actions.php`	Handles updating attachment attributes via AJAX.
wp_ajax_save_attachment_compat()`wp-admin/includes/ajax-actions.php`	Handles saving backward compatible attachment attributes via AJAX.
wp_ajax_meta_box_order()`wp-admin/includes/ajax-actions.php`	Handles saving the meta box order via AJAX.
wp_ajax_find_posts()`wp-admin/includes/ajax-actions.php`	Handles querying posts for the Find Posts modal via AJAX.
Custom_Image_Header::ajax_header_crop()`wp-admin/includes/class-custom-image-header.php`	Gets attachment uploaded by Media Manager, crops it, then saves it as a new object. Returns JSON-encoded object details.
Custom_Image_Header::ajax_header_add()`wp-admin/includes/class-custom-image-header.php`	Given an attachment ID for a header image, updates its “last used” timestamp to now.
Custom_Image_Header::ajax_header_remove()`wp-admin/includes/class-custom-image-header.php`	Given an attachment ID for a header image, unsets it as a user-uploaded header image for the active theme.
WP_Customize_Manager::save()`wp-includes/class-wp-customize-manager.php`	Handles customize_save WP Ajax request to save/update a changeset.
WP_Customize_Widgets::wp_ajax_update_widget()`wp-includes/class-wp-customize-widgets.php`	Updates widget settings asynchronously.

Show 57 more Show less

Changelog

Version	Description
5.6.0	The `$flags` parameter was added.
4.7.0	The `$status_code` parameter was added.
3.5.0	Introduced.

User Contributed Notes

Skip to note 3 content

Andrew Lima

5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
Busy working on sending JSON requests back to Zapier, here’s an example to help people get started. You can send an associative array of any data you need to get returned/shown.
```
wp_send_json_success( array( 
    'name' => 'Andrew', 
    'call' => 'From some API/trigger', 
    'variable' => $var,
), 200 );
```
Log in to add feedback

Skip to note 4 content

Codex

10 years ago

-2

Basic Example

jQuery( document ).ready( function() {

	jQuery( '#btn_save' ).click( function( e ) {
		e.preventDefault();
		jQuery.post( pluginUrl+ 'ajax/save_field.php', 
			jQuery( '#my-form' ).serialize(), function( data ) {                        
				alert( data.message ); 
			}
		);
	} );
} );

save_field.php:

// Bootstrap WP

$return = array(
	'message' => __( 'Saved', 'textdomain' ),
	'ID'      => 1
);
wp_send_json_success( $return );

云策 WordPress 开发者社区

函数文档

wp_send_json_success()

概述

关键要点

代码示例

注意事项

Parameters

More Information

Source

Changelog

User Contributed Notes

函数文档

概述

关键要点

代码示例

注意事项

Parameters

More Information

Source

Related

Changelog

User Contributed Notes