ワードプレスでウェブサイトを構築するとき、ほぼ必ずサブループを使います。
サブループはワードプレスの基礎と言っても過言ではないでしょう。

しかしサブループを実装するための「WP_Query」は用意されているパラメーターが膨大で、暗記しておくのは現実的ではありません。
そこで「WP_Query」のパラメーターの一覧と使い方をここで完全に整理していきます。

「WP_Query」を使った基本のサブループ

<?php
$args = array(
	'posts_per_page' => '10',
	'post_type' => 'post'
);
$the_query = new WP_Query( $args );
if($the_query->have_posts()):
?>
<ul>
<?php while($the_query->have_posts()) : $the_query->the_post(); ?>
	<li>
		<a href="<?php the_permalink() ?>">
			<?php the_title_attribute(); ?>
		</a>
	</li>
<?php endwhile; ?>
</ul>
<?php endif; ?>
<?php wp_reset_postdata(); ?>

大きなポイントは２点。

  • 配列「$args」を設定して、様々な条件で投稿を取得します。
  • サブループが終わったら必ずwp_reset_postdata();を実行して取得しているループをリセットします。

パラメータ一覧

著者

特定の「著者」に関連付けられた投稿を表示。

$args = array(
	'author' => '1,2,3', 			// 著者IDを指定
	'author_name' => 'example', 		// user_nicenameを指定
	'author__in' => array( 2 , 6 ), 	// 著者IDを配列で指定
	'author__not_in' => array( 2 , 6 ),	// 著者IDを配列で指定（著者IDを含まない記事を絞り込む）
);

カテゴリー

特定の「カテゴリー」に関連付けられた投稿を表示。

$args = array(
	'cat' => 11, 					// カテゴリーIDを指定
	'category_name' => 'news, events', 		// カテゴリースラッグを指定
	'category__and' => array( 8 , 11 ), 		// カテゴリーIDを配列で指定
	'category__in' => array( 8 , 11 ), 		// カテゴリーIDを配列で指定
	'category__not_in' => array( 8 , 11 ),		// カテゴリーIDを配列で指定（カテゴリーIDを含まない記事を絞り込む）
);

タグ

特定の「タグ」に関連付けられた投稿を表示

$args = array(
	'tag' => 'javascript',				// タグスラッグを指定
	'tag_id' => 11,					// タグIDを指定
	'tag__and' => array( 3 , 5 ),			// タグIDを配列で指定
	'tag__in' => array( 3 , 5 ),			// タグIDを配列で指定
	'tag__not_in' => array( 3 , 5 ),		// タグIDを配列で指定（タグIDを含まない記事を絞り込む）
	'tag_slug__and' => array( 'js', 'css' ),	// タグスラッグを配列で指定
	'tag_slug__in' => array( 'js', 'css' ),		// タグスラッグを配列で指定
);

カスタムタクソノミー

以下はカスタム分類「cooking」の「french」に関連付けられた投稿（post）を表示。

$args = array(
	'post_type' => 'post',
	'tax_query' => array(
		array(
			'taxonomy' => 'cooking',
			'field'    => 'slug',
			'terms'    => 'French',
			'operator' => 'IN',	// 使用可能な値は「'IN'」「'NOT IN'」「'AND'」「'EXISTS'」「'NOT EXISTS'」
		),
	),
	'include_children' => true,		// 階層を持つタクソノミーの場合に、子孫タクソノミーを含めるかどうか
operator
);

投稿と固定ページ

特定の「投稿」または「固定ページ」を表示。

$args = array(
	'p' => 1, 					// 投稿のIDを指定
	'name' => 'hello-world', 			// 投稿のスラッグを指定
	'title' => 'hello-world',  			// 投稿のタイトルを指定
	'page_id' => 1,					// 固定ページのIDを指定
	'pagename' => 'sample-page', 			// 固定ページのスラッグを指定
	'post_parent' => 1,				// 固定ページのIDを指定と子ページを返す
	'post_parent__in' => array(1, 2, 3),		// 投稿のIDを指定すると配列の親ページIDを含む投稿を返す
	'post_parent__not_in' => array(1, 2, 3),	// 投稿のIDを指定すると配列の親ページIDを含まない投稿を返す
	'post__in' => array(1, 2, 3),			// 投稿のIDを指定すると配列の投稿IDを含む投稿を返す
	'post__not_in' => array(1, 2, 3),		// 投稿のIDを指定すると配列の投稿IDを含まない投稿を返す
	'post_name__in' => 'hello-world',		// 投稿のスラッグを指定
);

パスワードのパラメータ

特定の「パスワード」に関連付けられた投稿を表示。
パスワードのパラメータを指定した場合、投稿と固定ページのパラメータで選ばれた投稿や固定ページが対象になる。

$args = array(
	'has_password' => true,		// パスワードで保護された投稿を表示するには true、保護されてない投稿を表示するには false を指定
	'post_password' => 'abcdef',	// 特定のパスワードで保護されている投稿を表示
);

投稿タイプ

特定の「投稿タイプ」に関連付けられた投稿を表示。

$args = array(
	'post_type' => array( 
		'post',			// 投稿
		'page',			// 固定ページ
		'revision',		// リビジョン
		'attachment', 		// 添付ファイル
		'nav_menu_item',	// ナビゲーションメニュー項目
		'custom-post-type',	// カスタム投稿タイプ
	),
	'post_type' => 'any',	// リビジョンと'exclude_from_search'がtrueにセットされたものを除き、すべての投稿タイプを含める
);

ステータスのパラメータ

特定の「投稿ステータス」に関連付けられた投稿を表示。

$args = array(
	'publish',	// 公開状態の投稿もしくは固定ページ
	'pending',	// レビュー待ちの投稿
	'draft',	// 下書きの投稿
	'auto-draft',	// コンテンツのない、新規作成された投稿
	'future',	// 予約公開設定された投稿
	'private',	// ログインしていないユーザーから見えない設定
	'inherit',	// リビジョン
	'trash',	// ゴミ箱に入った投稿
	'any',		// 'exclude_from_search' が true にセットされているもの（つまり trash と auto-draft）を除き、すべてのステータスの投稿を取得
);

コメントパラメータ

$args = array(
	// コメント数が20の投稿を表示する場合：
	'comment_count' => 20,		// 投稿のコメント数（比較演算子は '=' が使われる）
	// コメント数が25以上の投稿を表示する場合：
	'comment_count' => array(
		'value' => 25,		// 投稿のコメント数と比較する数
		'compare' => '>=',	// 比較演算子（可能な値は「'='」「'!='」「'>'」「'>='」「'<'」「'<='」）
	)
);

ページネーション設定

$args = array(
	'nopaging' => false,			// ページネーションを使用するか、すべての投稿を表示するか（デフォルトはfalseでページネーションを使用）
	'posts_per_page' => 10,			// 1ページあたりに表示する投稿数を指定（-1を指定すると全件表示）
	'posts_per_archive_page' => 10,		// 1ページあたりに表示する投稿数を指定（アーカイブページのみ）
	'paged' => 11, 				// ページ番号11の記事を表示
	'paged' => get_query_var('paged'),	// 現在のページから投稿を表示
	'offset' => 3,				// ずらす（読み飛ばす）投稿の数
	'ignore_sticky_posts' => false,		// 先頭固定表示投稿を無視するかどうか（true にすると無視する）
);

順序パラメータ

$args = array(
	'order' => 'DESC',	// 'DESC'（最高から最低へ降順）、'ASC'（最低から最高へ昇順）
	'orderby' => 'date',
				// 'none'		順序をつけない
				// 'ID'			投稿IDで並び替える
				// 'author'		著者で並び替える（'post_author' でも良い）
				// 'title'		タイトルで並び替える（'post_title' でも良い）
				// 'name'		スラッグで並び替える（'post_name' でも良い）
				// 'type'		投稿タイプで並び替える（'post_type' でも良い）
				// 'date'		日付で並び替える（'post_date' でも良い）
				// 'modified'		更新日で並び替える（'post_modified' でも良い）
				// 'parent'		投稿または固定ページの親ID順（'post_parent' でも良い）
				// 'rand'		ランダムで並び替える
				// 'comment_count'	コメント数で並び替える
				// 'relevance'		文字列検索のとき次の順で並び替える：「1.文字列全体がマッチ」「2.すべての単語がタイトルに含まれる」「3.いずれかの単語がタイトルに現れる」「4.文字列全体が post_content に現れる」
				// 'menu_order'		固定ページの表示順で並び替える
				// 'meta_value'		カスタムフィールドで並び替える（'meta_key=keyname' がクエリに存在しなければいけない
				// 'meta_value_num'	カスタムフィールドの値を数値として並び替える（'meta_key=keyname'がクエリに存在しなければならない）
				// 'post__in'		post__inで配列で指定された投稿IDの並び順を維持して表示
				// 'post_name__in'	'post_name__in' パラメータの配列に並んだ投稿スラッグの順
				// 'post_parent__in'	'post_parent__in' パラメータの配列に並んだ親投稿 ID の順
);

日付パラメータ

特定の「日付」に関連付けられた投稿を表示。

$args = array(
	'year' => 2011,		// 4桁の年を数字で指定
	'monthnum' => 8,	// 月を数字で指定
	'w' => 13,		// 年内の週を数字で指定
	'day' => 18,		// 月内の日を数字で指定
	'hour' => 13,		// 時間を数字で指定
	'minute' => 11,		// 分を数字で指定
	'second' => 30,		// 秒を数字で指定
	'm' => 202112,		// 年と月を数字で指定（例：201307）
	'date_query' => array(	// 複雑な指定ができる日付パラメータ
		array(
			'year' => 2012,
			'monthnum' => 12,
			'w' => 12,
			'after' => 'January 1st, 2013',		// この日付より後の投稿を取得
			'before' => 'January 1st, 2018',	// この日付より前の投稿を取得
		),
	),
	'inclusive' => true,		//「after」または「before」パラメーターで指定された値を含むかどうか
	'compare' => '=',		// 使用可能な値は「'='」「'!='」「'>'」「'>='」「'<'」「'<='」
	'column' => 'post_date',	// クエリ対象とする（wp_postsテーブルの）カラム（デフォルトは 'post_date'）
	'relation' => 'AND',		// 子の配列をどのように結合して比較するか（OR または AND）
);

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

特定の「カスタムフィールド」に関連付けられた投稿を表示。

$args = array(
	'meta_key' => 'key',			// カスタムフィールドのキー
	'meta_value' => 'value', 		// カスタムフィールドの値（文字列として比較）
	'meta_value_num' => 12, 		// カスタムフィールドの値（数値として比較）
	'meta_compare' => '=',		// 'meta_value'のテスト演算子（使える値は「'!='」「'>'」「'>='」「'<'」「'<='」「'LIKE'」「'NOT LIKE'」「'IN'」「'NOT IN'」「'BETWEEN'」「'NOT BETWEEN'」「'NOT EXISTS'」「'REGEXP'」「'NOT REGEXP'」「RLIKE'」）
	'meta_query' => array(		// カスタムフィールドの複雑なパラメータ
		'relation' => 'AND',		// meta_query の中に2つ以上の配列を入れたときの論理的な関係。使える値は 'AND'と'OR'。ひとつだけ配列を入れるときは使わないこと。
		array(
			'key' => 'cooking',		// カスタムフィールドのキー
			'value' => 'japanese',		// カスタムフィールドの値。配列を指定できるのは compare が 'IN', 'NOT IN', 'BETWEEN' または 'NOT BETWEEN' の場合。 compare に 'EXISTS' または 'NOT EXISTS' を指定する場合は value を省略できる。
			'compare' => '=',		// テスト演算子。使える値は「'='」「'!='」「'>'」「'>='」「'<'」「'<='」「'LIKE'」「'NOT LIKE'」「'IN'」「'NOT IN'」「'BETWEEN'」「'NOT BETWEEN'」「'EXISTS'」「'NOT EXISTS'」
			'type' => 'CHAR'		// カスタムフィールドの値のタイプ。使える値は「'NUMERIC'」「'BINARY'」「'CHAR'」「'DATE'」「'DATETIME'」「'DECIMAL'」「'SIGNED'」「'TIME'」「'UNSIGNED'」 
);

権限パラメータ

ユーザーが適切な権限を持つ場合に投稿を表示。
以下の例では、ユーザーが適切な権限を持つ場合に、公開済みと非公開の投稿を表示する。

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

MIME タイプのパラメータ

添付ファイル（attachments）投稿タイプと共に使う。
以下の例では、gif画像の添付ファイルを取得する。添付ファイルのデフォルトの投稿ステータスが inherit であることに注意する。

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

キャッシュのパラメータ

取得したデータがキャッシュへ追加されるのを禁止する。

$args = array(
	'cache_results' => true,                // 投稿情報のキャッシュ
	'update_post_meta_cache' => true,       // 投稿のメタ情報のキャッシュ（カスタムフィールドなど）
	'update_post_term_cache' => true,       // 投稿のターム情報のキャッシュ（カテゴリーなど）
);

戻り値パラメータ

戻り値を設定する。

$args = array(
	'fields' => 'ids',		// 投稿IDの配列を返す
	'fields' => 'id=>parent',	// プロパティに ID（投稿ID）と post_parent（親のID）を持つ stdClass オブジェクトの配列を返す
);

最後に

「サブループ（WP_Query）」+「カスタム投稿」を使えるようになるとワードプレスでできることが一気に広がります。
この記事をブックマークして、サブループ使い方で迷ったときはまた戻ってきてください。

［改訂版］WordPress　仕事の現場でサッと使える！ デザイン教科書［WordPress 5.x対応版］ Webデザイナー養成講座