WP_Query
WP_Query
は、データベースに保存されている投稿や固定ページ、カスタム投稿を取得するためのWordPressの主要な仕組みです。投稿を表示する際は通常必ずこの WP_Query
が使用されていて、投稿一覧ページ、個別投稿ページなどでは自動的に実行されています。( have_posts()
、the_post()
、the_title()
などのよくあるコードがすぐに使えるのもWordPressが裏で自動的に WP_Query
を動かしているおかげです)
手動での使い方
WordPressが自動で動作させるものとは別に、自分で好きな条件で WP_Query
を使用して投稿を取得することができます。
典型的なコードは下記のとおりです。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
<?php // 「テスト」が含まれる投稿を最大5件取得します。array()の部分が条件です(後述) $q = new WP_Query(array( 's' => 'テスト', 'posts_per_page' => 5 )); // 結果が1件でも取得できた場合 if ( $q->have_posts() ) { ?> <div class="posts"> <ul> <?php // 1件ずつ処理(ループ) while ( $q->have_posts() ) { $q->the_post(); // リンクとタイトルを取得して出力します。 ?> <li><a href="<?php the_permalink() ?>"><?php the_title() ?></a></li> <?php } ?> </ul> </div> <?php // 後片付け wp_reset_postdata(); ?> <?php } ?> |
主な条件
WP_Query
のすべての条件(検索条件)は Codex ( 日本語版 ) に記載されています。ここでは必要な部分をコピーして使えるように、主な条件を早見表(チートシート)のような形で紹介します。
※ 同じキー(post_type
など)を一度に使用することはできません。下記をすべて貼り付けても動きませんので、必要な条件のみコピーしてください。
※ 投稿ステータスの一部などの使用頻度が少なそうなもの、nopaging
などの役割が他のものと被っているものは省いています。(使用頻度が少なくても書き方が特殊なものは掲載しています)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 |
$q = new WP_Query(array( // 投稿タイプ 'post_type' => 'post', // 投稿(通常投稿)のみ 'post_type' => 'page', // 固定ページのみ 'post_type' => 'attachment', // 添付のみ 'post_type' => array( 'post', 'page', 'attachment' ), // 投稿、固定ページ、添付のみ // 投稿ステータス 'post_status' => 'publish', // 公開のみ 'post_status' => 'pending', // レビュー待ちのみ 'post_status' => 'draft', // 下書きのみ 'post_status' => 'future', // 予約投稿のみ 'post_status' => 'private', // 非公開のみ 'post_status' => array( 'publish', 'pending', 'draft', 'future', 'private' ), // 公開、レビュー待ち、下書き、予約投稿、非公開 // スラッグ(投稿名)・投稿データ 'name' => 'hello-world', // 指定されたスラッグを持つデータのみ 'post__in' => array( 1, 2, 3 ), // 指定されたIDを持つデータのみ取得 'post__not_in' => array( 1, 2, 3 ), // 指定されたIDを持つデータ「以外」を取得 // 検索 's' => 'テスト', // 検索キーワードが含まれるデータのみ // 日付(作成日が指定した年月日) 'year' => 2011, 'monthnum' => 1, 'day' => 1, // 日付(作成日が指定した年月日かそれ以前のデータのみ) 'date_query' => array( array( 'before' => array( 'year' => 2016, 'month' => 7, 'day' => 1, ), 'inclusive' => true, // 上記の日付(2016年7月1日)のデータも結果に含める ), ), // カテゴリー 'cat' => 4, // 指定されたIDのカテゴリーに属するデータのみ 'category_name' => 'staff', // 指定されたスラッグ(内部名)のカテゴリーに属するデータのみ 'category__and' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーすべてに属するデータのみ 'category__in' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーのいずれかに属するデータのみ 'category__not_in' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーのどれにも属さないデータのみ // タグ 'tag_id' => 4, // 指定されたIDのタグに属するデータのみ 'tag' => 'cooking', // 指定されたスラッグ(内部名)のタグに属するデータのみ 'category__and' => array( 1, 2, 3 ), // 指定されたIDのタグすべてに属するデータのみ 'category__in' => array( 1, 2, 3 ), // 指定されたIDのタグのいずれかに属するデータのみ 'category__not_in' => array( 1, 2, 3 ), // 指定されたIDのタグのどれにも属さないデータのみ // タクソノミー (カテゴリー、タグも含む) 'tax_query' => array( // 例: staffというスラッグ(内部名)のカテゴリーに属するデータ ('category_name' => 'staff'と同じ) array( 'taxonomy' => 'category', // カテゴリー。タグの場合は 'tag'、他のタクソノミーの場合はタクソノミーのスラッグ(内部名) 'field' => 'slug', // スラッグ 'terms' => 'staff', // スラッグが「staff」 ), ), // カスタムフィールド(下記2つセット。例: color=blueがあるデータのみ) 'meta_key' => 'color', // colorという名前のフィールド 'meta_value' => 'blue' // 値が「blue」 // カスタムフィールド(下記3つセット。例: colorにblueという文字が含まれるデータのみ) 'meta_key' => 'color', // colorという名前のフィールド 'meta_value' => 'blue' // 値が「blue」 'meta_compare' => 'LIKE' // 含まれる // カスタムフィールド(複数条件が必要な場合などの別の書き方) 'meta_query' => array( // colorにblueが含まれない array( 'key' => 'color', // colorという名前のフィールド 'value' => 'blue', // 値が「blue」 'compare' => 'NOT LIKE' // 「含まれない」 ), // price(数値)が20〜100 array( 'key' => 'price', // priceという名前のフィールド 'value' => array( 20, 100 ), // 20〜100 'type' => 'numeric', // 数値として扱う 'compare' => 'BETWEEN', // 「値(value)の間」 ), // 「上記どちらかでも一致すればOK」とする // (relationを省略したり'AND'にした場合は「条件すべて満たせばOK」 'relation' => 'OR', ), // 件数 'posts_per_page' => -1, // 条件に当てはまる投稿すべてを取得 'posts_per_page' => 5, // 条件に当てはまる投稿を最大5件取得 'paged' => 2, // 2ページ目を取得 (posts_per_pageが5の場合6〜10件目) // 並び順 'orderby' => 'ID', // ID順 'orderby' => 'title', // タイトル順 'orderby' => 'date', // 日付(日時)順 'orderby' => 'modified', // 更新日(日時)順 'orderby' => 'menu_order', // 「ページ属性」の「順序」順 'orderby' => 'rand', // ランダム 'orderby' => array( 'date', 'ID' ), // 日付(日時)順、同じ日付(日時)のデータはID順 'orderby' => 'date ID', // 上記と同じ // 並び順(昇順、降順) 'order' => 'ASC', // 昇順 'order' => 'DESC', // 降順 // 複雑な並び順 'orderby' => array( 'date' => 'DESC', 'ID' => 'ASC' ), // 日付(日時)の降順、同じ日付(日時)のデータはIDの昇順 // カスタムフィールドの並び順(下記3つ指定) 'meta_key' => 'age', // ageという名前のフィールド 'orderby' => 'meta_value_num', // カスタムフィールドを数値として並び替え 'order' => 'ASC', // 昇順 )); |