wp_ajax_autocomplete_user()
云策文档标注
概述
wp_ajax_autocomplete_user() 是一个用于处理用户自动补全的 AJAX 函数，主要应用于 WordPress 多站点环境。它通过检查用户权限和网络规模，并根据请求参数返回匹配的用户列表。
关键要点
- 函数仅在多站点环境中可用，且当前用户需具备 'promote_users' 权限，否则会调用 wp_die() 终止执行。
- 支持两种请求类型：'add'（默认）和 'search'，分别用于添加用户和搜索用户。
- 支持两种字段类型：'user_login'（默认）和 'user_email'，用于指定返回值的字段。
- 通过 get_users() 函数检索用户，可基于站点 ID、搜索词和包含/排除条件进行过滤。
- 返回格式为 JSON 数组，包含 'label'（用户登录名和邮箱）和 'value'（指定字段值）。
- 使用 apply_filters('autocomplete_users_for_site_admins', bool $enable) 钩子允许非超级管理员在多站点中使用自动补全功能。
代码示例
// 示例 AJAX 请求参数
$params = array(
'autocomplete_type' => 'search',
'autocomplete_field' => 'user_email',
'term' => 'example',
'site_id' => 1
);
// 函数内部会处理这些参数并返回匹配的用户列表注意事项
- 如果网络用户数量过大（通过 wp_is_large_network('users') 检测），函数会终止执行。
- 在多站点中，非超级管理员默认无法使用此功能，除非通过过滤器启用。
- 函数使用 wp_die() 输出 JSON 响应，确保前端 AJAX 调用能正确处理返回数据。
原文内容
Handles user autocomplete via AJAX.
Source
function wp_ajax_autocomplete_user() {
if ( ! is_multisite() || ! current_user_can( 'promote_users' ) || wp_is_large_network( 'users' ) ) {
wp_die( -1 );
}
/** This filter is documented in wp-admin/user-new.php */
if ( ! current_user_can( 'manage_network_users' ) && ! apply_filters( 'autocomplete_users_for_site_admins', false ) ) {
wp_die( -1 );
}
$return = array();
/*
* Check the type of request.
* Current allowed values are `add` and `search`.
*/
if ( isset( $_REQUEST['autocomplete_type'] ) && 'search' === $_REQUEST['autocomplete_type'] ) {
$type = $_REQUEST['autocomplete_type'];
} else {
$type = 'add';
}
/*
* Check the desired field for value.
* Current allowed values are `user_email` and `user_login`.
*/
if ( isset( $_REQUEST['autocomplete_field'] ) && 'user_email' === $_REQUEST['autocomplete_field'] ) {
$field = $_REQUEST['autocomplete_field'];
} else {
$field = 'user_login';
}
// Exclude current users of this blog.
if ( isset( $_REQUEST['site_id'] ) ) {
$id = absint( $_REQUEST['site_id'] );
} else {
$id = get_current_blog_id();
}
$include_blog_users = ( 'search' === $type ? get_users(
array(
'blog_id' => $id,
'fields' => 'ID',
)
) : array() );
$exclude_blog_users = ( 'add' === $type ? get_users(
array(
'blog_id' => $id,
'fields' => 'ID',
)
) : array() );
$users = get_users(
array(
'blog_id' => false,
'search' => '*' . $_REQUEST['term'] . '*',
'include' => $include_blog_users,
'exclude' => $exclude_blog_users,
'search_columns' => array( 'user_login', 'user_nicename', 'user_email' ),
)
);
foreach ( $users as $user ) {
$return[] = array(
/* translators: 1: User login, 2: User email address. */
'label' => sprintf( _x( '%1$s (%2$s)', 'user autocomplete result' ), $user->user_login, $user->user_email ),
'value' => $user->$field,
);
}
wp_die( wp_json_encode( $return ) );
}
Hooks
- apply_filters( ‘autocomplete_users_for_site_admins’, bool $enable )
-
Filters whether to enable user auto-complete for non-super admins in Multisite.
Changelog
| Version | Description |
|---|---|
| 3.4.0 | Introduced. |