Question

get_users( array $args = array() )

Retrieve list of users matching criteria.

---

description

---

参数

$args

(array) (Optional) Arguments to retrieve users. See WP_User_Query::prepare_query(). for more information on accepted arguments.

Default value: array()

---

返回值

(array) List of users.

---

源代码

File: wp-includes/user.php

function get_users( $args = array() ) {

	$args = wp_parse_args( $args );
	$args['count_total'] = false;

	$user_search = new WP_User_Query($args);

	return (array) $user_search->get_results();
}

---

更新日志

Version	description
3.1.0	Introduced.

---

相关函数

Uses

• wp-includes/functions.php: wp_parse_args()
• wp-includes/class-wp-user-query.php: WP_User_Query::__construct()

---

Used By

• wp-admin/includes/class-wp-ms-sites-list-table.php: WP_MS_Sites_List_Table::column_users()
• wp-admin/includes/ms.php: wpmu_delete_blog()
• wp-admin/includes/schema.php: populate_network()
• wp-admin/includes/ajax-actions.php: wp_ajax_autocomplete_user()
• wp-admin/includes/ms.php: confirm_delete_users()
• wp-includes/user.php: wp_dropdown_users()
• wp-includes/author-template.php: wp_list_authors()
• wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_getAuthors()
• wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_getUsers()
Show 4 more used by Hide more used by

---

User Contributed Notes

1. Skip to note content 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 Contributed by Codex

   An example using the ‘search’ field.

   
   <?php
   $blogusers = get_users( array( 'search' => 'john' ) );
   // Array of WP_User objects.
   foreach ( $blogusers as $user ) {
   	echo '<span>' . esc_html( $user->user_email ) . '</span>';
   }
   

   This example will find and display all users that have a user name, ID, email of “john”. You can also do wild card search by adding an * before or after your search query. For example, to search for all users that start with “jo”, you would pass something like “jo*”.

   The results will be all users whose user names, IDs, or emails that start with “jo”. The * can be placed before or after your search query. When placed before, the results will be all users that end in your query.

An example of querying by a specific field.

<?php
$blogusers = get_users( array( 'fields' => array( 'display_name' ) ) );
// Array of stdClass objects.
foreach ( $blogusers as $user ) {
	echo '<span>' . esc_html( $user->display_name ) . '</span>';
}

A basic example to display all subscribers in an unordered list.

<?php
$blogusers = get_users( 'blog_id=1&orderby=nicename&role=subscriber' );
// Array of WP_User objects.
foreach ( $blogusers as $user ) {
	echo '<span>' . esc_html( $user->user_email ) . '</span>';
}

An example of fetching users that match any one of an array of roles using role__in.

<?php
$blogusers = get_users( [ 'role__in' => [ 'author', 'subscriber' ] ] );
// Array of WP_User objects.
foreach ( $blogusers as $user ) {
    echo '<span>' . esc_html( $user->display_name ) . '</span>';
}