各位观众老爷，大家好！今天咱们来聊聊WordPress里一个相当重要的角色——WP_User_Query，这玩意儿就好比是用户数据的“高级搜索官”，能帮你从WordPress那茫茫人海（用户数据库）中，找到你想要的特定用户群体。
一、开场白：用户数据，WordPress的基石
想想看，一个WordPress网站，少了用户，那还算什么？没有注册用户，就没有评论互动，没有会员权限，甚至连文章都没人看（如果允许匿名评论，那另说）。所以，用户数据是WordPress的基石，而WP_User_Query就是让你玩转这些数据的利器。
二、WP_User_Query：你的高级用户数据搜索官
WP_User_Query是一个类，位于wp-includes/user.php文件中。它的主要作用就是根据你提供的各种条件，从WordPress的用户数据库中检索出符合条件的用户信息。
三、基本用法：构建你的第一个查询
最简单的用法是实例化这个类，然后执行查询。
$user_query = new WP_User_Query();
if ( ! empty( $user_query->results ) ) {
foreach ( $user_query->results as $user ) {
echo 'User ID: ' . $user->ID . '<br>';
echo 'Username: ' . $user->user_login . '<br>';
echo 'Email: ' . $user->user_email . '<br>';
echo '<hr>';
}
} else {
echo 'No users found.';
}这段代码会获取所有用户，然后循环输出他们的ID、用户名和邮箱。简单粗暴，但是有用。
四、查询参数：选择你的搜索条件
WP_User_Query最强大的地方在于它支持大量的查询参数，让你能够精确地筛选用户。 这些参数都可以在构造函数中以数组的形式传入。下面列出一些常用的参数：
| 参数名称 | 描述 | 默认值 | 数据类型 |
|---|---|---|---|
role |
按照用户角色筛选，例如 administrator、editor、author、contributor、subscriber。可以传入单个角色或者角色数组。 |
” | string/array |
role__in |
查找拥有任何指定角色的用户。传入一个角色数组。 | ” | array |
role__not_in |
查找不拥有任何指定角色的用户。传入一个角色数组。 | ” | array |
include |
只返回指定ID的用户。传入一个用户ID数组。 | ” | array |
exclude |
排除指定ID的用户。传入一个用户ID数组。 | ” | array |
search |
搜索用户名或电子邮件。 | ” | string |
search_columns |
指定搜索的列。可以是 'user_login'、'user_email'、'user_nicename'、'display_name'。传入一个列名数组。 |
” | array |
orderby |
排序字段。可以是 'ID'、'login'、'nicename'、'email'、'url'、'registered'、'display_name'、'post_count'。 |
'login' |
string |
order |
排序方式。可以是 'ASC'（升序）或 'DESC'（降序）。 |
'ASC' |
string |
offset |
偏移量，跳过多少个用户。 | ” | int |
number |
返回的用户数量。 | ” (all) | int |
meta_key |
自定义用户元数据的键名。与 meta_value 或 meta_query 配合使用。 |
” | string |
meta_value |
自定义用户元数据的值。与 meta_key 配合使用。 |
” | string/array |
meta_compare |
自定义用户元数据的比较运算符。可以是 '='、'!='、'>'、'>='、'<'、'<='、'LIKE'、'NOT LIKE'、'IN'、'NOT IN'、'BETWEEN'、'NOT BETWEEN'、'REGEXP'、'NOT REGEXP'、'RLIKE'。 |
'=' |
string |
meta_query |
更复杂的元数据查询。使用数组定义多个元数据条件。 | ” | array |
has_published_posts |
是否有已发布的文章。可以设置为 true 或 false。 从WordPress 5.9开始可用。 |
null |
bool |
nicename |
按照用户昵称筛选用户。 | ” | string/array |
nicename__in |
查找昵称在指定列表中的用户。传入一个昵称数组。 | ” | array |
nicename__not_in |
查找昵称不在指定列表中的用户。传入一个昵称数组。 | ” | array |
login |
按照用户名筛选用户。 | ” | string/array |
login__in |
查找用户名在指定列表中的用户。传入一个用户名数组。 | ” | array |
login__not_in |
查找用户名不在指定列表中的用户。传入一个用户名数组。 | ” | array |
registered_after |
注册日期晚于指定日期。可以使用日期字符串或 DateTime 对象。 | ” | string/DateTime |
registered_before |
注册日期早于指定日期。可以使用日期字符串或 DateTime 对象。 | ” | string/DateTime |
date_query |
更复杂的注册日期查询。使用数组定义多个日期条件。 从WordPress 3.7开始可用。 | ” | array |
五、实例演示：玩转查询参数
- 查找所有管理员：
$args = array(
'role' => 'administrator',
);
$user_query = new WP_User_Query( $args );
if ( ! empty( $user_query->results ) ) {
echo 'Administrators:<br>';
foreach ( $user_query->results as $user ) {
echo $user->user_login . '<br>';
}
} else {
echo 'No administrators found.';
}- 查找用户名包含 "test" 的用户：
$args = array(
'search' => '*test*', // *号是通配符
'search_columns' => array( 'user_login' ),
);
$user_query = new WP_User_Query( $args );
if ( ! empty( $user_query->results ) ) {
echo 'Users with "test" in their username:<br>';
foreach ( $user_query->results as $user ) {
echo $user->user_login . '<br>';
}
} else {
echo 'No users found with "test" in their username.';
}- 查找 ID 为 1, 3, 5 的用户：
$args = array(
'include' => array( 1, 3, 5 ),
);
$user_query = new WP_User_Query( $args );
if ( ! empty( $user_query->results ) ) {
echo 'Users with ID 1, 3, or 5:<br>';
foreach ( $user_query->results as $user ) {
echo $user->user_login . '<br>';
}
} else {
echo 'No users found with ID 1, 3, or 5.';
}- 查找注册日期在 2023年1月1日 之后的订阅者：
$args = array(
'role' => 'subscriber',
'date_query' => array(
array(
'after' => '2023-01-01',
'inclusive' => true, // 包含指定日期
),
),
);
$user_query = new WP_User_Query( $args );
if ( ! empty( $user_query->results ) ) {
echo 'Subscribers registered after 2023-01-01:<br>';
foreach ( $user_query->results as $user ) {
echo $user->user_login . '<br>';
}
} else {
echo 'No subscribers found registered after 2023-01-01.';
}- 使用
meta_query进行高级自定义字段查询：
假设你使用了一个自定义字段来存储用户的“城市”，键名为'city'，你想查找所有住在“北京”或“上海”的用户。
$args = array(
'meta_query' => array(
'relation' => 'OR', // 可以是 'AND'
array(
'key' => 'city',
'value' => '北京',
'compare' => '=',
),
array(
'key' => 'city',
'value' => '上海',
'compare' => '=',
),
),
);
$user_query = new WP_User_Query( $args );
if ( ! empty( $user_query->results ) ) {
echo 'Users living in Beijing or Shanghai:<br>';
foreach ( $user_query->results as $user ) {
echo $user->user_login . '<br>';
}
} else {
echo 'No users found living in Beijing or Shanghai.';
}六、分页：处理大量用户数据
如果你的网站用户数量非常庞大，一次性加载所有用户数据可能会导致性能问题。WP_User_Query 提供了分页功能，可以分批加载用户数据。
$paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1; // 获取当前页码
$users_per_page = 10; // 每页显示的用户数量
$args = array(
'number' => $users_per_page,
'offset' => ( $paged - 1 ) * $users_per_page,
);
$user_query = new WP_User_Query( $args );
if ( ! empty( $user_query->results ) ) {
echo 'Users (page ' . $paged . '):<br>';
foreach ( $user_query->results as $user ) {
echo $user->user_login . '<br>';
}
// 输出分页链接 (需要自己实现分页逻辑，这里只是个示例)
$total_users = $user_query->get_total();
$total_pages = ceil( $total_users / $users_per_page );
echo '<div class="pagination">';
for ($i = 1; $i <= $total_pages; $i++) {
echo '<a href="?paged=' . $i . '">' . $i . '</a> ';
}
echo '</div>';
} else {
echo 'No users found.';
}七、get_results() vs get_total()：获取结果的正确姿势
$user_query->results：返回一个包含用户对象的数组。你可以循环遍历这个数组来访问每个用户的信息。$user_query->get_total()：返回符合查询条件的用户总数。这个方法不会返回用户对象，只是告诉你总共有多少用户符合条件。 当你需要做分页的时候，这个方法非常有用。
八、性能优化：避免查询地狱
WP_User_Query功能强大，但也容易被滥用，导致性能问题。以下是一些优化建议：
- 只查询需要的字段： 默认情况下，
WP_User_Query会返回所有用户字段。如果只需要特定的字段，可以使用fields参数来指定。 例如，只获取用户的ID：'fields' => 'ID' - 避免在循环中执行查询： 尽量避免在循环中调用
WP_User_Query，这样会产生大量的数据库查询，严重影响性能。应该在循环外部执行查询，然后将结果缓存起来。 - 使用缓存： WordPress 提供了对象缓存机制，可以将查询结果缓存起来，避免重复查询数据库。可以使用
wp_cache_get()和wp_cache_set()函数来实现缓存。 - 索引优化： 如果你经常使用自定义字段进行查询，可以考虑在数据库中为这些字段添加索引，以提高查询效率。
- 避免使用过于复杂的
meta_query： 复杂的meta_query会导致查询效率低下。尽量简化查询条件，或者考虑使用更高效的查询方式，例如使用 WordPress 的内置分类法或标签来组织用户数据。 - 使用
count_total参数： 如果只需要知道符合条件的用户总数，而不需要获取用户对象，可以将count_total设置为false，这样可以避免加载用户对象，提高查询效率。
$args = array(
'count_total' => false, // 只计算总数，不返回用户对象
'role' => 'administrator',
);
$user_query = new WP_User_Query( $args );
$total_admins = $user_query->get_total();
echo "Total administrators: " . $total_admins;九、WP_User_Query 的替代方案
虽然WP_User_Query很强大，但在某些情况下，可能有更合适的替代方案：
get_users()函数： 这是 WordPress 提供的一个更简单的函数，用于获取用户。它接受的参数与WP_User_Query类似，但功能相对较少。如果只需要简单的用户查询，可以使用get_users()函数。- 直接执行 SQL 查询： 如果需要执行非常复杂的查询，或者需要访问一些
WP_User_Query不支持的数据库字段，可以直接执行 SQL 查询。 但是，直接执行 SQL 查询需要小心处理数据安全问题，并确保与 WordPress 的数据库结构保持一致。 - 使用第三方插件： 有很多第三方插件提供了更高级的用户管理和查询功能。如果需要更强大的功能，可以考虑使用这些插件。
十、WP_User_Query的几个隐藏小技巧
-
who参数： 这个参数允许你查询那些当前在线的用户。 它的取值只有'authors'和'all'。'authors'会返回至少发表过一篇文章的在线用户。'all'则会返回所有在线用户。 但是，这个参数的准确性依赖于 WordPress 的心跳机制，所以可能不是 100% 准确。$args = array( 'who' => 'authors', ); $user_query = new WP_User_Query( $args ); if ( ! empty( $user_query->results ) ) { echo 'Online authors:<br>'; foreach ( $user_query->results as $user ) { echo $user->user_login . '<br>'; } } else { echo 'No online authors found.'; } -
查询已发布文章的用户： 通过
has_published_posts参数可以查找已发布文章的用户（WordPress 5.9+）。这对于查找活跃用户非常有用。
$args = array(
'has_published_posts' => true,
);
$user_query = new WP_User_Query( $args );
if ( ! empty( $user_query->results ) ) {
echo 'Users who have published posts:<br>';
foreach ( $user_query->results as $user ) {
echo $user->user_login . '<br>';
}
} else {
echo 'No users found who have published posts.';
}十一、总结：灵活运用，掌控用户数据
WP_User_Query 是 WordPress 中一个非常重要的类，它可以让你轻松地从用户数据库中检索出符合条件的用户信息。 掌握 WP_User_Query 的用法，可以让你更好地管理用户数据，并为用户提供更好的体验。记住，灵活运用查询参数，注意性能优化，你就能成为用户数据的主宰者！
好了，今天的讲座就到这里。希望大家有所收获，下次再见！