Question

wp_dropdown_users( array|string $args = '' )

Create dropdown HTML content of users.

---

description

The content can either be displayed, which it is by default or retrieved by setting the ‘echo’ argument. The ‘include’ and ‘exclude’ arguments do not need to be used; all users will be displayed in that case. Only one can be used, either ‘include’ or ‘exclude’, but not both.

The available arguments are as follows:

---

参数

$args

(array|string) (Optional) Array or string of arguments to generate a drop-down of users. See WP_User_Query::prepare_query() for additional available arguments.

• 'show_option_all'
  (string) Text to show as the drop-down default (all).
• 'show_option_none'
  (string) Text to show as the drop-down default when no users were found.
• 'option_none_value'
  (int|string) Value to use for $show_option_non when no users were found. Default -1.
• 'hide_if_only_one_author'
  (string) Whether to skip generating the drop-down if only one user was found.
• 'orderby'
  (string) Field to order found users by. Accepts user fields. Default 'display_name'.
• 'order'
  (string) Whether to order users in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC' (descending). Default 'ASC'.
• 'include'
  (array|string) Array or comma-separated list of user IDs to include.
• 'exclude'
  (array|string) Array or comma-separated list of user IDs to exclude.
• 'multi'
  (bool|int) Whether to skip the ID attribute on the 'select' element. Accepts 1|true or 0|false. Default 0|false.
• 'show'
  (string) User data to display. If the selected item is empty then the 'user_login' will be displayed in parentheses. Accepts any user field, or 'display_name_with_login' to show the display name with user_login in parentheses. Default 'display_name'.
• 'echo'
  (int|bool) Whether to echo or return the drop-down. Accepts 1|true (echo) or 0|false (return). Default 1|true.
• 'selected'
  (int) Which user ID should be selected. Default 0.
• 'include_selected'
  (bool) Whether to always include the selected user ID in the drop- down. Default false.
• 'name'
  (string) Name attribute of select element. Default 'user'.
• 'id'
  (string) ID attribute of the select element. Default is the value of $name.
• 'class'
  (string) Class attribute of the select element.
• 'blog_id'
  (int) ID of blog (Multisite only). Default is ID of the current blog.
• 'who'
  (string) Which type of users to query. Accepts only an empty string or 'authors'.
• 'role'
  (string|array) An array or a comma-separated list of role names that users must match to be included in results. Note that this is an inclusive list: users must match *each* role.
• 'role__in'
  (array) An array of role names. Matched users must have at least one of these roles. Default empty array.
• 'role__not_in'
  (array) An array of role names to exclude. Users matching one or more of these roles will not be included in results. Default empty array.

Default value: ''

---

返回值

(string) String of HTML content.

---

源代码

File: wp-includes/user.php

function wp_dropdown_users( $args = '' ) {
	$defaults = array(
		'show_option_all' => '', 'show_option_none' => '', 'hide_if_only_one_author' => '',
		'orderby' => 'display_name', 'order' => 'ASC',
		'include' => '', 'exclude' => '', 'multi' => 0,
		'show' => 'display_name', 'echo' => 1,
		'selected' => 0, 'name' => 'user', 'class' => '', 'id' => '',
		'blog_id' => get_current_blog_id(), 'who' => '', 'include_selected' => false,
		'option_none_value' => -1,
		'role' => '',
		'role__in' => array(),
		'role__not_in' => array(),
	);

	$defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0;

	$r = wp_parse_args( $args, $defaults );

	$query_args = wp_array_slice_assoc( $r, array( 'blog_id', 'include', 'exclude', 'orderby', 'order', 'who', 'role', 'role__in', 'role__not_in' ) );

	$fields = array( 'ID', 'user_login' );

	$show = ! empty( $r['show'] ) ? $r['show'] : 'display_name';
	if ( 'display_name_with_login' === $show ) {
		$fields[] = 'display_name';
	} else {
		$fields[] = $show;
	}

	$query_args['fields'] = $fields;

	$show_option_all = $r['show_option_all'];
	$show_option_none = $r['show_option_none'];
	$option_none_value = $r['option_none_value'];

	/**
	 * Filters the query arguments for the list of users in the dropdown.
	 *
	 * @since 4.4.0
	 *
	 * @param array $query_args The query arguments for get_users().
	 * @param array $r          The arguments passed to wp_dropdown_users() combined with the defaults.
	 */
	$query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $r );

	$users = get_users( $query_args );

	$output = '';
	if ( ! empty( $users ) && ( empty( $r['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) {
		$name = esc_attr( $r['name'] );
		if ( $r['multi'] && ! $r['id'] ) {
			$id = '';
		} else {
			$id = $r['id'] ? " id='" . esc_attr( $r['id'] ) . "'" : " id='$name'";
		}
		$output = "<select name='{$name}'{$id} class='" . $r['class'] . "'>\n";

		if ( $show_option_all ) {
			$output .= "\t<option value='0'>$show_option_all</option>\n";
		}

		if ( $show_option_none ) {
			$_selected = selected( $option_none_value, $r['selected'], false );
			$output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$_selected>$show_option_none</option>\n";
		}

		if ( $r['include_selected'] && ( $r['selected'] > 0 ) ) {
			$found_selected = false;
			$r['selected'] = (int) $r['selected'];
			foreach ( (array) $users as $user ) {
				$user->ID = (int) $user->ID;
				if ( $user->ID === $r['selected'] ) {
					$found_selected = true;
				}
			}

			if ( ! $found_selected ) {
				$users[] = get_userdata( $r['selected'] );
			}
		}

		foreach ( (array) $users as $user ) {
			if ( 'display_name_with_login' === $show ) {
				/* translators: 1: display name, 2: user_login */
				$display = sprintf( _x( '%1$s (%2$s)', 'user dropdown' ), $user->display_name, $user->user_login );
			} elseif ( ! empty( $user->$show ) ) {
				$display = $user->$show;
			} else {
				$display = '(' . $user->user_login . ')';
			}

			$_selected = selected( $user->ID, $r['selected'], false );
			$output .= "\t<option value='$user->ID'$_selected>" . esc_html( $display ) . "</option>\n";
		}

		$output .= "</select>";
	}

	/**
	 * Filters the wp_dropdown_users() HTML output.
	 *
	 * @since 2.3.0
	 *
	 * @param string $output HTML output generated by wp_dropdown_users().
	 */
	$html = apply_filters( 'wp_dropdown_users', $output );

	if ( $r['echo'] ) {
		echo $html;
	}
	return $html;
}

---

更新日志

Version	description
4.7.0	Added the $role, $role__in, and $role__not_in parameters.
4.5.0	Added the 'display_name_with_login' value for 'show'.
2.3.0	Introduced.

---

相关函数

Uses

• wp-includes/user.php: wp_dropdown_users_args
• wp-includes/l10n.php: _x()
• wp-includes/formatting.php: esc_attr()
• wp-includes/formatting.php: esc_html()
• wp-includes/general-template.php: selected()
• wp-includes/pluggable.php: get_userdata()
• wp-includes/query.php: is_author()
• wp-includes/query.php: get_query_var()
• wp-includes/load.php: get_current_blog_id()
• wp-includes/functions.php: wp_parse_args()
• wp-includes/functions.php: wp_array_slice_assoc()
• wp-includes/plugin.php: apply_filters()
• wp-includes/user.php: get_users()
• wp-includes/user.php: wp_dropdown_users
Show 9 more uses Hide more uses

---

Used By

• wp-admin/includes/meta-boxes.php: post_author_meta_box()
• wp-admin/includes/class-wp-posts-list-table.php: WP_Posts_List_Table::inline_edit()

---

User Contributed Notes

1. Skip to note content You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note Contributed by Codex

   Dropdown with Submit Button
   Displays a users drop-down list in HTML form with a submit button.

   
   <li id="users">
   	<h2><?php esc_html_e( 'users:' ); ?></h2>
   	<form action="<?php home_url(); ?>" method="get">
   		<?php wp_dropdown_users( array( 'name' => 'author' ) ); ?>
   		<input type="submit" name="submit" value="view" />
   	</form>
   </li>
   

Query users by role:

$role = 'subscriber';

$query_users_ids_by_role = array(
	'field' => 'id',
	'role' => $role
);

$array_of_users_ids = get_users( $query_users_ids_by_role );

$users_ids_list = implode( ',',$array_of_users_ids );

$query_for_dropdown = array(
    'include' => $user_ids_list,
);

wp_dropdown_users( $query_for_dropdown );

* Accumulated from others’ work too.

Query users by role (that work):

$query_users_ids_by_role = [
	'fields' => ['id'],
	'role' => $role
];

$array_of_users = get_users( $query_users_ids_by_role );

$array_of_users_ids = array_map(function ($user) {
	return $user->id;
}, $array_of_users);

$users_ids_list = implode( ',', $array_of_users_ids );

$query_for_dropdown = [
	'show_option_all'   => __('All users'),
	'orderby'           => 'display_name',
	'order'             => 'ASC',
	'include'           => $users_ids_list
];

wp_dropdown_users($query_for_dropdown);