Function Reference/WP Query

WP_Query角色

WP_Query is a class defined in wp-includes/query.php that deals with the intricacies of a request to a WordPress blog. The wp-blog-header.php (or the WP class in Version 2.0) gives the $wp_query object information defining the current request, and then $wp_query determines what type of query it's dealing with (category archive? dated archive? feed? search?), and fetches the requested posts. It retains a lot of information on the request, which can be pulled at a later date.

WP_Query是wp-includes/query.php定义的class，处理WordPress博客上错综复杂的查询。wp-blog-header.php（或者2.0版本中的WP class）向$wp_query object提供信息，定义当前的查询，然后$wp_query决定处理的查询的类型（类别归档？日期归档？feed?搜索？），并且获得查询的文章。查询上仍然留有许多信息，可以稍后处理。

方法和属性

This is the formal documentation of WP_Query. You shouldn't alter the properties directly, but instead use the methods to interact with them. Also see [[WordPress:#Interacting_with_WP_Query|Interacting with WP_Query]] for some useful functions that avoid the need to mess around with class internals and global variables.

这是WP_Query正式的文档。你不能够直接地更改属性，但是可以使用一些方法，处理属性。也看看[[WordPress:#Interacting_with_WP_Query|Interacting with WP_Query]]上的一些函数，避免混乱class internals和全局变数。

属性

$query

Holds the query string that was passed to the $wp_query object by wp-blog-header.php (or the WP class in Version 2.0). For information on the construction of this query string (in WP1.5 with wp-blog-header.php - the following link is fairly outdated now), see WordPress Code Flow.

$query

拥有wp-blog-header.php（或者2.0版本中的WP class）传递给$wp_query object的字符串。关于这个查询字符串结构的信息（对于WP1.5中的wp-blog-header.php-下面的链接已经过时了），请看看WordPress Code Flow。

$query_vars

An associative array containing the dissected $query: an array of the query variables and their respective values.

$query_vars

一个联合的数组，包含分开的$query：一组查询变数及其相关的参数值。

$queried_object

Applicable if the request is a category, author, permalink or Page. Holds information on the requested category, author, post or Page. 如果查询类别，作者，permalink或者网页，

$queried_object

就可以适用。将信息放置在被请求的类别，作者，文章或者网页上。

$queried_object_id

Simply holds the ID of the above property.

$queried_object_id

Simply拥有以上属性的ID。

$posts

Gets filled with the requested posts from the database.

$posts

由数据库中的文章填满。

$post_count

The number of posts being displayed.

$current_post

(available during WordPress:The Loop) Index of the post currently being displayed.

$post_count

显示的文章数目。

$current_post

(在The Loop时，可以得到)显示当前显示的文章的索引。

$post

(available during WordPress:The Loop) The post currently being displayed. >(在The Loop时，可以得到) 显示当前显示的文章

$post

$is_single, $is_page, $is_archive, $is_preview, $is_date, $is_year, $is_month, $is_time, $is_author, $is_category, $is_tag, $is_tax, $is_search, $is_feed, $is_comment_feed, $is_trackback, $is_home, $is_404, $is_comments_popup, $is_admin, $is_attachment, $is_singular, $is_robots, $is_posts_page, $is_paged

Booleans dictating what type of request this is. For example, the first three represent 'is it a permalink?', 'is it a Page?', 'is it any type of archive page?', respectively.

$post

$is_single, $is_page, $is_archive, $is_preview, $is_date, $is_year, $is_month, $is_time, $is_author, $is_category, $is_tag, $is_tax, $is_search, $is_feed, $is_comment_feed, $is_trackback, $is_home, $is_404, $is_comments_popup, $is_admin, $is_attachment, $is_singular, $is_robots, $is_posts_page, $is_paged

Booleans指定这是哪种方式的查询。例如，前三个查询分别代表'这是不是个permalink?', '这是不是个网页?', '这是不是什么类型的归档网页?'。

Methods

方法

(An ampersand (&) before a method name indicates it returns by reference.)

(方法名称之前有一个&符号(&) 指出会返回方法供参考。)

init()

Initialise the object, set all properties to null, zero or false.

init()

初始化object，将所有的属性设置为空，零或者错误的。

parse_query($query)

Takes a query string defining the request, parses it and populates all properties apart from $posts, $post_count, $post and $current_post.

parse_query($query)

：获得定义查询的字符串，解析这个字符串并且配置除了$posts, $post_count, $post and $current_post之外的所有属性。

parse_query_vars()

Reparse the old query string.

parse_query_vars()

重新解析旧的查询字符串。

get($query_var)

Get a named query variable.

get($query_var)

得到指定的查询变数。

set($query_var, $value)

Set a named query variable to a specific value.

set($query_var, $value)

将指定的查询字符串设置为一个特定的值。

&get_posts()

Fetch and return the requested posts from the database. Also populate $posts and $post_count.

&get_posts()

Fetch and return the requested posts from the database. Also populate $posts and $post_count.

：从数据库中获得并且返回查询的文章。同时规定$posts 和$post_count。

next_post()

(to be used when in WordPress:The Loop) Advance onto the next post in $posts. Increment $current_post and set $post.

next_post()

(在 The Loop时，使用) 进入$posts中的下一篇文章。增加 $current_post并且设置 $post。

the_post()

(to be used when in WordPress:The Loop) Advance onto the next post, and set the global $post variable.

the_post()

(在 The Loop时，使用) 进入下一篇文章，并且设置全局$post 变量。

have_posts()

(to be used when in WordPress:The Loop, or just before The Loop) Determine if we have posts remaining to be displayed.

have_posts()

(在 The Loop时，使用或者在Loop之前使用) 决定我们是否还有需要显示的文章。

rewind_posts()

Reset $current_post and $post.

&query($query)

Call parse_query() and get_posts(). Return the results of get_posts().

get_queried_object()

Set $queried_object if it's not already set and return it.

get_queried_object_id()

Set $queried_object_id if it's not already set and return it.

WP_Query($query = '') (constructor)

If you provide a query string, call query() with it.

rewind_posts()

重新设置 $current_post 和 $post。

&query($query)

调用 parse_query() 和 get_posts()。返回get_posts()的结果。

get_queried_object()

如果$queried_object 还没有设置，设置$queried_object并且返回$queried_object。

get_queried_object_id()

如果$queried_object_id还没有设置，设置$queried_object_id并且返回。

WP_Query($query = '') (constructor)

如果你提供了查询字符串，用这个字符串调用query() 。

Interacting with WP_Query

与 WP_Query相结合

Most of the time you can find the information you want without actually dealing with the class internals and globals variables. There are a whole bunch of functions that you can call from anywhere that will enable you to get the information you need.

大多数时候，你能够找到你想要的信息，不需要真正地处理class internals和全局变数。你可以从任何地方调用许多函数，这些函数能够使你得到你需要的信息。

There are two main scenarios you might want to use WP_Query in. The first is to find out what type of request WordPress is currently dealing with. The $is_* properties are designed to hold this information: use the WordPress:Conditional Tags to interact here. This is the more common scenario to plugin writers (the second normally applies to theme writers).

你可能想将WP_Query用于两个主要的环节中。首先要找出WordPress当前处理的是那种类型的请求。$is_*属性是用来保存这个信息的：使用条件式标签影响这里。这是插件作者更常用的scenario（第二个一般用于主题作者）。

The second is during WordPress:The Loop. WP_Query provides numerous functions for common tasks within The Loop. To begin with, have_posts(), which calls $wp_query->have_posts(), is called to see if there are any posts to show. If there are, a while loop is begun, using have_posts() as the condition. This will iterate around as long as there are posts to show. In each iteration, the_post(), which calls $wp_query->the_post() is called, setting up internal variables within $wp_query and the global $post variable (which the WordPress:Template Tags rely on), as above. These are the functions you should use when writing a theme file that needs a loop. See also WordPress:The Loop and WordPress:The Loop in Action for more information.

The second is during WordPress:The Loop. WP_Query为Loop内一些常见的函数提供了许多函数。首先，调用$wp_query->have_posts()的have_posts()，得到了调用，核查是否要显示任何文章。如果要显示文章，就会开始while loop，使用have_posts()作为条件。只要有文章显示，就会重复while loop。在每一次重复的过程中，调用$wp_query->the_post()的the_post()得到了调用，设置了$wp_query内的内部变数和全局$post变数（模板标签依赖于这些变数）。编写需要loop的主题文件的时候，你就需要使用这些函数。更多的信息，请看看The Loop 和运转的Loop。