WordPress WP_Query参数详解_WordPress教程

Author Parameters Author Parameters

Show posts associated with certain author.

author (int) – use author id.
author_name (string) – use ‘user_nicename‘ – NOT name.
author__in (array) – use author id (available since version 3.7).
author__not_in (array) – use author id (available since version 3.7).

Show Posts for one Author

Display posts by author, using author id:

$query = new WP_Query( array( 'author' => 123 ) );

Display posts by author, using author ‘user_nicename‘:

$query = new WP_Query( array( 'author_name' => 'rami' ) );

Show Posts From Several Authors

Display posts from several specific authors:

$query = new WP_Query( array( 'author' => '2,6,17,38' ) );

Exclude Posts Belonging to an Author

Display all posts except those from an author(singular) by prefixing its id with a ‘-‘ (minus) sign:

$query = new WP_Query( array( 'author' => -12 ) );

Multiple Author Handling

Display posts from multiple authors:

$query = new WP_Query( array( 'author__in' => array( 2, 6 ) ) );

You can also exclude multiple author this way:

$query = new WP_Query( array( 'author__not_in' => array( 2, 6 ) ) );

Top ↑

Category Parameters Category Parameters

Show posts associated with certain categories.

cat (int) – use category id.
category_name (string) – use category slug.
category__and (array) – use category id.
category__in (array) – use category id.
category__not_in (array) – use category id.

Display posts that have one category (and any children of that category), using category id:

$query = new WP_Query( array( 'cat' => 4 ) );

Display posts that have this category (and any children of that category), using category slug:

$query = new WP_Query( array( 'category_name' => 'staff' ) );

Display posts that have this category (not children of that category), using category id:

$query = new WP_Query( array( 'category__in' => 4 ) );

Display posts that have several categories, using category id:

$query = new WP_Query( array( 'cat' => '2,6,17,38' ) );

Display posts that have these categories, using category slug:

$query = new WP_Query( array( 'category_name' => 'staff,news' ) );

Display posts that have “all” of these categories:

$query = new WP_Query( array( 'category_name' => 'staff+news' ) );

Display all posts except those from a category by prefixing its id with a ‘-‘ (minus) sign.

$query = new WP_Query( array( 'cat' => '-12,-34,-56' ) );

Display posts that are in multiple categories. This shows posts that are in both categories 2 and 6:

$query = new WP_Query( array( 'category__and' => array( 2, 6 ) ) );

To display posts from either category 2 OR 6, you could use cat as mentioned above, or by using category__in (note this does not show posts from any children of these categories):

$query = new WP_Query( array( 'category__in' => array( 2, 6 ) ) );

You can also exclude multiple categories this way:

$query = new WP_Query( array( 'category__not_in' => array( 2, 6 ) ) );

Top ↑

Tag Parameters Tag Parameters

Show posts associated with certain tags.

tag (string) – use tag slug.
tag_id (int) – use tag id.
tag__and (array) – use tag ids.
tag__in (array) – use tag ids.
tag__not_in (array) – use tag ids.
tag_slug__and (array) – use tag slugs.
tag_slug__in (array) – use tag slugs.

Display posts that have one tag, using tag slug:

$query = new WP_Query( array( 'tag' => 'cooking' ) );

Display posts that have this tag, using tag id:

$query = new WP_Query( array( 'tag_id' => 13 ) );

Display posts that have “either” of these tags:

$query = new WP_Query( array( 'tag' => 'bread,baking' ) );

Display posts that have “all” of these tags:

$query = new WP_Query( array( 'tag' => 'bread+baking+recipe' ) );

Display posts that are tagged with both tag id 37 and tag id 47:

$query = new WP_Query( array( 'tag__and' => array( 37, 47 ) ) );

To display posts from either tag id 37 or 47, you could use tag as mentioned above, or explicitly specify by using tag__in:

$query = new WP_Query( array( 'tag__in' => array( 37, 47 ) ) );

Display posts that do not have any of the two tag ids 37 and 47:

$query = new WP_Query( array( 'tag__not_in' => array( 37, 47 ) ) );

The tag_slug__in and tag_slug__and behave much the same, except match against the tag’s slug.

Top ↑

Taxonomy Parameters Taxonomy Parameters

Show posts associated with certain taxonomy.

{tax} (string) – use taxonomy slug. (Deprecated since version 3.1 in favor of ‘tax_query‘).
tax_query (array) – use taxonomy parameters (available since version 3.1).
- relation (string) – The logical relationship between each inner taxonomy array when there is more than one. Possible values are ‘AND’, ‘OR’. Do not use with a single inner taxonomy array.
  - taxonomy (string) – Taxonomy.
  - field (string) – Select taxonomy term by. Possible values are ‘term_id’, ‘name’, ‘slug’ or ‘term_taxonomy_id’. Default value is ‘term_id’.
  - terms (int/string/array) – Taxonomy term(s).
  - include_children (boolean) – Whether or not to include children for hierarchical taxonomies. Defaults to true.
  - operator (string) – Operator to test. Possible values are ‘IN’, ‘NOT IN’, ‘AND’, ‘EXISTS’ and ‘NOT EXISTS’. Default value is ‘IN’.

Important Note: tax_query takes an array of tax query arguments arrays (it takes an array of arrays).
This construct allows you to query multiple taxonomies by using the relation parameter in the first (outer) array to describe the boolean relationship between the taxonomy arrays.

Simple Taxonomy Query:

Display posts tagged with bob, under people custom taxonomy:

$args = array(
    'post_type' => 'post',
    'tax_query' => array(
        array(
            'taxonomy' => 'people',
            'field'    => 'slug',
            'terms'    => 'bob',
        ),
    ),
);
$query = new WP_Query( $args );

Multiple Taxonomy Handling:

Display posts from several custom taxonomies:

$args = array(
    'post_type' => 'post',
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'movie_genre',
            'field'    => 'slug',
            'terms'    => array( 'action', 'comedy' ),
        ),
        array(
            'taxonomy' => 'actor',
            'field'    => 'term_id',
            'terms'    => array( 103, 115, 206 ),
            'operator' => 'NOT IN',
        ),
    ),
);
$query = new WP_Query( $args );

Expand full source code

Display posts that are in the quotes category OR have the quote post format:

$args = array(
    'post_type' => 'post',
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'category',
            'field'    => 'slug',
            'terms'    => array( 'quotes' ),
        ),
        array(
            'taxonomy' => 'post_format',
            'field'    => 'slug',
            'terms'    => array( 'post-format-quote' ),
        ),
    ),
);
$query = new WP_Query( $args );

Expand full source code

Nested Taxonomy Handling:

The 'tax_query' clauses can be nested, to create more complex queries. Example: Display posts that are in the quotes category OR both have the quote post format AND are in the wisdom category:

$args = array(
    'post_type' => 'post',
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'category',
            'field'    => 'slug',
            'terms'    => array( 'quotes' ),
        ),
        array(
                        'relation' => 'AND',
                        array(
                    'taxonomy' => 'post_format',
                    'field'    => 'slug',
                    'terms'    => array( 'post-format-quote' ),
                        ),
                        array(
                                'taxonomy' => 'category',
                                'field'    => 'slug',
                                'terms'    => array( 'wisdom' ),
                        ),
        ),
    ),
);
$query = new WP_Query( $args );

Expand full source code

Top ↑

Search Parameters Search Parameters

Show posts based on a keyword search.

s (string) – Search keyword.

Show Posts based on a keyword search

$query = new WP_Query( array( 's' => 'keyword' ) );

Prepending a term with a hyphen will exclude posts matching that term. Eg, 'pillow -sofa' will return posts containing ‘pillow’ but not ‘sofa’ (available since Version 4.4).

Top ↑

Post & Page Parameters Post & Page Parameters

Display content based on post and page parameters. Remember that default post_type is only set to display posts but not pages.

p (int) – use post id.
name (string) – use post slug.
page_id (int) – use page id.
pagename (string) – use page slug.
post_parent (int) – use page id to return only child pages. Set to 0 to return only top-level entries.
post_parent__in (array) – use post ids. Specify posts whose parent is in an array. (available since version 3.6)
post_parent__not_in (array) – use post ids. Specify posts whose parent is not in an array. (available since version 3.6)
post__in (array) – use post ids. Specify posts to retrieve. ATTENTION If you use sticky posts, they will be included (prepended!) in the posts you retrieve whether you want it or not. To suppress this behaviour use ignore_sticky_posts.
post__not_in (array) – use post ids. Specify post NOT to retrieve.
post_name__in (array) – use post slugs. Specify posts to retrieve. (Will be available in version 4.4)

NOTE: Ticket #28099: Passing an empty array to post__in will return has_posts() as true (and all posts will be returned). Logic should be used before hand to determine if WP_Query should be used in the event that the array being passed to post__in is empty.

Display post by ID:

$query = new WP_Query( array( 'p' => 7 ) );

Display page by ID:

$query = new WP_Query( array( 'page_id' => 7 ) );

Show post/page by slug

$query = new WP_Query( array( 'name' => 'about-my-life' ) );

Display page by slug:

$query = new WP_Query( array( 'pagename' => 'contact' ) );

Display child page using the slug of the parent and the child page, separated by a slash (e.g. ‘parent_slug/child_slug’):

$query = new WP_Query( array( 'pagename' => 'contact_us/canada' ) );

Display child pages using parent page ID:

$query = new WP_Query( array( 'post_parent' => 93 ) );

Display only top-level pages, exclude all child pages:

$query = new WP_Query( array( 'post_parent' => 0 ) );

Display posts whose parent is in an array:

$query = new WP_Query( array( 'post_parent__in' => array( 2, 5, 12, 14, 20 ) ) );

Display only the specific posts:

$query = new WP_Query( array( 'post_type' => 'page', 'post__in' => array( 2, 5, 12, 14, 20 ) ) );

Display all posts but NOT the specified ones:

$query = new WP_Query( array( 'post_type' => 'post', 'post__not_in' => array( 2, 5, 12, 14, 20 ) ) );

Note: you cannot combine post__in and post__not_in in the same query.

Also note that using a string containing a comma separated list will not work here. If you’re passing a variable, make sure it’s a proper array of integer values:

// This will NOT work
$exclude_ids = '1,2,3';
$query = new WP_Query( array( 'post__not_in' => array( $exclude_ids ) ) );
// This WILL work
$exclude_ids = array( 1, 2, 3 );
$query = new WP_Query( array( 'post__not_in' => $exclude_ids ) );

Top ↑

Password Parameters Password Parameters

Show content based on post and page parameters. Remember that default post_type is only set to display posts but not pages.

has_password (bool) – true for posts with passwords ; false for posts without passwords ; null for all posts with and without passwords (available since version 3.9).
post_password (string) – show posts with a particular password (available since version 3.9)

Display only password protected posts:

$query = new WP_Query( array( 'has_password' => true ) );

Display only posts without passwords:

$query = new WP_Query( array( 'has_password' => false ) );

Display only posts with and without passwords:

$query = new WP_Query( array( 'has_password' => null ) );

Display posts with a particular password:

$query = new WP_Query( array( 'post_password' => 'zxcvbn' ) );

Top ↑

Post Type Parameters Post Type Parameters

Show posts associated with certain type.

post_type (string / array) – use post types. Retrieves posts by post types, default value is ‘post‘. If ‘tax_query‘ is set for a query, the default value becomes ‘any‘;
- ‘post‘ – a post.
- ‘page‘ – a page.
- ‘revision‘ – a revision.
- ‘attachment‘ – an attachment. Whilst the default WP_Query post_status is ‘publish’, attachments have a default post_status of ‘inherit’. This means no attachments will be returned unless you also explicitly set post_status to ‘inherit’ or ‘any’. See Status parameters section below.
- ‘nav_menu_item‘ – a navigation menu item
- ‘any‘ – retrieves any type except revisions and types with ‘exclude_from_search’ set to true.
  ** Custom Post Types (e.g. movies)

Display only pages:

$query = new WP_Query( array( 'post_type' => 'page' ) );

Display ‘any‘ post type (retrieves any type except revisions and types with ‘exclude_from_search’ set to TRUE):

$query = new WP_Query( array( 'post_type' => 'any' ) );

Display multiple post types, including custom post types:

$args = array(
    'post_type' => array( 'post', 'page', 'movie', 'book' )
);
$query = new WP_Query( $args );

Status Parameters

Show posts associated with certain post status.

post_status (string / array) – use post status. Retrieves posts by post status. Default value is ‘publish‘, but if the user is logged in, ‘private‘ is added. Public custom post statuses are also included by default. And if the query is run in an admin context (administration area or AJAX call), protected statuses are added too. By default protected statuses are ‘future‘, ‘draft‘ and ‘pending‘.
- ‘publish‘ – a published post or page.
- ‘pending‘ – post is pending review.
- ‘draft‘ – a post in draft status.
- ‘auto-draft‘ – a newly created post, with no content.
- ‘future‘ – a post to publish in the future.
- ‘private‘ – not visible to users who are not logged in.
- ‘inherit‘ – a revision. see get_children().
- ‘trash‘ – post is in trashbin (available since version 2.9).
- ‘any‘ – retrieves any status except those from post statuses with ‘exclude_from_search’ set to true (i.e. trash and auto-draft).

Display only posts with the ‘draft‘ status:

$query = new WP_Query( array( 'post_status' => 'draft' ) );

Display multiple post status:

$args = array(
    'post_status' => array( 'pending', 'draft', 'future' )
);
$query = new WP_Query( $args );

Display all attachments:

$args = array(
    'post_status' => 'any',
    'post_type'   => 'attachment'
);
$query = new WP_Query( $args );

Comment Parameters

Since Version 4.9 Introduced the `$comment_count` parameter. It can be either an Integer or an Array.

comment_count (int) – The amount of comments your CPT has to have ( Search operator will do a ‘=’ operation )
comment_count (Array) – If comment_count is an array, it should have two arguments:
- ‘value‘ – The amount of comments your post has to have when comparing
- ‘compare‘ – The search operator. Possible values are ‘=’, ‘!=’, ‘>’, ‘>=’, ‘<', '<='. Default value is '='.

Display posts with with 20 comments:

$args = array(
    'post_type' => 'post',
    'comment_count' => 20,
    )
);
$query = new WP_Query( $args );

Display posts with with 25 comments or more:

$args = array(
    'post_type' => 'post',
    'comment_count' => array(
        'value' => 25,
        'compare' => '>=',
    )
);
$query = new WP_Query( $args );

Pagination Parameters

nopaging (boolean) – show all posts or use pagination. Default value is ‘false’, use paging.
posts_per_page (int) – number of post to show per page (available since version 2.1, replaced showposts parameter). Use 'posts_per_page'=>-1 to show all posts (the 'offset' parameter is ignored with a -1 value). Set the ‘paged’ parameter if pagination is off after using this parameter. Note: if the query is in a feed, wordpress overwrites this parameter with the stored ‘posts_per_rss’ option. To reimpose the limit, try using the ‘post_limits’ filter, or filter ‘pre_option_posts_per_rss’ and return -1
posts_per_archive_page (int) – number of posts to show per page – on archive pages only. Over-rides posts_per_page and showposts on pages where is_archive() or is_search() would be true.
offset (int) – number of post to displace or pass over. Warning: Setting the offset parameter overrides/ignores the paged parameter and breaks pagination. The 'offset' parameter is ignored when 'posts_per_page'=>-1 (show all posts) is used.
paged (int) – number of page. Show the posts that would normally show up just on page X when using the “Older Entries” link.
page (int) – number of page for a static front page. Show the posts that would normally show up just on page X of a Static Front Page.
ignore_sticky_posts (boolean) – ignore post stickiness (available since version 3.1, replaced caller_get_posts parameter). false (default): move sticky posts to the start of the set. true: do not move sticky posts to the start of the set.

Display x posts per page:

$query = new WP_Query( array( 'posts_per_page' => 3 ) );

Display all posts in one page:

$query = new WP_Query( array( 'posts_per_page' => -1 ) );

Display all posts by disabling pagination:

$query = new WP_Query( array( 'nopaging' => true ) );

Display posts from the 4th one:

$query = new WP_Query( array( 'offset' => 3 ) );

Display 5 posts per page which follow the 3 most recent posts:

$query = new WP_Query( array( 'posts_per_page' => 5, 'offset' => 3 ) );

Display posts from page number x:

$query = new WP_Query( array( 'paged' => 6 ) );

Display posts from current page:

$query = new WP_Query( array( 'paged' => get_query_var( 'paged' ) ) );

Display posts from the current page and set the ‘paged’ parameter to 1 when the query variable is not set (first page).

$paged = ( get_query_var('paged') ) ? get_query_var('paged') : 1;
$query = new WP_Query( array( 'paged' => $paged ) );

Pagination Note: Use get_query_var('page'); if you want your query to work in a page template that you’ve set as your static front page. The query variable ‘page’ also holds the pagenumber for a single paginated Post or Page that includes the  quicktag in the post content.

Display posts from current page on a static front page:

$paged = ( get_query_var('page') ) ? get_query_var('page') : 1;
$query = new WP_Query( array( 'paged' => $paged ) );

Display just the first sticky post:

$sticky = get_option( 'sticky_posts' );
$query = new WP_Query( array( 'p' => $sticky[0] ) );

Display just the first sticky post, if none return the last post published:

$args = array(
    'posts_per_page'      => 1,
    'post__in'            => get_option( 'sticky_posts' ),
    'ignore_sticky_posts' => 1,
);
$query = new WP_Query( $args );

Display just the first sticky post, if none return nothing:

$sticky = get_option( 'sticky_posts' );
$args = array(
    'posts_per_page'      => 1,
    'post__in'            => $sticky,
    'ignore_sticky_posts' => 1,
);
$query = new WP_Query( $args );
if ( $sticky[0] ) {
    // insert here your stuff...
}

Exclude all sticky posts from the query:

$query = new WP_Query( array( 'post__not_in' => get_option( 'sticky_posts' ) ) );

Exclude sticky posts from a category:

Return ALL posts within the category, but don’t show sticky posts at the top. The ‘sticky posts’ will still show in their natural position (e.g. by date):

$query = new WP_Query( array( 'ignore_sticky_posts' => 1, 'posts_per_page' => 3, 'cat' => 6 );

Exclude sticky posts from a category:

Return posts within the category, but exclude sticky posts completely, and adhere to paging rules:

$paged = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;
$sticky = get_option( 'sticky_posts' );
$args = array(
    'cat'                 => 3,
    'ignore_sticky_posts' => 1,
    'post__not_in'        => $sticky,
    'paged'               => $paged,
);
$query = new WP_Query( $args );

Top ↑

Order & Orderby Parameters Order & Orderby Parameters

Sort retrieved posts.

order (string | array) – Designates the ascending or descending order of the ‘orderby‘ parameter. Defaults to ‘DESC’. An array can be used for multiple order/orderby sets.
- ‘ASC‘ – ascending order from lowest to highest values (1, 2, 3; a, b, c).
- ‘DESC‘ – descending order from highest to lowest values (3, 2, 1; c, b, a).
orderby (string | array) – Sort retrieved posts by parameter. Defaults to ‘date (post_date)’. One or more options can be passed.
- ‘none‘ – No order (available since version 2.8).
- ‘ID‘ – Order by post id. Note the capitalization.
- ‘author‘ – Order by author.
- ‘title‘ – Order by title.
- ‘name‘ – Order by post name (post slug).
- ‘type‘ – Order by post type (available since version 4.0).
- ‘date‘ – Order by date.
- ‘modified‘ – Order by last modified date.
- ‘parent‘ – Order by post/page parent id.
- ‘rand‘ – Random order.
- ‘comment_count‘ – Order by number of comments (available since version 2.9).
- ‘relevance‘ – Order by search terms in the following order: First, whether the entire sentence is matched. Second, if all the search terms are within the titles. Third, if any of the search terms appear in the titles. And, fourth, if the full sentence appears in the contents.
- ‘menu_order‘ – Order by Page Order. Used most often for pages (Order field in the Edit Page Attributes box) and for attachments (the integer fields in the Insert / Upload Media Gallery dialog), but could be used for any post type with distinct ‘menu_order‘ values (they all default to 0).
- ‘meta_value‘ – Note that a ‘meta_key=keyname‘ must also be present in the query. Note also that the sorting will be alphabetical which is fine for strings (i.e. words), but can be unexpected for numbers (e.g. 1, 3, 34, 4, 56, 6, etc, rather than 1, 3, 4, 6, 34, 56 as you might naturally expect). Use ‘meta_value_num‘ instead for numeric values. You may also specify ‘meta_type‘ if you want to cast the meta value as a specific type. Possible values are ‘NUMERIC’, ‘BINARY’, ‘CHAR’, ‘DATE’, ‘DATETIME’, ‘DECIMAL’, ‘SIGNED’, ‘TIME’, ‘UNSIGNED’, same as in ‘$meta_query‘. When using ‘meta_type’ you can also use ‘meta_value_*’ accordingly. For example, when using DATETIME as ‘meta_type’ you can use ‘meta_value_datetime’ to define order structure.
- ‘meta_value_num‘ – Order by numeric meta value (available since version 2.8). Also note that a ‘meta_key=keyname‘ must also be present in the query. This value allows for numerical sorting as noted above in ‘meta_value‘.
- ‘post__in‘ – Preserve post ID order given in the post__in array (available since version 3.5). Note – the value of the order parameter does not change the resulting sort order.
- ‘post_name__in‘ – Preserve post slug order given in the ‘post_name__in’ array (available since Version 4.6). Note – the value of the order parameter does not change the resulting sort order.
- ‘post_parent__in‘ -Preserve post parent order given in the ‘post_parent__in’ array (available since Version 4.6). Note – the value of the order parameter does not change the resulting sort order.

Display posts sorted by post ‘title’ in a descending order:

$args = array(
    'orderby' => 'title',
    'order'   => 'DESC',
);
$query = new WP_Query( $args );

Display posts sorted by ‘menu_order’ with a fallback to post ‘title’, in a descending order:

$args = array(
    'orderby' => 'menu_order title',
    'order'   => 'DESC',
);
$query = new WP_Query( $args );

Display one random post:

$args = array(
    'orderby'        => 'rand',
    'posts_per_page' => '1',
);
$query = new WP_Query( $args );

Display posts ordered by comment count (popularity):

$args = array(
    'orderby' => 'comment_count'
);
$query = new WP_Query( $args );

Display posts with ‘Product’ type ordered by ‘Price’ custom field:

$args = array(
    'post_type' => 'product',
    'orderby'   => 'meta_value_num',
    'meta_key'  => 'price',
);
$query = new WP_Query( $args );

Display pages ordered by ‘title’ and ‘menu_order’. (title is dominant):

$args = array(
    'post_type' => 'page',
    'orderby'   => 'title menu_order',
    'order'     => 'ASC',
);
$query = new WP_Query( $args );

Display pages ordered by ‘title’ and ‘menu_order’ with different sort orders (ASC/DESC) (available since version 4.0):

$args = array(
    'orderby' => array( 'title' => 'DESC', 'menu_order' => 'ASC' )
);
$query = new WP_Query( $args );

Related article: A more powerful ORDER BY in WordPress 4.0.

Mulitiple orderby/order pairs

$args = array(
    'orderby'  => array( 'meta_value_num' => 'DESC', 'title' => 'ASC' ),
    'meta_key' => 'age'
);
$query = new WP_Query( $args );

‘orderby’ with ‘meta_value’ and custom post type

Display posts of type ‘my_custom_post_type’, ordered by ‘age’, and filtered to show only ages 3 and 4 (using meta_query).

$args = array(
    'post_type'  => 'my_custom_post_type',
    'meta_key'   => 'age',
    'orderby'    => 'meta_value_num',
    'order'      => 'ASC',
    'meta_query' => array(
        array(
            'key'     => 'age',
            'value'   => array( 3, 4 ),
            'compare' => 'IN',
        ),
    ),
);
$query = new WP_Query( $args );

Expand full source code

‘orderby’ with multiple ‘meta_key’s

If you wish to order by two different pieces of postmeta (for example, City first and State second), you need to combine and link your meta query to your orderby array using ‘named meta queries’. See the example below:

$q = new WP_Query( array(
    'meta_query' => array(
        'relation' => 'AND',
        'state_clause' => array(
            'key' => 'state',
            'value' => 'Wisconsin',
        ),
        'city_clause' => array(
            'key' => 'city',
            'compare' => 'EXISTS',
        ), 
    ),
    'orderby' => array( 
        'city_clause' => 'ASC',
        'state_clause' => 'DESC',
    ),
) );

Collapse full source code

(props to cybmeta on WPSE for this example).

Top ↑

Date Parameters Date Parameters

Show posts associated with a certain time and date period.

year (int) – 4 digit year (e.g. 2011).
monthnum (int) – Month number (from 1 to 12).
w (int) – Week of the year (from 0 to 53). Uses MySQL WEEK command. The mode is dependent on the “start_of_week” option.
day (int) – Day of the month (from 1 to 31).
hour (int) – Hour (from 0 to 23).
minute (int) – Minute (from 0 to 60).
second (int) – Second (0 to 60).
m (int) – YearMonth (For e.g.: 201307).
date_query (array) – Date parameters (available since version 3.7).
- year (int) – 4 digit year (e.g. 2011).
- month (int) – Month number (from 1 to 12).
- week (int) – Week of the year (from 0 to 53).
- day (int) – Day of the month (from 1 to 31).
- hour (int) – Hour (from 0 to 23).
- minute (int) – Minute (from 0 to 59).
- second (int) – Second (0 to 59).
- after (string/array) – Date to retrieve posts after. Accepts strtotime()-compatible string, or array of ‘year’, ‘month’, ‘day’ values:
  - year (string) Accepts any four-digit year. Default is empty.
  - month (string) The month of the year. Accepts numbers 1-12. Default: 12.
  - day (string) The day of the month. Accepts numbers 1-31. Default: last day of month.
- before (string/array) – Date to retrieve posts before. Accepts strtotime()-compatible string, or array of ‘year’, ‘month’, ‘day’ values:
  - year (string) Accepts any four-digit year. Default is empty.
  - month (string) The month of the year. Accepts numbers 1-12. Default: 1.
  - day (string) The day of the month. Accepts numbers 1-31. Default: 1.
- inclusive (boolean) – For after/before, whether exact value should be matched or not’.
- compare (string) – See WP_Date_Query::get_compare().
- column (string) – Posts column to query against. Default: ‘post_date’.
- relation (string) – OR or AND, how the sub-arrays should be compared. Default: AND.

Returns posts dated December 12, 2012:

$query = new WP_Query( 'year=2012&monthnum=12&day=12' );

or:

$args = array(
    'date_query' => array(
        array(
            'year'  => 2012,
            'month' => 12,
            'day'   => 12,
        ),
    ),
);
$query = new WP_Query( $args );

Returns posts for today:

$today = getdate();
$query = new WP_Query( 'year=' . $today['year'] . '&monthnum=' . $today['mon'] . '&day=' . $today['mday'] );

or:

$today = getdate();
$args = array(
    'date_query' => array(
        array(
            'year'  => $today['year'],
            'month' => $today['mon'],
            'day'   => $today['mday'],
        ),
    ),
);
$query = new WP_Query( $args );

Returns posts for this week:

$week = date( 'W' );
$year = date( 'Y' );
$query = new WP_Query( 'year=' . $year . '&w=' . $week );

or:

$args = array(
    'date_query' => array(
        array(
            'year' => date( 'Y' ),
            'week' => date( 'W' ),
        ),
    ),
);
$query = new WP_Query( $args );

Return posts between 9AM to 5PM on weekdays

$args = array(
    'date_query' => array(
        array(
            'hour'      => 9,
            'compare'   => '>=',
        ),
        array(
            'hour'      => 17,
            'compare'   => '<=',
        ),
        array(
            'dayofweek' => array( 2, 6 ),
            'compare'   => 'BETWEEN',
        ),
    ),
    'posts_per_page' => -1,
);
$query = new WP_Query( $args );

Expand full source code

Return posts from January 1st to February 28th

$args = array(
    'date_query' => array(
        array(
            'after'     => 'January 1st, 2013',
            'before'    => array(
                'year'  => 2013,
                'month' => 2,
                'day'   => 28,
            ),
            'inclusive' => true,
        ),
    ),
    'posts_per_page' => -1,
);
$query = new WP_Query( $args );

Expand full source code

Note that if a strtotime()-compatible string with just a date was passed in the before parameter, this will be converted to 00:00:00 on that date. In this case, even if inclusive was set to true, the date would not be included in the query. If you want a before date to be inclusive, include the time as well, such as 'before' => '2013-02-28 23:59:59', or use the array format, which is adjusted automatically if inclusive is set.

Return posts made over a year ago but modified in the past month

$args = array(
    'date_query' => array(
        array(
            'column' => 'post_date_gmt',
            'before' => '1 year ago',
        ),
        array(
            'column' => 'post_modified_gmt',
            'after'  => '1 month ago',
        ),
    ),
    'posts_per_page' => -1,
);
$query = new WP_Query( $args );

Expand full source code

The 'date_query' clauses can be nested, in order to construct complex queries. See Taxonomy Parameters for details on the syntax.

Top ↑

Custom Field (post meta) Parameters Custom Field (post meta) Parameters

Show posts associated with a certain custom field.

This part of the query is parsed by WP_Meta_Query, so check the docs for it as well in case this list of arguments isn’t up to date.

meta_key (string) – Custom field key.
meta_value (string) – Custom field value.
meta_value_num (number) – Custom field value.
meta_compare (string) – Operator to test the ‘meta_value‘. Possible values are ‘=’, ‘!=’, ‘>’, ‘>=’, ‘<‘, ‘<=’, ‘LIKE’, ‘NOT LIKE’, ‘IN’, ‘NOT IN’, ‘BETWEEN’, ‘NOT BETWEEN’, ‘NOT EXISTS’, ‘REGEXP’, ‘NOT REGEXP’ or ‘RLIKE’. Default value is ‘=’.
meta_query (array) – Custom field parameters (available since version 3.1).
- relation (string) – The logical relationship between each inner meta_query array when there is more than one. Possible values are ‘AND’, ‘OR’. Do not use with a single inner meta_query array.

meta_query also contains one or more arrays with the following keys:

key (string) – Custom field key.
value (string|array) – Custom field value. It can be an array only when compare is 'IN', 'NOT IN', 'BETWEEN', or 'NOT BETWEEN'. You don’t have to specify a value when using the 'EXISTS' or 'NOT EXISTS' comparisons in WordPress 3.9 and up.
(Note: Due to bug #23268, value is required for NOT EXISTS comparisons to work correctly prior to 3.9. You must supply some string for the value parameter. An empty string or NULL will NOT work. However, any other string will do the trick and will NOT show up in your SQL when using NOT EXISTS. Need inspiration? How about 'bug #23268'.)
compare (string) – Operator to test. Possible values are ‘=’, ‘!=’, ‘>’, ‘>=’, ‘<‘, ‘<=’, ‘LIKE’, ‘NOT LIKE’, ‘IN’, ‘NOT IN’, ‘BETWEEN’, ‘NOT BETWEEN’, ‘EXISTS’ and ‘NOT EXISTS’. Default value is ‘=’.
type (string) – Custom field type. Possible values are ‘NUMERIC’, ‘BINARY’, ‘CHAR’, ‘DATE’, ‘DATETIME’, ‘DECIMAL’, ‘SIGNED’, ‘TIME’, ‘UNSIGNED’. Default value is ‘CHAR’.

The ‘type’ DATE works with the ‘compare’ value BETWEEN only if the date is stored at the format YYYY-MM-DD and tested with this format.

Important Note: meta_query takes an array of meta query arguments arrays (it takes an array of arrays) – you can see this in the examples below.
This construct allows you to query multiple metadatas by using the relation parameter in the first (outer) array to describe the boolean relationship between the meta queries. Accepted arguments are ‘AND’, ‘OR’. The default is ‘AND’.

Simple Custom Field Query:

Display posts where the custom field key is ‘color’, regardless of the custom field value:

$query = new WP_Query( array( 'meta_key' => 'color' ) );

Display posts where the custom field value is ‘blue’, regardless of the custom field key:

$query = new WP_Query( array( 'meta_value' => 'blue' ) );

Display page where the custom field value is ‘blue’, regardless of the custom field key:

$args = array(
    'meta_value' => 'blue',
    'post_type'  => 'page'
);
$query = new WP_Query( $args );

Display posts where the custom field key is ‘color’ and the custom field value is ‘blue’:

$args = array(
    'meta_key'   => 'color',
    'meta_value' => 'blue'
);
$query = new WP_Query( $args );

Display posts where the custom field key is ‘color’ and the custom field value IS NOT ‘blue’:

$args = array(
    'meta_key'     => 'color',
    'meta_value'   => 'blue',
    'meta_compare' => '!='
);
$query = new WP_Query( $args );

Display posts where the custom field key is a set date and the custom field value is now. Displays only posts which date has not passed.

$args = array(
    'post_type'    => 'event',
    'meta_key'     => 'event_date',
    'meta_value'   => date( "Ymd" ), // change to how "event date" is stored
    'meta_compare' => '>',
);
$query = new WP_Query( $args );

Display ‘product'(s) where the custom field key is ‘price’ and the custom field value that is LESS THAN OR EQUAL TO 22.
By using the ‘meta_value’ parameter the value 99 will be considered greater than 100 as the data are stored as ‘strings’, not ‘numbers’. For number comparison use ‘meta_value_num’.

$args = array(
    'meta_key'     => 'price',
    'meta_value'   => '22',
    'meta_compare' => '<=',
    'post_type'    => 'product'
);
$query = new WP_Query( $args );

Display posts with a custom field value of zero (0), regardless of the custom field key:

$args = array(
    'meta_value' => '_wp_zero_value'
);
$query = new WP_Query( $args );

Display posts from a single custom field:

$args = array(
    'post_type'  => 'product',
    'meta_query' => array(
        array(
            'key'     => 'color',
            'value'   => 'blue',
            'compare' => 'NOT LIKE',
        ),
    ),
);
$query = new WP_Query( $args );

(Note that meta_query expects nested arrays, even if you only have one query.)

Display posts from several custom fields:

$args = array(
    'post_type'  => 'product',
    'meta_query' => array(
        array(
            'key'     => 'color',
            'value'   => 'blue',
            'compare' => 'NOT LIKE',
        ),
        array(
            'key' => 'price',
            'value'   => array( 20, 100 ),
            'type'    => 'numeric',
            'compare' => 'BETWEEN',
        ),
    ),
);
$query = new WP_Query( $args );

Expand full source code

Display posts that have meta key ‘color’ NOT LIKE value ‘blue’ OR meta key ‘price’ with values BETWEEN 20 and 100:

$args = array(
    'post_type'  => 'product',
    'meta_query' => array(
        'relation' => 'OR',
        array(
            'key'     => 'color',
            'value'   => 'blue',
            'compare' => 'NOT LIKE',
        ),
        array(
            'key'     => 'price',
            'value'   => array( 20, 100 ),
            'type'    => 'numeric',
            'compare' => 'BETWEEN',
        ),
    ),
);
$query = new WP_Query( $args );

Expand full source code

The 'meta_query' clauses can be nested in order to construct complex queries. For example, show productss where color=orange OR color=red&size=small translates to the following:

$args = array(
    'post_type'  => 'product',
    'meta_query' => array(
        'relation' => 'OR',
        array(
            'key'     => 'color',
            'value'   => 'orange',
            'compare' => '=',
        ),
                array(
                        'relation' => 'AND',
                        array(
                                'key' => 'color',
                                'value' => 'red',
                                'compare' => '=',
                        ),
                        array(
                                'key' => 'size',
                                'value' => 'small',
                                'compare' => '=',
                        ),
        ),
    ),
);
$query = new WP_Query( $args );

Expand full source code

Top ↑

Permission Parameters Permission Parameters

Show posts if user has the appropriate capability

perm (string) – User permission.

Display published and private posts, if the user has the appropriate capability:

$args = array(
    'post_status' => array( 'publish', 'private' ),
    'perm'        => 'readable',
);
$query = new WP_Query( $args );

Top ↑

Mime Type Parameters Mime Type Parameters

Used with the attachments post type.

post_mime_type (string/array) – Allowed mime types.

Get attachments that are gif images:

Get gif images and remember that by default the attachment’s post_status is set to inherit.

$args = array(
    'post_type'  => 'attachment',
    'post_status'    => 'inherit',
    'post_mime_type' => 'image/gif',
);
$query = new WP_Query( $args );

Get attachments that are not images:

To exclude certain mime types you first need to get all mime types using get_allowed_mime_types() and run a difference between arrays of what you want and the allowed mime types with array_diff().

$unsupported_mimes  = array( 'image/jpeg', 'image/gif', 'image/png', 'image/bmp', 'image/tiff', 'image/x-icon' );
$all_mimes          = get_allowed_mime_types();
$accepted_mimes     = array_diff( $all_mimes, $unsupported_mimes );
$args           = array(
    'post_type'         => 'attachment',
    'post_status'       => 'inherit',
    'post_mime_type'    => $accepted_mimes,
);
$query          = new WP_Query( $query_args );

Top ↑

Caching Parameters Caching Parameters

Stop the data retrieved from being added to the cache.

cache_results (boolean) – Post information cache.
update_post_meta_cache (boolean) – Post meta information cache.
update_post_term_cache (boolean) – Post term information cache.

Show Posts without adding post information to the cache

Display 50 posts, but don’t add post information to the cache:

$args = array(
    'posts_per_page' => 50,
    'cache_results'  => false
);
$query = new WP_Query( $args );

Show Posts without adding post meta information to the cache

Display 50 posts, but don’t add post meta information to the cache:

$args = array(
    'posts_per_page'         => 50,
    'update_post_meta_cache' => false
);
$query = new WP_Query( $args );

Show Posts without adding post term information to the cache

Display 50 posts, but don’t add post term information to the cache:

$args = array(
    'posts_per_page'         => 50,
    'update_post_term_cache' => false
);
$query = new WP_Query( $args );

In general usage you should not need to use these, adding to the cache is the right thing to do, however they may be useful in specific circumstances. An example of such circumstances might be when using a WP_Query to retrieve a list of post titles and URLs to be displayed, but in which no other information about the post will be used and the taxonomy and meta data won’t be needed. By not loading this information, you can save time from the extra unnecessary SQL queries.

Note: If a persistent object cache backend (such as memcached) is used, these flags are set to false by default since there is no need to update the cache every page load when a persistent cache exists.

Top ↑

Return Fields Parameter Return Fields Parameter

Set return values.

fields (string) – Which fields to return. There are three options:
- 'all' – Return all fields (default).
- 'ids' – Return an array of post IDs.
- 'id=>parent' – Return an array of stdClass objects with ID and post_parent properties.

Passing anything else will return all fields (default) – an array of post objects.

Top ↑

Methods Methods

__call — Make private/protected methods readable for backward compatibility.
__construct — Constructor.
__get — Make private properties readable for backward compatibility.
__isset — Make private properties checkable for backward compatibility.
__unset — Make private properties settable for backwards compatibility.
fill_query_vars — Fills in the query variables, which do not exist within the parameter.
generate_postdata — Generate post data.
get — Retrieve query variable.
get_posts — Retrieves an array of posts based on query variables.
get_queried_object — Retrieve queried object.
get_queried_object_id — Retrieve ID of the current queried object.
get_search_stopwords — Retrieve stopwords used when parsing search terms.
have_comments — Whether there are more comments available.
have_posts — Determines whether there are more posts available in the loop.
init — Initiates object properties and sets default values.
init_query_flags — Resets query flags to false.
is_404 — Is the query a 404 (returns no results)?
is_archive — Is the query for an existing archive page?
is_attachment — Is the query for an existing attachment page?
is_author — Is the query for an existing author archive page?
is_category — Is the query for an existing category archive page?
is_comment_feed — Is the query for a comments feed?
is_comments_popup — Whether the current URL is within the comments popup window. — deprecated
is_date — Is the query for an existing date archive?
is_day — Is the query for an existing day archive?
is_embed — Is the query for an embedded post?
is_favicon — Is the query for the favicon.ico file?
is_feed — Is the query for a feed?
is_front_page — Is the query for the front page of the site?
is_home — Is the query for the blog homepage?
is_main_query — Is the query the main query?
is_month — Is the query for an existing month archive?
is_page — Is the query for an existing single page?
is_paged — Is the query for paged result and not for the first page?
is_post_type_archive — Is the query for an existing post type archive page?
is_preview — Is the query for a post or page preview?
is_privacy_policy — Is the query for the Privacy Policy page?
is_robots — Is the query for the robots.txt file?
is_search — Is the query for a search?
is_single — Is the query for an existing single post?
is_singular — Is the query for an existing single post of any post type (post, attachment, page, custom post types)?
is_tag — Is the query for an existing tag archive page?
is_tax — Is the query for an existing custom taxonomy archive page?
is_time — Is the query for a specific time?
is_trackback — Is the query for a trackback endpoint call?
is_year — Is the query for an existing year archive?
lazyload_comment_meta — Lazyload comment meta for comments in the loop. — deprecated
lazyload_term_meta — Lazyload term meta for posts in the loop. — deprecated
next_comment — Iterate current comment index and return WP_Comment object.
next_post — Set up the next post and iterate current post index.
parse_order — Parse an 'order' query variable and cast it to ASC or DESC as necessary.
parse_orderby — Converts the given orderby alias (if allowed) to a properly-prefixed value.
parse_query — Parse a query string and set query type booleans.
parse_query_vars — Reparse the query vars.
parse_search — Generates SQL for the WHERE clause based on passed search terms.
parse_search_order — Generates SQL for the ORDER BY condition based on passed search terms.
parse_search_terms — Check if the terms are suitable for searching.
parse_tax_query — Parses various taxonomy related query vars.
query — Sets up the WordPress query by parsing query string.
reset_postdata — After looping through a nested query, this function restores the $post global to the current post in this query.
rewind_comments — Rewind the comments, resets the comment index and comment to first.
rewind_posts — Rewind the posts and reset post index.
set — Set query variable.
set_404 — Sets the 404 property and saves whether query is feed.
set_found_posts — Set up the amount of found posts and the number of pages (if limit clause was used) for the current query.
setup_postdata — Set up global post data.
the_comment — Sets up the current comment.
the_post — Sets up the current post.

WordPress WP_Query参数详解

Author Parameters Author Parameters

Category Parameters Category Parameters

Tag Parameters Tag Parameters

Taxonomy Parameters Taxonomy Parameters

Search Parameters Search Parameters

Post & Page Parameters Post & Page Parameters

Password Parameters Password Parameters

Post Type Parameters Post Type Parameters

Status Parameters

Comment Parameters

Order & Orderby Parameters Order & Orderby Parameters

Date Parameters Date Parameters

Custom Field (post meta) Parameters Custom Field (post meta) Parameters

Permission Parameters Permission Parameters

Mime Type Parameters Mime Type Parameters

Caching Parameters Caching Parameters

Return Fields Parameter Return Fields Parameter

Methods Methods

猜你喜欢

0 个评论

Author Parameters #Author Parameters

Category Parameters #Category Parameters

Tag Parameters #Tag Parameters

Taxonomy Parameters #Taxonomy Parameters

Search Parameters #Search Parameters

Post & Page Parameters #Post & Page Parameters

Password Parameters #Password Parameters

Post Type Parameters #Post Type Parameters

Status Parameters

Comment Parameters

Pagination Parameters

Order & Orderby Parameters #Order & Orderby Parameters

Date Parameters #Date Parameters

Custom Field (post meta) Parameters #Custom Field (post meta) Parameters

Permission Parameters #Permission Parameters

Mime Type Parameters #Mime Type Parameters

Caching Parameters #Caching Parameters

Return Fields Parameter #Return Fields Parameter

Methods #Methods

猜你喜欢

0 个评论

Author Parameters Author Parameters

Category Parameters Category Parameters

Tag Parameters Tag Parameters

Taxonomy Parameters Taxonomy Parameters

Search Parameters Search Parameters

Post & Page Parameters Post & Page Parameters

Password Parameters Password Parameters

Post Type Parameters Post Type Parameters

Order & Orderby Parameters Order & Orderby Parameters

Date Parameters Date Parameters

Custom Field (post meta) Parameters Custom Field (post meta) Parameters

Permission Parameters Permission Parameters

Mime Type Parameters Mime Type Parameters

Caching Parameters Caching Parameters

Return Fields Parameter Return Fields Parameter

Methods Methods