编辑“WordPress模板标签之query posts”

<span style="border:1px solid #000; text-align:center; float:right; padding:6px;"><strong>导航:</strong> [[WordPress开发文档|上一页]] | {{Template:WordPress导航}}</span>
<div style="clear:both;"></div>
==说明==
该标签可决定哪些文章出现在[http://www.wordpress.la/codex-WordPress%E4%B8%BB%E5%BE%AA%E7%8E%AF.html WordPress主循环（loop）]中。该标签接收大量参数，格式与URL中的参数格式相同（如p=4表示ID为4的文章）。

为什么非要更改从URL中生成的查询语句呢？你完全可以通过结合博客文章与页面逻辑（如条件[http://www.wordpress.la/codex-%E6%9D%A1%E4%BB%B6%E6%A0%87%E7%AD%BE.html 标签]）来定制博客文章的样式——而无需更改任何URL。

常见用途：
*仅在博客主页上显示一篇文章（通过设置>阅读进行设置） 
*显示某一特定时间段内发表的所有文章 
*在主页显示近期发表文章 
*更改文章排列顺序 
*仅显示某一分类目录中的文章 
*排除一个或多个分类 

'''重要提示'''
query_posts函数仅用于修改主页循环（Loop），而不是一种在页面上生成次级循环的手段。如果你希望在主循环外另外生成循环，应该新建独立的[http://www.wordpress.la/codex-%E5%B8%B8%E7%94%A8%E5%87%BD%E6%95%B0-wp_query%28%29.html WP_Query]对象，用这些对象生成循环。在主循环外的循环上使用query_posts会导致主循环运行偏差，并可能在页面上显示出你不希望看到的内容。

query_posts函数会改写并取代页面的主查询。为谨慎起见，请不要将query_posts用作其它用途。

==用法==
 <?php
 //The Query
 query_posts('posts_per_page=5');
 //The Loop
 if ( have_posts() ) : while ( have_posts() ) : the_post();
 ..
 endwhile; else:
 ..
 endif;
 //Reset Query
 wp_reset_query();
 ?>

'''用法提示'''

在主循环开始前，对你的某个[http://www.wordpress.la/codex-WordPress%E6%A8%A1%E6%9D%BF%E6%96%87%E4%BB%B6.html 模板]文件的query_posts()安排一个调用。wp_query对象会利用参数生成新的SQL查询。当你开始调用时，WordPress会忽略通过URL接收到的其它参数（如页面编号或分类）。如果你希望保留这些信息，可以在对query_posts()的调用中使用$query_string全局变量。

例如，要设置文章的显示顺序而不影响查询字符串的剩余部分，可以将以下代码添加到[http://www.wordpress.la/codex-WordPress%E4%B8%BB%E5%BE%AA%E7%8E%AF.html 主循环（loop）]之前：
 global $query_string;  
 query_posts($query_string . "&order=ASC");  
以这种方式使用query_posts时，参数所引用的部分必须以&符号开头。

==示例==
===从博客主页上排除某些分类===

将以下代码添加到index.php文件中，使主页显示的文章可以来自除分类3以外的任何分类。
 <?php
 if (is_home()) {
 query_posts("cat=-3");
 }
 ?>

你也可以多排除几个分类。
 <?php
 if (is_home()) {
 query_posts("cat=-1,-2,-3");
 }
 ?>

===检索指定文章===

用以下语句检索某篇指定文章：
 <?php
 // retrieve one post with an ID of 5
 query_posts('p=5'); 
 ?>

如果你希望在查询语句中使用Read More功能，请将全局变量$more设为0。
 <?php
 // retrieve one post with an ID of 5
 query_posts('p=5');
 global $more;
 // set $more to 0 in order to only get the first part of the post
 $more = 0;
 // the Loop
 while (have_posts()) : the_post(); 
 // the content of the post
 the_content('Read the full post ?'); 
 endwhile;
 ?>

===检索指定页面===
用以下语句检索某篇指定页面：
 <?php
 query_posts('page_id=7'); //retrieves page 7 only
 ?>
或者
 <?php
 query_posts('pagename=about'); //retrieves the about page only
 ?>

检索子页面时，需要提供子页面及其父页面的别名，用斜线隔开两者。例如：
 <?php
 query_posts('pagename=parent/child'); // retrieve the child page of a parent
 ?>

===给query_posts传递变量===
有两种方法可以给给查询传递变量，你可以根据自己的需求从中选择一种。使用时，将代码添加到循环中：

'''示例1'''

在这个例子中，我们在运行查询语句前先连结所有查询。首先赋值变量，然后连结变量并运行。这里我们要从别处引入一个分类变量。
 <?php
 $categoryvariable=$cat; // assign the variable as current category
 $query= 'cat=' . $categoryvariable. '&orderby=date&order=ASC'; // concatenate the query
 query_posts($query); // run the query
 ?>

'''示例2'''

这个示例将使用双引号来告诉PHP将引号中的内容当成表达式。在下面的例子中，我们要获取当前月份、年份时间，然后让query_posts获取当前月/年的文章，并且以升序方式在页面最上方显示发表日期最早的文章。
 <?php
 $current_month = date('m');
 $current_year = date('Y');
 query_posts("cat=22&year=$current_year&monthnum=$current_month&order=ASC");
 ?>
 <!-- put your loop here -->

''示例3''

该示例说明了怎样生成一个完整的文章分页列表。我们可以用默认的$query_string来命令query_posts给我们显示一个完整的文章列表。也可以将posts_per_page查询语句从-1改成你希望在每页显示的文章数。在后面这种情况下，你可以用posts_nav_link 来导航所生成的存档。
 <?php 
 query_posts($query_string.'&posts_per_page=-1');
 while(have_posts()) { the_post();
 <!-- put your loop here -->
 }
 ?>

'''示例4'''

如果你不需要使用$query_string变量，可以在一些复杂的情况下使用一个更简单易读的方法。这个方法就是，将参数放入数组。那么通过下面的代码，也可以生成示例2中的查询：
 query_posts(array(
 'cat' => 22, 
 'year' => $current_year, 
 'monthnum' => $current_month, 
 'order' => 'ASC',
 ));

现在你可以看到，所有变量都独立成行，更加便于阅读。

'''保留原始查询'''

如果你希望保留原始查询，可以将原始查询数组整合到参数数组中：
 global $wp_query;
 query_posts(
 array_merge(
 array('cat' => 1),
 $wp_query->query
 )
 );

==参数==
这里并没有列出完整的参数列表。我们在这里介绍这些参数，只是为了让你多了解一些关于如何设置查询的信息。

===分类参数===
只显示特定分类下的文章。

*cat —— 必须使用分类ID 
*category_name 
*category_and —— 必须使用分类ID 
*category_in —— 必须使用分类ID 
*category_not_in —— 必须使用分类ID 
'''根据ID显示单个分类'''

只显示来自某一个分类目录ID（以及该分类目录下的子分类目录）的文章：
 query_posts('cat=4');  

'''根据分类名称显示单个分类'''

只显示来自某一个分类名称下的文章：
 query_posts('category_name=Staff Home');  

'''根据ID显示多个分类'''

显示来自若干指定分类目录ID下的文章：
 query_posts('cat=2,6,17,38');  

'''排除某一分类中的文章'''

显示除某一分类文章外的所有文章，被排除的分类ID以减号（'-'）作为前缀。
 query_posts('cat=-3');  

以上代码删除ID为3的分类中的文章。

'''处理多个分类'''

显示隶属于多个分类的文章。下面的代码可展示同时属于分类2和分类6的文章：
 query_posts(array('category__and' => array(2,6))); 
如果希望显示分类2或分类6中的文章，可以使用上面介绍的cat，也可以使用category_in函数 （注意这里不会显示分类下子分类中的文章） ：
 query_posts(array('category__in' => array(2,6)));  
可以用下面这种方式排除多个分类中的文章：
 query_posts(array('category__not_in' => array(2,6)));  
===标签参数===
显示特定标签下的文章。
*tag —— 必须使用标签ID 
*tag_id —— 必须使用标签ID 
*tag_and —— 必须使用标签ID 
*tag_in —— 必须使用标签ID 
*tag_not_in —— 必须使用标签ID 
*tag_slug_and ——必须使用标签ID 
*tag_slug_in ——必须使用标签ID 
'''获取某一标签中的文章'''
 query_posts('tag=cooking');  
'''获取若干标签中任一标签中的文章'''
 query_posts('tag=bread+baking+recipe');  

'''多个标签'''

显示同时属于ID为37和47的标签下的文章：
 query_posts(array('tag__and' => array(37,47));  
若要显示ID为为37或47的标签下的文章，可以使用tag参数，也可以用tag_in：
 query_posts(array('tag__in' => array(37,47));  
显示的文章既不属于标签37，也不属于标签47：
 query_posts(array('tag__not_in' => array(37,47));  
tag_slug_in与tag_slug_and工作方式几乎一致，不同之处在于相匹配的别名不同。

===作者参数===
你也可以根据作者来选择文章。
*author=3 
*author=-3 ——排除ID为3的作者所发表的文章 
*author_name=Harriet 
注意：author_name运行在user_nicename字段上，同时author运行在author id字段上。

显示ID为1的作者所发表的所有页面，以标题顺序排列页面，页面列表上方无置顶文章：
 query_posts('caller_get_posts=1&author=1&post_type=page&post_status=publish&orderby=title&order=ASC');  

===文章&页面参数===
检索单篇文章或页面。

*'p' => 27 —— 通过文章ID显示该文章 
*'name' => 'about-my-life' —— 对某篇文章的查询，查询中含有文章别名 
*'page_id' => 7 —— 对ID为7的页面的查询 
*'pagename' => 'about' —— 注意，这不是页面标题，而是页面路径 
*用'posts_per_page' => 1 - use 'posts_per_page' => 3 展示3篇文章。用'posts_per_page' => -1展示所有文章 
*'showposts' => 1 - use 'showposts' => 3 展示3篇文章。用'showposts' => -1展示所有文章。已弃用。 
*'post__in' => array(5,12,2,14,7) —— 指定希望检索的文章ID 
*'post__not_in' => array(6,2,8) ——排除不希望检索的文章ID 
*'post_type' => 'page' ——返回页面；默认值为post；可用值包括any, attachment, page, post或revision。any可检索到除修订版外的所有页面类型。 
*'post_status' => 'publish' —— 返回已发布页面。可用值还包括pending, draft, future, private, trash。关于inherit请见get_children。trash状态新增于WordPress 2.9。 
*'post_parent' => 93 —— 返回页面93的子页面。 

===置顶文章参数===
置顶文章功能引入于WordPress 2.7。在查询中，被设为“置顶”的文章会显示在其它文章之前，除非该文章已经被caller_get_posts=1参数排除。

array('post__in'=>get_option('sticky_posts')) —— 返回所有置顶文章的数组 
caller_get_posts=1 —— 排除返回的文章上方的置顶文章，但在返回文章列表时，以自然顺序将曾经置顶的文章安插在列表中。 
返回第一篇置顶文章
 $sticky=get_option('sticky_posts') ; 
 query_posts('p=' . $sticky[0]);

或
 $args = array(
 'posts_per_page' => 1,
 'post__in' => get_option('sticky_posts'),
 'caller_get_posts' => 1
 );
 query_posts($args);

注意：第二种方法只能返回最新发表的置顶文章；若当前无置顶文章，返回最新发表文章。

返回第一篇置顶文章；若无，则不返回任何内容
 $sticky = get_option('sticky_posts');
 $args = array(
 'posts_per_page' => 1,
 'post__in' => $sticky,
 'caller_get_posts' => 1
 );
 query_posts($args);
 if($sticky[0]) {
 // insert here your stuff...
 }

'''从查询中排除所有置顶文章'''
 query_posts(array("post__not_in" =>get_option("sticky_posts"))); 
返回某一分类下所有文章，但不在文章列表上方显示置顶文章。所有设为“置顶”的文章以正常顺序（如日期顺序）显示
 query_posts('caller_get_posts=1&posts_per_page=3&cat=6');   
返回某一分类下所有文章，完全不显示置顶文章，保留分页
 <?php
 $paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
 $sticky=get_option('sticky_posts');
 $args=array(
 'cat'=>3,
 'caller_get_posts'=>1,
 'post__not_in' => $sticky,
 'paged'=>$paged,
 );
 query_posts($args);
 ?>
===时间参数===
检索特定时间段内发表的文章。
*hour= -hour （时，-范围从0到23） 
*minute= - minute （分，-范围从0到60） 
*second= - second （秒，-范围从0到60） 
*day= - day of the month （日，-范围从1到31） 
*monthnum= - month number （月，-范围从1到12） 
*year= - 4 digit year (年，如2009) 
*w= - week of the year（一年中的第几周，-范围从0到53），使用[http://dev.mysql.com/doc/refman/5.1/en/date-and-time-functions.html#function_week MySQL WEEK command Mode=1]命令 

'''返回最近发表的文章'''
 $today = getdate();  
 query_posts('year=' .$today["year"] .'&monthnum=' .$today["mon"] .'&day=' .$today["mday"] );  

'''返回12月20日发表的文章'''
 query_posts(monthnum=12&day=20' );  

'''返回2009年3月1日到3月15日之间发表的文章'''
 <?php
 //based on Austin Matzko's code from wp-hackers email list
 function filter_where($where = '') {
 //posts for March 1 to March 15, 2009
 $where .= " AND post_date >= '2009-03-01' AND post_date < '2009-03-16'";
 return $where;
 }
 add_filter('posts_where', 'filter_where');
 query_posts($query_string);
 ?>

'''返回最近30天内发表的文章'''
 <?php
 //based on Austin Matzko's code from wp-hackers email list
 function filter_where($where = '') {
 //posts in the last 30 days
 $where .= " AND post_date > '" . date('Y-m-d', strtotime('-30 days')) . "'";
 return $where;
 }
 add_filter('posts_where', 'filter_where');
 query_posts($query_string);
 ?>

返回过去30天到过去60天内发表的文章

<?php
//based on Austin Matzko's code from wp-hackers email list
function filter_where($where = '') {
//posts 30 to 60 days old
$where .= " AND post_date >= '" . date('Y-m-d', strtotime('-60 days')) . "'" . " AND post_date <= '" . date('Y-m-d', strtotime('-30 days')) . "'";
return $where;
}
add_filter('posts_where', 'filter_where');
query_posts($query_string);
?>

===分页参数===
*paged=2 ——显示点击“较早的日志”[[链接]]后出现在第二页中的文章 
*posts_per_page=10 —— 每页所显示的文章数量；若值为-1，显示所有文章。 
*order=ASC —— 按时间顺序显示文章，若值为DESC则按逆向时间顺序显示文章（默认） 

===offset（偏移）参数===
通过offset参数，你可以移除或忽略正常情况下被查询集中的一篇或多篇初始文章。

以下显示最近一篇文章之后的5篇文章：
 query_posts('posts_per_page=5&offset=1');  
===排序参数===
*orderby=author 
*orderby=date 
*orderby=category ——注意：该参数不能用于WordPress 2.8，可能已经被废止 
*orderby=title 
*orderby=modified 
*orderby=menu_order 
*orderby=parent 
*orderby=ID 
*orderby=rand 
*orderby=meta_value —— meta_key=some value语句也应出现在查询参数中 
*orderby=none - no order —— (新增于[http://codex.wordpress.org/Version_2.8 WP 2.8]) 
*orderby=comment_count ——（新增于[http://codex.wordpress.org/Version_2.9 WP 2.9]) 

===顺序参数===
决定以升序或降序排列排序参数
*order=ASC —— 升序，从最低值到最高值 
*order=DESC —— 降序，从最高值到最低值 

===自定义字段参数===
根据自定义[[关键字]]或值检索文章（或页面）。
*meta_key= 
*meta_value= 
*meta_compare= —— 用以测试meta_value=的操作符，默认值为 '='，其它可能的值包括'!='、 '>'、'>='、 '<'或 '<=' 。 
返回关键字为 'color' 且值为'blue'的文章：
 query_posts('meta_key=color&meta_value=blue');   
返回自定义字段关键字为'color'的文章，无论自定义字段值为何：
 query_posts('meta_key=color');   
返回自定义字段值为'color'的文章，无论关键字为何：
 query_posts('meta_value=color');  
返回自定义字段值为'green'的页面，无论自定义字段关键字为何：
 query_posts('post_type=page&meta_value=green');  
返回自定义关键字为'color'、自定义字段值不为'blue'的文章和页面：
 query_posts('post_type=any&meta_key=color&meta_compare=!=&meta_value=blue');  
返回自定义字段关键字为'miles'、自定义字段值小于等于22的文章。注意，字段值99会被看做大于字段值100，因为数据是以字符串形式而不是数字形式存储的。
 query_posts('meta_key=miles&meta_compare=<=&meta_value=22'); 
===联合参数===
你可能已经从上面有些例子中看出来了，可以用&符号连接不同参数，如：
 uery_posts('cat=3&year=2004');  
显示主页上、当前月份发表的、隶属于分类13下的文章：
 if (is_home()) {
 query_posts($query_string . '&cat=13&monthnum=' . date('n',current_time('timestamp')));
 }
在WP 2.3中，以下参数联合会返回同时属于分类1和分类3的两篇文章，以文章标题降序排列：
  query_posts(array('category__and'=>array(1,3),'posts_per_page'=>2,'orderby'=>title,'order'=>DESC));  
在WP 2.3和WP 2.5中，以下参数联合本应返回属于分类1且带有“apples”标签的文章：
 query_posts('cat=1&tag=apples');  
但由于一个bug，代码没能显示出正常结果。详情请见[http://core.trac.wordpress.org/ticket/5433 Ticket #5433]。有一个解决办法：利用+号查找多个标签：
 query_posts('cat=1&tag=apples+apples');  
这就显示出我们希望显示的结果了。

==使用技巧==
设置>阅读中的“博客页面最多显示”参数会影响你的查询结果，要覆盖设置>阅读中的设置，需要在标签中添加'posts_per_page' 参数。例如：
query_posts('category_name=The Category Name&posts_per_page=-1');  //returns ALL from the category  


==相关条目==
*[[Drupal]] 
*[[OBLOG]] 
*[[X-Space]] 
*[[SaBlog-X]] 
*[[Bo-Blog]]

[[category:WordPress中文文档|W]]
[[category:WordPress网站开发|W]]
[[category:WordPress开发文档|W]]