描述
注意:如果使用条件标签,请在传递的实例中使用方法版本(例如,$this->is_main_query()而不是is_main_query())。这是因为像is_main_query()这样的函数是针对全局$wp_query实例而不是传递的实例进行检测的。
参数
- $query
-
(WP_Query) WP_Query实例(通过引用传递)。
更多信息
针对正确的查询
使用pre_get_posts
动作时,请注意您正在更改查询。利用条件标签以确定正确的查询。例如,建议在管理界面中使用is_admin()条件判断,而不是直接更改查询。通过查询对象中的$query->is_main_query()
条件,您可以将页面请求的主查询作为目标,主查询由主文章循环使用,该循环显示文章、页面或存档的主要内容。如果没有这些条件,您可能会无意中更改边栏、页脚或其他位置中自定义循环的查询。
以类别存档的主查询为目标的示例:
function target_main_category_query_with_conditional_tags( $query ) { if ( ! is_admin() && $query->is_main_query() ) { // Not a query for an admin page. // It's the main query for a front end page of your site. if ( is_category() ) { // It's the main query for a category archive. // Let's change the query for category archives. $query->set( 'posts_per_page', 15 ); } } } add_action( 'pre_get_posts', 'target_main_category_query_with_conditional_tags' );
默认主查询参数
主查询(对象)已经根据页面请求设置了一些默认属性。例如,对于单个文章,$query->is_single
属性设置为true。这意味着您不能简单地将单个文章或页面查询更改为文章存档查询(或相反)。要实现这一点,必须在查询对象本身中重置这些属性。除非您非常熟悉这些设置并愿意自己协调它们,否则建议您在page.php或single.php(子)主题模板文件中使用WP_Query替换主查询。
关于条件函数的警告
pre_get_posts
在WP_Query设置之前运行。一些模板标签和依赖WP_Query的条件函数将无法工作。例如,is_front_page()
将不起作用,尽管is_home()
将起作用。在这种情况下,您需要直接使用查询变量,这些变量作为参数传递给pre_get_posts
钩子(本页示例中为$query
)。
偏移和分页
在任何WordPress查询中使用offset参数都会中断分页。如果需要使用offset并保留分页,请记住需要手动处理分页。有关详细信息,请阅读codex文章使用偏移和分页进行自定义查询。
基本示例
从主页中按ID排除单个文章
function exclude_single_posts_home($query) { if ( $query->is_home() && $query->is_main_query() ) { $query->set( 'post__not_in', array( 7, 11 ) ); } } add_action( 'pre_get_posts', 'exclude_single_posts_home' );
从搜索结果中排除页面
function search_filter($query) { if ( ! is_admin() && $query->is_main_query() ) { if ( $query->is_search ) { $query->set( 'post_type', 'post' ); } } } add_action( 'pre_get_posts', 'search_filter' );
仅显示特定日期后的搜索结果
function date_search_filter($query) { if ( ! is_admin() && $query->is_main_query() ) { if ( $query->is_search ) { $query->set( 'date_query', array( array( 'after' => 'May 17, 2019', ) ) ); } } } add_action( 'pre_get_posts', 'date_search_filter' );
按文章类型更改每页的文章数量
function hwl_home_pagesize( $query ) { if ( ! is_admin() && $query->is_main_query() && is_post_type_archive( 'movie' ) ) { // Display 50 posts for a custom post type called 'movie' $query->set( 'posts_per_page', 50 ); return; } } add_action( 'pre_get_posts', 'hwl_home_pagesize', 1 );
源码
更新日志
版本 | 描述 |
---|---|
2.0.0 | 开始引入 |
使用示例
/** * * The Code below will modify the main WordPress loop, before the queries fired, * to only show posts in the halloween category on the home page. * */ function wpdocs_exclude_category( $query ) { if ( $query->is_home() && $query->is_main_query() && ! is_admin() ) { $query->set( 'category_name', 'halloween' ); } } add_action( 'pre_get_posts', 'wpdocs_exclude_category' );
有关如何调整“event”文章类型的查询的示例:
function university_adjust_queries($query){ if ( ! is_admin() && is_post_type_archive( 'event' ) && $query->is_main_query() ) { $query->set( 'meta_key', 'event_date' ); $query->set( 'orderby', 'meta_value_num' ); $query->set( 'order', 'ASC'); $query->set( 'meta_query', array( array( 'key' => 'event_date', 'compare' => '>=', 'value' => date('Ymd'), 'type' => 'numeric', ) ) ); } } add_action( 'pre_get_posts', 'university_adjust_queries' );
在主页中包含自定义文章类型
function add_custom_pt( $query ) { if ( !is_admin() && $query->is_main_query() ) { $query->set( 'post_type', array( 'post', 'the_custom_pt' ) ); } } add_action( 'pre_get_posts', 'add_custom_pt' );
包括在搜索结果中
function add_custom_pt( $query ) { if ( !is_admin() && $query->is_main_query() ) { if ( $query->is_search ) { $query->set( 'post_type', array( 'post', 'the_custom_pt' ) ); } } } add_action( 'pre_get_posts', 'add_custom_pt' );
用自定义文章类型的名称替换‘the_custom_pt’。
您可以从“最近的文章”或其他不包含meta键的小工具中筛选文章或页面。在本例中,‘transk_lang’是分配给文章和页面的meta key。
add_action( 'pre_get_posts', 'wpdocs_pre_get_posts' ); function wpdocs_pre_get_posts( $query ) { // avoid main query if ( $query->is_main_query() ) { return; } // avoid filtering menu items if ( 'nav_menu_item' === $query->query_vars['post_type'] ) { return; } // add meta query $meta_query = $query->get( 'meta_query' ); if ( ! is_array( $meta_query ) ) { $meta_query = array(); } $meta_query[] = array( 'key' => 'transk_lang', 'value' => get_user_locale(), 'compare' => '==', ); $query->set( 'meta_query', $meta_query ); }