query_posts( array|string $query )

说明

Credit: Andrey Savchenko (rarst.net) / CC-By-SA.

query_posts()是一种改变WordPress用于显示文章的主查询的方法。它将主查询放在一边，并用一个新查询替换它。要在调用query_posts后进行清理，请调用wp_reset_query()，原始主查询将被还原。

应该注意的是，使用它来替换页面上的主查询可能会增加页面加载时间，在最坏的情况下，所需工作量会增加一倍以上。虽然该函数易于使用，但以后也容易出现混淆和问题。有关详细信息，请参阅下面的注意事项。

对于一般文章查询，请使用WP_Query或get_posts()。

强烈建议您使用‘pre_get_posts’动作，并通过检查is_main_query()来更改主查询。

例如，在主页上，你通常会看到最近的10篇文章。如果您只想显示5篇文章（并且不关心分页），可以这样使用query_posts()：

query_posts( 'posts_per_page=5' );

下面是在functions.php中使用‘pre_get_posts’动作的类似代码：

function wpdocs_five_posts_on_homepage( $query ) {
    if ( $query->is_home() && $query->is_main_query() ) {
        $query->set( 'posts_per_page', 5 );
    }
}
add_action( 'pre_get_posts', 'wpdocs_five_posts_on_homepage' );

用法

// The Query
query_posts( $args );

// The Loop
while ( have_posts() ) : the_post();
	echo '
<li>';
	the_title();
	echo '</li>

';
endwhile;

// Reset Query
wp_reset_query();

在循环开始之前，在一个模板文件中调用query_posts()。WP_Query对象将使用您的参数生成一个新的SQL查询。执行此操作时，WordPress会忽略通过URL接收的其他参数（例如页码或类别）。

保留现有查询参数

如果要保留用于生成当前查询的原始查询参数信息，然后添加或覆盖某些参数，可以在对query_posts()的调用中使用$query_string全局变量。

例如，要在不影响查询字符串其余部分的情况下设置文章的显示顺序，可以将以下内容放在循环之前：

global $query_string;
query_posts( $query_string . '&order=ASC' );

以这种方式使用query_posts()时，参数的引用部分必须以与（&）开头。

或者，您可以将原始查询数组合并到参数数组中：

global $wp_query;
$args = array_merge( $wp_query->query_vars, array( 'post_type' => 'product' ) );
query_posts( $args );

参数组合

您可能已经从上面的一些示例中注意到，您将参数与符号（&）组合在一起，像这样：

query_posts( 'cat=3&year=2004' );

主页上当月类别13的文章：

if ( is_home() ) {
	query_posts( $query_string . '&cat=13&monthnum=' . date( 'n', current_time( 'timestamp' ) ) );
}

在2.3，这种组合将返回属于类别1和类别3的文章，只显示两（2）篇文章，按标题降序排列：

query_posts( array( 'category__and' => array(1,3), 'posts_per_page' => 2, 'orderby' => 'title', 'order' => 'DESC' ) );

下面返回所有属于类别1，标签为“apples”的文章。

query_posts( 'cat=1&tag=apples' );

您可以使用“+”搜索多个标签。在这种情况下，所有文章都属于类别1，标签为“apples”和“oranges”。

query_posts( 'cat=1&tag=apples+oranges' );

注意事项

query_posts()只是众多查询数据库和生成文章列表的方法之一。在决定使用query_posts()之前，请务必了解其缺点。

更改主循环

query_posts()用于改变主循环。它通过替换用于生成主循环内容的查询来实现。使用query_posts()后，与post相关的全局变量和模板标签将被更改。在您调用query_posts()之后调用的条件标签也将被更改–这可能是也可能不是预期的结果。

二次循环

要创建二次列表（例如，页面底部的相关文章列表，或边栏小工具中的链接列表），请尝试创建WP_Query的新实例或使用get_posts()。

如果必须使用query_posts()，请确保在完成后调用wp_reset_query()。

分页

除非适当设置“paged”查询变量，否则分页将无法正常工作。

额外的SQL查询

如果您在模板页面中使用query_posts，WordPress将已经执行了数据库查询，并在到达模板页面时检索到记录（这就是它如何知道要提供哪个模板页面！）。因此，当您使用query_posts()覆盖默认查询时，实际上是在丢弃默认查询及其结果，然后对数据库重新执行另一个查询。

这不一定是一个问题，尤其是如果你正在处理一个较小的基于博客的网站。具有大型数据库和高访问量的大型网站的开发人员可能希望考虑其他选择，例如直接修改默认请求（在调用之前）。‘request’过滤器可用于实现这一点。

‘parse_query’和‘pre_get_posts’过滤器也可用于修改用于生成查询数据库的SQL的内部$query对象。