• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/WP Query

提供: WordPress Codex 日本語版
< 関数リファレンス
2015年10月31日 (土) 00:09時点におけるGblsm (トーク | 投稿記録)による版 (ページ送りパラメータ、順序づけパラメータの各セクションを本家(英語版)から反映。)

移動先: 案内検索

説明

WP_Querywp-includes/query.php に定義されているクラスで、WordPress ブログへの複雑な投稿やページのリクエストを取り扱います。 wp-blog-header.php (バージョン 2.0 では WP クラス) が $wp_query オブジェクトに現在のリクエストを定義する情報を与えることで、$wp_query はどのタイプのクエリを扱っているのか (カテゴリーアーカイブ、年月別アーカイブ、フィード、検索など) を確定し、要求された投稿を取り出します。$wp_query はリクエスト上の情報を多く保持していて、後からでも利用することができます。

WP_Queryのインタラクション

ほとんどの場合、クラスの内部やグローバル変数を使わなくても欲しい情報は手に入れられるでしょう。どこからでも欲しい情報を手に入れるために、厖大な数の関数があるのですから。

WP_Queryを使いたくなるかもしれないケースが二つあります。一つは、WordPressが今扱っているリクエストがどんなものかを知るためです。$is_*プロパティはこの情報を持つよう設計されています: このためには条件分岐タグを使ってください。これはプラグイン作者 (そして、テーマ作者) によくあるケースです。

二つ目はループの中です。WP_Queryはループ内において、よくある要望を実現するための厖大な関数を備えています。たとえば$wp_query->have_posts()を呼び出すhave_posts()は、表示すべき投稿があるかどうかを判断するために呼び出されます。whileループの開始時に、have_posts()を条件として使います。このループは表示すべき投稿がある限り反復されます。反復処理を行うごとに、$wp_query->the_post()を呼び出す the_post() が呼び出され、$wp_query 内の変数とグローバル変数 $post (テンプレートタグはこれに依存します) を設定します。これは上で見た通りです。ループを必要とするテーマを作っている時、使うべき関数はたくさんあります。詳しくはループThe Loop in Action をご覧ください。

注意: あなたのクエリで the_post() を使うのなら、クエリの後に wp_reset_postdata() を実行する必要があります。テンプレートタグがメインクエリの現在の記事を再び使えるようにするためです。

注意: Ticket #18408 For querying posts in the admin, consider using get_posts() as wp_reset_postdata() might not behave as expected.

用例

標準的なループ

<?php

// The Query
$the_query = new WP_Query( $args );

// The Loop
if ( $the_query->have_posts() ) {
	echo '<ul>';
	while ( $the_query->have_posts() ) {
		$the_query->the_post();
		echo '<li>' . get_the_title() . '</li>';
	}
	echo '</ul>';
} else {
	// no posts found
}
/* Restore original Post Data */
wp_reset_postdata();

標準的なループ (別の方法)

<?php 
// the query
$the_query = new WP_Query( $args ); ?>

<?php if ( $the_query->have_posts() ) : ?>

	<!-- pagination here -->

	<!-- the loop -->
	<?php while ( $the_query->have_posts() ) : $the_query->the_post(); ?>
		<h2><?php the_title(); ?></h2>
	<?php endwhile; ?>
	<!-- end of the loop -->

	<!-- pagination here -->

	<?php wp_reset_postdata(); ?>

<?php else : ?>
	<p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>
<?php endif; ?>

複数のループ

If you have multiple queries, you need to perform multiple loops. Like so...

<?php

// The Query
$query1 = new WP_Query( $args );

// The Loop
while ( $query1->have_posts() ) {
	$query1->the_post();
	echo '<li>' . get_the_title() . '</li>';
}

/* Restore original Post Data 
 * NB: Because we are using new WP_Query we aren't stomping on the 
 * original $wp_query and it does not need to be reset with 
 * wp_reset_query(). We just need to set the post data back up with
 * wp_reset_postdata().
 */
wp_reset_postdata();


/* 2つ目のクエリ (without global var) */
$query2 = new WP_Query( $args2 );

// 2つ目のループ
while ( $query2->have_posts() ) {
	$query2->the_post();
	echo '<li>' . get_the_title( $query2->post->ID ) . '</li>';
}

// 元の投稿データを復元
wp_reset_postdata();

?>

メソッドとプロパティ

これはWP_Queryの公式な文書です。プロパティを直接書き換えるべきではありません。その代わりにメソッドを使って操作することができます。クラスのメンバとグローバル変数がめちゃくちゃになることを避ける便利な関数がありますので、WP_Queryに働きかけるを参考にしてください。

プロパティ

$query
$wp_query オブジェクトに WP クラスによって渡されたクエリストリングを含む。
$query_vars
解析された $query を保持する連想配列。クエリ変数と対応する値の配列。
$queried_object
リクエストがカテゴリー、作者ページ、パーマリンク、投稿または固定ページだった場合に適用される。リクエストされたクエリの情報を含む。
$queried_object_id
リクエストがカテゴリー、作者ページ、パーマリンク、投稿または固定ページだった場合、対応する ID を含む。
$posts
要求された投稿をデータベースから取得したもの。
$post_count
表示される投稿の数。
$found_posts
現在のクエリ変数に一致する投稿の合計数。
$max_num_pages
ページの合計数。$found_posts を $posts_per_page で割った結果。
$current_post
(ループ内でのみ使用可能) 表示されようとしている投稿の数。
$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

リクエストがどのタイプなのかを判断するためのブーリアン値。最初の3つの例で言えば、「これはパーマリンクか?」「これは固定ページか?」「これは何らかのアーカイブページか?」となる。合わせて読む: Conditional_Tags

メソッド

(メソッド名の前にあるアンパサンド(&)はそれが参照渡しであることを示します。)

init()
オブジェクトを初期化して、すべてのプロパティをnull、ゼロ、falseにセットする。
parse_query($query)
リクエストを定義するクエリ文字列を受け取り、それを解析して$posts$post_count$post$current_post以外のすべてのプロパティを返す。
parse_query_vars()
古いクエリ文字列をもう一度解析する。
get($query_var)
指定されたクエリ変数を取得する。
set($query_var, $value)
指定されたクエリ変数を任意の値に設定する。
&get_posts()
要求された投稿をデータベースから取得して返す。$posts$post_countも返す。
next_post()
(ループ内でのみ使用可能) $posts で次の投稿に進む。$current_post を1つ増やし、$post を (新規の) 現在の投稿オブジェクトに設定する (注: グローバル $post 変数を設定はせず、WP_Query オブジェクトのインスタンス変数のみに適用される) 。現在の投稿オブジェクトを返す。(これは非推奨です。'next_post_link()'を使用ください。 )
the_post()
(ループ内でのみ使用可能)次の投稿に進み、グローバル変数$postを設定する。
have_posts()
(ループ内か、ループの前でのみ使用可能) 表示する投稿が残っているかを示す。Calls rewind_posts() and returns false if don't have posts remaining. Because of the rewind, you can't rely on have_posts() staying false. have_posts() noteをご覧ください。
rewind_posts()
$current_post$postをリセットする。
&query($query)
parse_query()get_posts()を呼び出し、get_posts()の結果を返す。
get_queried_object()
$queried_objectを設定し、それがまだ設定されていなければ、返す。
get_queried_object_id()
$queried_object_idを設定し、それがまだ設定されていなければ返す。
WP_Query($query = '') (コンストラクタ)
クエリ文字列を与えれば、それを使ってquery()を呼び出す。


パラメータ

投稿者パラメータ

ある投稿者に関連付けられた投稿を表示する。

  • author (int) - ユーザーID。
  • author_name (string) - 'user_nicename' (姓・名・ニックネームではなく)。
  • author__in (array) - ユーザーID (バージョン 3.7以降で利用可能)。
  • author__not_in (array) - ユーザーID (バージョン 3.7以降で利用可能)。

ひとりの投稿者の投稿を表示する

ユーザーIDを用いて、ある投稿者の記事を表示する場合:

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

'user_nicename' を用いて、ある投稿者の記事を表示する場合:

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

複数の投稿者の投稿を表示する

複数の、特定の投稿者の記事を表示する場合:

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

ある投稿者による記事を除外する

'-'(マイナス)記号をユーザーIDの頭につけることで、あるひとりの投稿者(singular) による記事を除く、すべての記事を表示できます:

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

複数の投稿者を扱う

複数の投稿者の記事を表示する:

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

以下の方法で複数の投稿者を除外することもできます:

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

カテゴリーパラメータ

あるカテゴリーに関連付けられた投稿を表示する。

  • cat (int) - カテゴリIDを使用します。
  • category_name (string) - カテゴリのスラッグ(カテゴリ名ではありません)を使用します。
  • category__and (array) - カテゴリIDを使用します。
  • category__in (array) - カテゴリIDを使用します。
  • category__not_in (array) -カテゴリIDを使用します。

1つのカテゴリの記事を表示

カテゴリIDを使用して、そのカテゴリ(さらにそのカテゴリの子カテゴリ)に属する記事を表示:

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

カテゴリスラッグを使用して、そのカテゴリ(さらにそのカテゴリの子カテゴリ)に属する記事を表示:

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

カテゴリIDを使って、そのカテゴリ (子カテゴリではない)に属する記事を表示:

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

複数のカテゴリから記事を表示

カテゴリIDを使用して、それらのカテゴリに属する記事を表示:

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

カテゴリスラッグを使用して、それらのカテゴリに属する記事を表示:

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

それらのカテゴリの "全て" に属する記事を表示:

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

カテゴリに属する記事を除外

IDに'-'(マイナス記号)が付いたカテゴリの記事を除くすべての記事を表示:

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

複数カテゴリの扱い

複数のカテゴリに属する記事を表示。下記はカテゴリID 2と6の両方に属する記事を表示します:

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

カテゴリID 2または6の記事を表示するには、前述の cat か、または category__in(これらのカテゴリの子カテゴリの記事は表示されないことに注意してください)を使うことで実現します:

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

下記の方法で、複数のカテゴリの記事を除外することもできます:

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

タグパラメータ

あるタグに関連付けられた投稿を表示する。

  • tag (文字列) - タグのスラッグを指定。
  • tag_id (整数) - タグ ID を指定。
  • tag__and (配列) - タグ ID を指定。
  • tag__in (配列) - タグ ID を指定。
  • tag__not_in (配列) - タグ ID を指定。
  • tag_slug__and (配列) - タグのスラッグを指定。
  • tag_slug__in (配列) - タグのスラッグを指定。

1つのタグの記事を表示

タグのスラッグを使って、このタグを持つ記事を表示:

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

タグのIDを使って、このタグを持つ記事を表示:

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

複数のタグから記事を表示

これらのいずれかのタグを持つ記事を表示:

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

これらのすべてのタグを持つ記事を表示:

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

複数タグの扱い

タグID 37 と 47 の両方にタグ付けられた記事を表示:

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

タグID 37 と 47 いずれかの記事を表示するには、前述の tag か、もしくは tag__in を使って明示的に特定することで実現します:

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

タグID 37 と 47 、2つのタグのいずれも持たない記事を表示:

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

tag_slug__intag_slug__and は、タグのスラッグを対象とすることを除いて、それぞれ tag__intag__and とほぼ同様に動作します。

タクソノミーパラメータ

あるタクソノミーに関連付けられた投稿を表示する。

  • {tax} (文字列) - タクソノミーのスラッグを使用します。注:バージョン 3.1 以降は非推奨になりましたので、代わりに 'tax_query' を使用してください。
  • tax_query (配列) - タクソノミーパラメータを使用(バージョン 3.1 から利用可能)。


    • relation (文字列) - 2 つ以上のタクソノミー検索条件(内側の配列)が含まれる場合に、それらの論理的な関係を指定します。有効な値は 'AND' または 'OR' です。1 つしかタクソノミー検索条件を含まない場合は指定しないでください。
    • taxonomy (文字列) - タクソノミー。
    • field (文字列) - タクソノミータームの種類を選択します。有効な値は 'term_id'(デフォルト)、'name' または 'slug' です。
    • terms (整数/文字列/配列) - タクソノミーターム。
    • include_children (真偽値) - 階層を持つタクソノミーの場合に子孫タクソノミーを含めるかどうか。デフォルトは true(含める)です。
    • operator (文字列) - 演算子。使用可能な値は 'IN'(デフォルト), 'NOT IN', 'AND', 'EXISTS' (4.1.0 以降) と 'NOT EXISTS'(4.1.0 以降) です。

重要な参考ポイント: tax_query は、タクソノミー検索条件(配列)の配列 をパラメータにします(つまり配列の配列です)。 下記の 2 番目の例を見るとわかりやすいでしょう。この構造によって、複数のタクソノミーを検索できますが、その時は最初の(外側の)配列の relation パラメータによって複数のタクソノミー検索の関係を指定します。

シンプルなカスタム分類のクエリー:

カスタム分類 peoplebobに関連付けられた 投稿を表示します :

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

複数のカスタム分類の取り扱い:

いくつかのカスタム分類から投稿を表示します:

$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 );

カテゴリー quotes に所属するか投稿フォーマットquote(引用)投稿を表示します:

$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 );

ネストされたカスタム分類の取扱い:

4.1以降から、より複雑なクエリを作成のために、'tax_query' 句を入れ子にすることができます。

例: カテゴリー quotes に所属する、もしくは投稿フォーマットが quote(引用) かつカテゴリー wisdom に所属する投稿を表示:

$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 );

検索パラメータ

キーワード検索によって投稿を表示します。

  • s (文字列) - 検索するキーワード。

キーワード検索によって投稿を表示

「キーワード」という検索語にマッチする投稿を表示します:

$query = new WP_Query( array( 's' => 'キーワード' ) );

投稿&固定ページパラメータ

投稿および固定ページに基づいてコンテンツを表示する。

  • p (int) - 投稿のIDを使用する。
  • name (string) - 投稿のスラッグを使用する。
  • page_id (int) - 固定ページのIDを使用する。
  • pagename (string) - 固定ページのスラッグを使用する。
  • post_parent (int) - 固定ページのIDを使用する。子ページを返す。
  • post__in (array) - 投稿のIDを使用する。取得するために投稿を指定する。
  • post__not_in (array) - 投稿のIDを使用する。指定された投稿は取得されない

IDで投稿/ページを表示

投稿のIDを指定して表示する:

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

固定ページのIDを指定して表示する:

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

スラッグで投稿/ページを表示

投稿のスラッグを指定して表示する:

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

固定ページのスラッグを指定して表示する:

$query = new WP_Query( '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( 'pagename=contact_us/canada' );

親ページの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 ) ) );

複数の投稿/ページを操作

指定された投稿のみ表示:

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

指定された以外の全ての投稿を表示:

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

注意: 同じクエリー内で 'post__in' を 'post__not_in' 同時に使うことは出来ません。

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 ) );

パスワードパラメータ

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)

Show Posts with/without passwords

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 ) );

Show Posts with particular password

Display posts with 'zxcvbn' password:

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

タイプパラメータ

ある投稿タイプに関連付けられた投稿を表示します。

  • post_type (string / array) - 投稿を[[投稿タイプ]によって取得する。デフォルト値は 'post'。'tax_query' がクエリーにセットされている場合、デフォルト値は 'any' になります。
    • 'post' - 投稿。
    • 'page' - 固定ページ。
    • 'revision' - 履歴 (リビジョン) 。
    • 'attachment' - 添付ファイル。WP_Query のデフォルトでは 'post_status' が 'published' ですが、添付ファイルはデフォルトで 'post_status' が 'inherit' になっています。そのため 'post_status' を明示的に 'inherit' か 'any' にしなければ、どの添付ファイルも取得できません。(See post_status, below)
    • 'nav_menu_item' - a navigation menu item
    • 'any' - リビジョンと 'exclude_from_search' が true にセットされたものを除き、すべてのタイプを含める
    • Custom Post Types (e.g. movies)

投稿タイプによる投稿の表示

固定ページのみ表示:

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

'any'(すべての)投稿タイプを表示(リビジョンと 'exclude_from_search' が TRUE になっている投稿タイプを除くすべての投稿タイプが含まれます):

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

カスタムポストタイプを含む複数のポストタイプを表示:

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

ステータスパラメータ

ある投稿ステータスに関連付けられた投稿を表示します。

  • post_status (string / array) - 投稿ステータスを指定します。 デフォルト値は 'publish' です。しかし if the user is logged in, 'private' is added. 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' - 公開された投稿もしくは固定ページ
    • 'pending' - レビュー待ちの投稿
    • 'draft' - 下書きの投稿
    • 'auto-draft' - コンテンツのない、新規作成された投稿
    • 'future' - 予約公開設定された投稿
    • 'private' - ログインしていないユーザーから見えない設定
    • 'inherit' - リビジョン。 get_childrenを見てください。
    • 'trash' - ゴミ箱に入った投稿。 (Version 2.9 以降で利用可能)。
    • 'any' - 'exclude_from_search' が true にセットされているもの(つまり trash と auto-draft)を除き、すべてのステータスの投稿を取得する。

ステータスによる投稿の表示

下書きのみ表示:

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

複数の投稿のステータスを表示:

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

すべての添付ファイルを表示:

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

ページ送りパラメータ

  • nopaging (真偽値) - すべての投稿を含めるか、ページ送りに対応させます。デフォルト値は false で、ページ送りに対応します。
  • posts_per_page (整数) - 1ページに含める投稿数(バージョン 2.1 以降で使えます。非推奨になった showposts パラメータを置き換えます)。'posts_per_page'=>-1 を使用するとすべての投稿を含めます(このとき 'offset' パラメータは無視されます)。ページ送りを使用するにはこのパラメータと一緒に 'paged' パラメータを指定してください。参考:フィードでのクエリの場合、WordPress はオプション 'posts_per_rss'(RSS/Atom フィードで表示する最新の投稿数)の値でこのパラメータを上書きします。それでも投稿数を設定するには 'post_limits' フィルターを使うか、'pre_option_posts_per_rss' フィルターで -1 を返してください。
  • posts_per_archive_page (整数) - 1ページに含める投稿数ですが、アーカイブページ専用です。is_archive()is_search() が true になるページでは、posts_per_pageshowposts の値を上書きします。
  • offset (整数) - ずらす(または読み飛ばす)投稿の数。注意offset パラメータをセットすると paged パラメータを無視します。そのためページ送りされません(ワークアラウンドを見るにはここをクリック /en)。反対に 'offset' パラメータは 'posts_per_page'=>-1 が使われると(すべての投稿を表示)無視されます。
  • paged (整数) - ページ番号。「前の投稿」リンクを使った場合にふつうページ X に表示されるであろう投稿を含めます。
  • 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 (真偽値) - 先頭固定表示の投稿を無視します(バージョン 3.1 以降で使えます。非推奨になった caller_get_posts パラメータを置き換えます)。デフォルトは false で、無視しません(先頭に含めます)。true にすると無視します。なお、先頭固定表示の投稿を無視(除外)しても先頭に出てこないだけで、投稿リストにそれらの投稿が本来並ぶべき位置には出てきます。

ページあたり x件の投稿を表示

ページあたり3件の投稿を表示する:

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

全ての投稿を表示

1つのページに全ての投稿を表示する:

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

ページネーションを無効にして全ての投稿を表示する:

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

投稿を読み飛ばす

4番目の投稿から表示する:

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

最新から3つを飛ばして5件の投稿を表示:

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

xページから投稿を表示

ページ番号6の記事を表示します:

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

現在のページから投稿を表示

現在のページから投稿を表示する:

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

現在のページから投稿を表示するが、もしクエリ変数がセットされていなければ(先頭ページなら)'page' パラメータに 1 をセットする。

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

ページネーションの参考:静的フロントページに指定したページテンプレートにおいて、クエリをページ送りに対応させるには get_query_var( 'page' ); を使ってください。さらにクエリ変数 'page' は、<!--nextpage--> クイックタグ をコンテンツに含んでおりページ分割された単一の投稿または固定ページについて、ページ番号を保持します。

静的フロントページの現在のページから投稿を表示する:

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

先頭固定表示の投稿を含める

先頭固定表示の投稿のうち最初のひとつを取得します:

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

最初の先頭固定表示の投稿を取得しますが、もしなければ最新の投稿を取得します:

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

最初の先頭固定表示の投稿を取得し、もしなければどの投稿も取得しません:

$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...
}

先頭固定表示の投稿を無視する

クエリからすべての先頭固定表示の投稿を除外します:

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

あるカテゴリーから先頭固定表示の投稿を無視して取得します。カテゴリー内のすべての投稿を取得しますが、先頭固定表示の投稿を最初に入れません。ただし本来出てくるべき位置(例:日付順)には先頭固定表示の投稿が含まれます:

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

あるカテゴリーから先頭固定表示の投稿を無視して取得します。カテゴリー内の投稿を取得しますが、先頭固定表示の投稿を完全に除外します。さらにページングに対応させます:

$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 );


順序づけパラメータ

投稿の並びを指定します。

  • order (文字列 | 配列) - 'orderby' パラメータについて昇順か降順かを指定します。デフォルトは 'DESC'(降順)です。複数の order/orderby の組を配列で指定することもできます。
    • 'ASC' - 最低から最高へ昇順 (1, 2, 3; a, b, c).
    • 'DESC' - 最高から最低へ降順 (3, 2, 1; c, b, a).
  • orderby (文字列 | 配列) - パラメータで指定した項目の値で投稿をソートする。デフォルトは 'date' (post_date) です。2つ以上のオプションを含めることもできます。
    • 'none' - 順序をつけない(バージョン 2.8 以降で使用可能)。
    • 'ID' - 投稿 ID で並び替える。大文字に注意。
    • 'author' - 著者で並び替える。
    • 'title' - タイトルで並び替える。
    • 'date' - 日付で並び替える。
    • 'modified' - 更新日で並び替える。
    • 'parent' - 投稿/固定ページの親ID順。
    • 'rand' - ランダムで並び替える。
    • 'comment_count' - コメント数で並び替える(バージョン 2.9 以降で使用可能)。
    • 'menu_order' - ページの表示順で並び替える。固定ページOrder field in the Edit Page Attributes box)と添付ファイル(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' - カスタムフィールドで並び替える。'meta_key=keyname'がクエリに存在しなければいけません。また、ソート順は文字列順になることに注意して下さい。数値だと予想外の挙動をします(通常、1, 3, 4, 6, 34, 56となると思うところが、1, 3, 34, 4, 56, 6となります)。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'.
    • 'meta_value_num' - カスタムフィールドの値を数値として並び替える。(バージョン 2.8 以降で使用可能)。これもまた、'meta_key=keyname'がクエリに存在しなければならないことに注意して下さい。こちらは 'meta_value' 示したような数値での並べ替えを可能にします。
    • 'post__in' - Preserve post ID order given in the post__in array (available since Version 3.5).

タイトルで投稿をソート表示、降順

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 );

ランダムに投稿を表示

ランダムに投稿を1件表示する:

$args = array(
	'orderby'        => 'rand',
	'posts_per_page' => '1',

);
$query = new WP_Query( $args );

人気の投稿を表示

投稿をコメント数の順に表示する:

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

値段順にソートした商品を表示

'Product' 投稿タイプをカスタムフィールド 'Price' で並び替えて表示:

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

複数の値を 'orderby' に指定

固定ページを 'title' と 'menu_order' で並び替えて表示(タイトルが優先):

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

配列を使って複数の値を 'orderby' に指定

別々の表示順(昇順/降順)の 'title' と 'menu_order' で並べ替えた固定ページを表示(バージョン 4.0 から利用可能):

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

Mulitiple orderby/order pairs

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

カスタムフィールドとカスタム投稿タイプを 'orderby' に指定

投稿タイプが 'my_custom_post_type' で 'age' 順、そして 'age' が3か4のものだけを表示(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 );

時間パラメータ

ある期間に関連付けられた投稿を表示する。

  • year (int) - 4ケタの年 (例. 2011).
  • monthnum (int) - 月 (1 から 12).
  • w (int) - 週数 (0 から 53). Uses the MySQL WEEK command Mode=1.
  • day (int) - 日 (1 から 31).
  • hour (int) - 時 (0 から 23).
  • minute (int) - 分 (0 から 60).
  • second (int) - 秒 (0 から 60).

現在の日付の記事を返す:

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

今週の記事を返す:

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

12月20日の投稿を返す:

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

Note: The queries above return posts for a specific date period in history, i.e. "Posts from X year, X month, X day". They are unable to fetch posts from a timespan relative to the present, so queries like "Posts from the last 30 days" or "Posts from the last year" are not possible with a basic query, and require use of the posts_where filter to be completed. The examples below use the posts_where filter, and should be modifyable for most time-relative queries.

2009年3月1日から3月15日までの投稿を返す:

// Create a new filtering function that will add our where clause to the query
function filter_where( $where = '' ) {
	// posts for March 1 to March 15, 2010
	$where .= " AND post_date >= '2010-03-01' AND post_date < '2010-03-16'";
	return $where;
}

add_filter( 'posts_where', 'filter_where' );
$query = new WP_Query( $query_string );
remove_filter( 'posts_where', 'filter_where' );

過去30日間からの投稿を返す:

// Create a new filtering function that will add our where clause to the query
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 = new WP_Query( $query_string );
remove_filter( 'posts_where', 'filter_where' );

30から60日経過した投稿を返す

// Create a new filtering function that will add our where clause to the query
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 = new WP_Query( $query_string );
remove_filter( 'posts_where', 'filter_where' );

Starting with 4.1, 'date_query' clauses can be nested in order to construct complex queries. See タクソノミーパラメータ for details on the syntax.


カスタムフィールドパラメータ

あるカスタムフィールドに関連付けられた投稿を表示する。

  • meta_key (文字列) - カスタムフィールドキー
  • meta_value (文字列) - カスタブフィールドの値
  • meta_compare (文字列) -'meta_value'のテスト演算子。 使える値は '!=', '>', '>=', '<', '<='です。デフォルト値は'='です。
  • meta_query (array) - カスタムフィールドのパラメータ (Version 3.1より利用可能)
    • key (文字列) - カスタムフィールドキー
    • value (文字列|array) - カスタブフィールドの値 (Note: Array support is limited to a compare value of 'IN', 'NOT IN', 'BETWEEN', or 'NOT BETWEEN')
    • compare (文字列) - テスト演算子。 使える値は '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN'です。デフォルト値は '='です。
    • type (文字列) - カスタムフィールド投稿タイプ。 使える値は 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'です。 デフォルト値は'CHAR'です。

簡単なカスタムフィールドクエリ:

カスタムフィールドの値に関係なく、カスタムフィールドのキーが'color'の記事を表示します:

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

カスタムフィールドのキーに関係なく、カスタムフィールドの値が'blue'の記事を表示します:

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

Display Page where the custom field value is 'blue', regardless of the custom field key:

$query = new WP_Query( 'meta_value=blue&post_type=page' );

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

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

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

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

Display 'product'(s) where the custom field key is 'price' and the custom field value that is LESS THAN OR EQUAL TO 22. Note the value 99 will be considered greater than 100 as the data is stored as 'strings', not 'numbers'.

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

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

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

単一のカスタムフィールドの取扱い:

1つのカスタムフィールドからの記事を表示します:

$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.)

複数のカスタムフィールドの取扱い:

複数のカスタムフィールドから記事を表示します:

$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 );

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 );

Starting with version 4.1, meta_query clauses can be nested in order to construct complex queries.

For example, "show me 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 );


権限パラメータ

  • perm (string) - User permission.

Show posts if user has the appropriate capability:

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 );

キャッシュパラメータ

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.


戻り値パラメータ

戻り値を設定します。

  • fields (文字列) - Which fields to return. すべてのフィールドがデフォルトで返されます。他の二つのオプションがあります。:
    • 'ids' - 投稿IDの配列を返します。
    • 'id=>parent' - IDpost_parentプロパティでのstdClassオブジェクトの配列を返します。
    • 他の何かを渡すと、すべてのフィールドを返します。 (デフォルト) - 投稿オブジェクトの配列。


フィルター

  • posts_distinct /en - Alters SQL 'DISTINCTROW'節 - post配列を返すクエリを変更
  • posts_groupby /en - Alters SQL 'GROUP BY' 節 - post配列を返すクエリ。
  • posts_join /en - Alters SQL 'JOIN' 節 - post配列を返すクエリ。
  • post_limits /en - Alters SQL 'LIMIT' 節 - post配列を返すクエリ。
  • posts_orderby /en - Alters SQL 'ORDER BY' 節 - post配列を返すクエリ。
  • posts_where /en - Alters SQL 'WHERE' 節 - post配列を返すクエリ。
  • posts_join_paged /en - Alters SQL paging for posts using 'JOIN' 節 - post配列を返すクエリ。
  • posts_where_paged /en - Alters SQL paging for posts using 'WHERE' 節 - post配列を返すクエリ。
  • posts_fields - Alters SQL 'SELECT' clause of the query that returns the post array.
  • posts_clauses /en Alters all the SQL clauses above in one go. It gives you an array of elements that are easy to alter. (Version 3.1以降で使用可能).

注: that there are more filters than the mentioned. As it is hard to keep the codex up to date, please inspect the get_posts(); function inside the WP_Query class yourself (/wp-includes/query.php).

ソースファイル

WP_Query()wp-includes/query.php にあります。

外部リソース

日本語

英語


関連項目

記事

コード・ドキュメンテーション

  • クラス: WP_Query - WP_Query クラスの詳細な全容
  • クラス: WP_Comment_Query - コメント関連のクエリのためのクラス
  • クラス: WP_User_Query - ユーザー関連のクエリのためのクラス
  • オブジェクト: $wpdb - $wpdb オブジェクトの使い方全容
  • 関数: set_query_var()
  • 関数: get_query_var()
  • 関数: query_posts() - 追加のカスタムクエリを作成
  • 関数: get_post() - 項目の ID を取得しデータベース内にあるその投稿のレコードを返す
  • 関数: get_posts() - 投稿の配列を返すことに特化した関数
  • 関数: get_pages() - ページの配列を返すことに特化した関数
  • 関数: have posts() - クエリが投稿を返すか否かを判断する条件関数
  • 関数: the_post() - クエリ後に自動的にループを設定する
  • 関数: rewind_posts() - 現状のループをリセットする
  • 関数: setup_postdata() - ループ内で個別の結果を得るためのクエリデータを設定する
  • 関数: wp_reset_postdata() - 直前のクエリを復元する (通常はループ内の別のループの後に用いられる)
  • 関数: wp_reset_query()
  • 関数: is_main_query() - 変更されるクエリがメインのクエリであることを確認する
  • アクションフック: pre_get_posts - WordPressクエリが実行される前に変更する
  • アクションフック: the_post - post クエリの後で post オブジェクトを変更する
  • フィルターフック: found_posts - WP_Query オブジェクトの found_posts 値を変更する


クラスリファレンス関数リファレンスの各インデックスも参照してください。

このページ「関数リファレンス/WP Query」は一部未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

最新英語版: WordPress Codex » Function Reference/WP Query最新版との差分