users_pre_query
云策文档标注
概述
users_pre_query 是一个 WordPress 过滤器，用于在用户查询执行前拦截并修改查询结果。开发者可以通过此 Hook 自定义用户数据返回，从而绕过默认的 WP_User_Query 查询流程。
关键要点
- 过滤器在 WP_User_Query 查询前触发，允许返回用户数据数组以短路默认查询。
- 参数包括 $results（用户数据数组或 null）和 $query（WP_User_Query 实例的引用）。
- 若需分页信息，建议设置 WP_User_Query 对象的 total_users 属性。
- 首次引入于 WordPress 5.1.0 版本。
注意事项
当 WP_User_Query 不执行数据库查询时，它可能无法自动生成分页相关值，因此手动设置 total_users 是必要的。
原文内容
Filters the users array before the query takes place.
Description
Return a non-null value to bypass WordPress’ default user queries.
Filtering functions that require pagination information are encouraged to set the total_users property of the WP_User_Query object, passed to the filter by reference. If WP_User_Query does not perform a database query, it will not have enough information to generate these values itself.
Parameters
$resultsarray|null-
Return an array of user data to short-circuit WP’s user query or null to allow WP to run its normal queries.
$queryWP_User_Query-
The WP_User_Query instance (passed by reference).
Source
$this->results = apply_filters_ref_array( 'users_pre_query', array( null, &$this ) );
Changelog
| Version | Description |
|---|---|
| 5.1.0 | Introduced. |