描述
可以显示内容(默认情况下是这样),也可以通过设置“echo”参数来检索内容。“include”和“exclude”参数非必须;在这种情况下,将显示所有用户。“include”和“exclude”只能使用一个,不能同时使用。
可用参数如下:
参数
- $args
-
(array|string)
(可选)
用于生成用户下拉列表的参数数组或字符串。有关其他可用参数,请参见WP_User_Query::prepare_query()。- 'show_option_all'
(string) 显示为下拉默认的文本(全部)。 - 'show_option_none'
(string) 未找到用户时显示为下拉默认值的文本。 - 'option_none_value'
(int|string) 未找到用户时$show_option_non使用的值,默认值-1。 - 'hide_if_only_one_author'
(string) 如果只找到一个用户,是否跳过生成下拉列表。 - 'orderby'
(string) 找到用户的排序依据字段,接受用户字段。默认值'display_name'。 - 'order'
(string) 是按升序还是降序排列用户。接受“ASC”(升序)或“DESC”(降序)。默认值“ASC”。 - 'include'
(int[]|string) 要包括的用户ID的数组或逗号分隔列表。 - 'exclude'
(int[]|string) 要排除的用户ID的数组或逗号分隔列表。 - 'multi'
(bool|int) 是否跳过“select”元素上的ID属性。接受 1|true 或 0|false,默认值 0|false。 - 'show'
(string) 要显示的用户数据。如果所选项目为空,则'user_login'将显示在括号中。接受任何用户字段,或'display_name_with_login'以显示显示名称,括号中带有user_login。默认值'display_name'。 - 'echo'
(int|bool) 是回显还是返回下拉列表。接受 1|true(echo)或 0|false(return)。默认 1|true。 - 'selected'
(int) 应选定哪个用户ID。默认值为0。 - 'include_selected'
(bool) 是否总是在下拉列表中包含选定的用户ID。默认值为false。 - 'name'
(string) select元素的name属性。默认'user'。 - 'id'
(string) select元素的ID属性。默认值为$name。 - 'class'
(string) select元素的class属性。 - 'blog_id'
(int) 博客ID(仅限多站点)。默认值是当前博客的ID。 - 'who'
(string) 要查询的用户类型。只接受空字符串或“authors”。 - 'role'
(string|array) 用户必须匹配才能包含在结果中的角色名称的数组或逗号分隔列表。注意,这是一个包含列表:用户必须匹配*每个*角色。 - 'role__in'
(string[]) 角色名称数组。匹配的用户必须至少具有其中一个角色。默认空数组。 - 'role__not_in'
(string[]) 要排除的角色名称数组。匹配其中一个或多个角色的用户将不会包含在结果中。默认空数组。
默认值: ''
- 'show_option_all'
返回
(string) 用户的HTML下拉列表。
源码
更新日志
版本 | 描述 |
---|---|
4.7.0 | 添加了$role 、$role__in 和$role__not_in 参数。 |
4.5.0 | 为“show”添加了'display_name_with_login'值。 |
2.3.0 | 开始引入 |
使用示例
带有提交按钮的下拉列表
以HTML格式显示带有提交按钮的用户下拉列表。<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_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);
自版本5.9以来,
who
参数不再有效,您需要使用新的功能或角色参数:按角色查询用户:
$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 );
*也是从别人的工作中积累起来的。