ワードプレスでウェブサイトを構築するとき、ほぼ必ずサブループを使います。
サブループはワードプレスの基礎と言っても過言ではないでしょう。
しかしサブループを実装するための「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）」+「カスタム投稿」を使えるようになるとワードプレスでできることが一気に広がります。
この記事をブックマークして、サブループ使い方で迷ったときはまた戻ってきてください。
