: WordPress

ちょいちょい忘れる『WP_Query』の使い方

WordPressの使い方

WordPressでテンプレート作る時に、「WP_Query」は一番使ってる気がするのになんだかんだで、いっつも検索して調べてるので、覚えるためにも大雑把にまとめてみます。

『WP_Query』ってどんな時に使うのか?

WordPress のページの一部でメインループではない、独自のループ設定をしたい時なんかに query_posts() の代わりに使ったりします。

『WP_Query』の使い方

使い方は、欲しい引数の条件を設定してループに教えてあげればいい。

例えば、カテゴリ ID 1 の記事を 5 件欲しかったら

<?php
$args = array(
  'cat' => 1,
  'posts_per_page' => 5
);
$the_query = new WP_Query( $args );
if ( $the_query->have_posts() ) :
  while ( $the_query->have_posts() ) : $the_query->the_post();
  //ここにループするテンプレート
  endwhile;
endif;
wp_reset_postdata();
?>

『WP_Query』で使える引数

著者引数

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

author(int)

著者 ID。(マイナス(-)を使用することで特定の著者を省くことができる)

author_name(string)

ユーザニックネーム(名前ではない)。

$args = array(
  'author' => 1,2,3, //省く場合は-1,-2,-3
  'author_name' => 'yama'
);

カテゴリ引数

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

cat(int)

カテゴリ ID。(マイナス(-)を使用することで特定のカテゴリを省くことができる)

category_name(string)

カテゴリスラッグ(カテゴリー名ではない)。

category__and(array)

カテゴリ ID の配列。指定した複数のカテゴリーすべてに含まれる投稿のみを表示。

category__in(array)

カテゴリ ID の配列。指定した複数のカテゴリーいずれかに含まれる投稿のみを表示。

category__not_in(array)

カテゴリ ID の配列。指定した複数のカテゴリーのいずれにもに含まれない投稿のみを表示。

$args = array(
  'cat' => 5,
  'category_name' => 'staff', 'news',
  'category__and' => array( 2, 6 ),
  'category__in' => array( 2, 6 ),
  'category__not_in' => array( 2, 6 )
);

タグ引数

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

tag(string)

タグスラッグ。

tag_id(int)

タグ ID 。

tag__and(array)

タグ ID を指定。コンマ区切りにした複数 ID の文字列も指定可能。

tag__in(array)

タグ ID の配列。指定した複数のタグのすべてを含む投稿のみを表示。

tag__not_in(array)

タグ ID の配列。指定した複数のタグのいずれも含まない投稿のみを表示。

tag_slug__and(array)

タグスラッグの配列。指定した複数のタグすべてを含む投稿のみを表示。

tag_slug__in(array)

タグスラッグの配列。指定した複数のタグのいずれかを含む投稿のみを表示。

$args = array(
  'cat' => 5,
  'category_name' => 'staff', 'news',
  'category__and' => array( 2, 6 ),
  'category__in' => array( 2, 6 ),
  'category__not_in' => array( 2, 6 )
);

タクソノミー引数

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

tax_query(array)

tax_queryはタクソノミークエリー引数の配列(入れ子の配列)をとる

‘tax_query’ => array(relation(string))

それぞれのタクソノミーを指定するのに ‘AND’ か ‘OR’ が使用できる。

‘tax_query’ => array(array(taxonomy(string)))

タクソノミー。

‘tax_query’ => array(array(field(string)))

ID(‘id’)かスラッグ(‘slug’)のどちらでタクソノミー項を選択するかを判定する。

‘tax_query’ => array(array(terms(int/string/array)))

タクソノミーの指定。

‘tax_query’ => array(array(include_children(bool)))

階層構造を持ったタクソノミーの場合に、子タクソノミー項を含めるかどうかを判定。デフォルトはtrue。

‘tax_query’ => array(array(operator(string)))

terms で指定された値の扱いを指定する。いずれかに合致(‘IN’)、いずれにも合致しない(‘NOT IN’)、全てに合致(‘AND’)が使用できる。

$args = array(
  'tax_query' => array(
    'relation' => 'AND',
      array(
        'taxonomy' => 'color',
        'field' => 'slug',
        'terms' => array( 'red', 'blue' ),
        'include_children' => true,
        'operator' => 'IN'
      ),
      array(
        'taxonomy' => 'actor',
        'field' => 'id',
        'terms' => array( 103, 115, 206 ),
        'include_children' => false,
        'operator' => 'NOT IN'
      )
    )
);

field に term_taxonomy_id を指定すると、データベースへのクエリーが条件毎に1つ軽減でき、負荷を軽減できるようです。

投稿&固定ページ引数

投稿または固定ページのパタメーターをもとにコンテンツを表示する。

p(int)

投稿の ID を指定する。

name(string)

投稿のスラッグを指定する。

page_id(int)

固定ページの ID を使用する。

pagename(string)

ページのスラッグを指定する。子ページを表示するには、スラッシュで区切られた親と子のスラッグを指定する。

post_parent(int)

ページ ID を指定して子ページを表示する。

post__in(array)

投稿の ID で表示に含めるものを指定する。’post__not_in’を同クエリー内では使えない。

post__not_in(array)

投稿の ID で表示に含めないものを指定する。’post__in’を同クエリー内では使えない。

$args = array(
  'p' => 1,
  'name' => 'hello-world',
  'page_id' => 1,
  'pagename' => 'sample-page',
  'pagename' => 'contact_us/canada',
  'post_parent' => 1,
  'post__in' => array(1,2,3),
  'post__not_in' => array(1,2,3)
);

タイプ&ステータス引数

特定のタイプやステータスに関連付けられた投稿を表示する。

post_type(string / array)

文字列又は配列で投稿タイプを指定する。デフォルト値は’post’で、投稿が表示される。

‘post_type’ => ‘post’

投稿。

‘post_type’ => ‘page’

固定ページ。

‘post_type’ => ‘revision’

リビジョン。

‘post_type’ => ‘attachment’

添付ファイル。デフォルトのWP_Queryでは’post_status’=>’published’となっているが、添付ファイルは’post_status’=>’inherit’なので、’inherit’または’any’を指定する必要がある。

‘post_type’ => ‘any’

リビジョンと’exclude_from_search’がtrueにセットされたものを除いて、すべてのタイプを含める。

‘post_type’ => ‘my-post-type’

カスタム投稿タイプ。

post_status(string / array)

投稿ステータスを指定する。デフォルトのは’publish’。

‘post_status’ => ‘publish’

公開された投稿または固定ページ。

‘post_status’ => ‘pending’

レビュー待ちの投稿。

‘post_status’ => ‘draft’

下書きの投稿。

‘post_status’ => ‘auto-draft’

コンテンツのない、新しく作成された投稿。

‘post_status’ => ‘future’

予約公開設定された投稿。

‘post_status’ => ‘private’

ログインしていないユーザーには見えない投稿。

‘post_status’ => ‘inherit’

リビジョン。get_childrenを参照。

‘post_status’ => ‘trash’

ゴミ箱に入った投稿。

‘post_status’ => ‘any’

投稿タイプで’exclude_from_search’がtrueにセットされているものを除いて、すべてのステータスの投稿を取得する。

$args = array(
  'post_type' => array(
    'post',
    'page',
    'revision',
    'attachment',
    'any',
    'my-post-type'
  ),
  'post_status' => array(
    'publish',
    'pending',
    'draft',
    'auto-draft',
    'future',
    'private',
    'inherit',
    'trash',
    'any'
  )
);

ページ送り引数

クエリーでページ送りを有効にするには、get_query_var( ‘page’ )を指定するようにしましょう。get_query_var( ‘paged’ )は、WordPress3.0.2 以降では互換性のために残されています。

posts_per_page(int)

1ページあたりに表示する投稿数。’posts_per_page’=1を指定するとすべての投稿を表示する。フィード中のクエリーの場合、WordPressは’posts_per_rss’の値でこのオプションを上書きするので注意してください。’post_limits’フィルターで最設定するか、’pre_option_posts_per_rss’フィルターで-1を返す。

posts_per_archive_page(int)

1ページあたりに表示する投稿数 – アーカイブページのみ。showpostsとposts_per_pageを、is_archive()かis_search()が有効の時に上書きします。

nopaging(bool)

すべての投稿を表示するか、ページ送りを使用するか。デフォルト値は’false’で、ページ送りを使用する。

‘paged’ => get_query_var(‘page’)

ページ数。通常”Older Entries”リンクで送ったページの数にしたがってそのページで表示される投稿が決まる。

$args = array(
  'posts_per_page' => 10,
  'posts_per_archive_page' => 10,
  'nopaging' => false,
  'paged' => get_query_var('page')
);

オフセット引数

offset(int)

先頭から省く投稿数。

$args = array(
  'offset' => 3
);

オーダー&オーダーバイ引数

投稿の並びを指定する。

order(string)

‘orderby’パラメーターで昇順(‘ASC’)・降順(‘DESC’)のどちらで並び替えるかを指定する。デフォルト値は’DESC’。それぞれ、Ascending(昇順の、上昇的な、上方に向かう)、Descending(下ってゆく,降下的な,下向きの、降順の)の略です。

‘ASC’ – 最低から最高に昇順 values (1, 2, 3; a, b, c)
‘DESC’ – 最高から最低に降順 values (3, 2, 1; c, b, a)

orderby(string)

どのパラメータ値で投稿を並び替えるかの指定。デフォルト値は’date’(日付)。

‘none’ – 並び替えない。
‘ID’ – 投稿IDで並び替える。
‘author’ – 著者で並び替える。
‘title’ – タイトルで並び替える。
‘date’ – 日付で並び替える。
‘modified’ – 更新日で並び替える。
‘parent’ – 親ページのIDで並び替える。
‘rand’ – ランダムに並び替える。
‘comment_count’ – コメント数で並び替える)。
‘menu_order’ – ページの表示順で並び替える。
‘meta_value’ – ‘meta_key=keyname’がクエリーに存在しなければならないので注意。アルファベット順でソートされる。
‘meta_value_num’ – 数値として並び替える。こちらも’meta_key=keyname’がクエリーに存在しなければならないので注意。

$args = array(
  'order' => 'DESC',
  'orderby' => 'date'
);

先頭固定表示引数

先頭固定表示ポストを表示、または無視する。

ignore_sticky_posts(bool)

先頭固定表示の投稿を無視するかどうか。デフォルトはfalseで、無視しない。先頭固定表示の投稿は返ってくる投稿一覧の先頭に追加され、本来の並び順の位置にも表示される。

$args = array(
ignore_sticky_posts' => false
);

時間引数

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

year(int)

4桁の年(例: 2011)。

monthnum(int)

月の数字(1から12)。

w(int)

年内の週(0から53)。MySQLのWEEKコマンドを使う。このモードは”start_of_week”オプションに依存します。

day(int)

月内の日(1から31)。

hour(int)

時間(0から23)。

minute(int)

分(0から60)。

second(int)

秒(0から60)。

$args = array(
'year' => 2012,
  'monthnum' => 3,
  'w' =>  25,
  'day' => 17,
  'hour' => 13,
  'minute' => 19,
  'second' => 30,
);

カスタムフィールド引数

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

meta_key(string)

カスタムフィールドのキー。

meta_value(string)

カスタムフィールドの値。

meta_value_num(number)

カスタムフィールドの値。

meta_compare(string)

‘meta_value’をテストする演算子。使える値は’!=’、’>’、’>=’、'<‘、’=’で、デフォルト値は’=’。

meta_query(array)

カスタムフィールドパラメーター(バージョン3.1以降で有効)。

‘meta_query’ => array(array(‘key'(string)))

カスタムフィールドのキー。

‘meta_query’ => array(array(‘value'(string/array)))

カスタムフィールドの値(注意: compareの値が’IN’、’NOT IN’、’BETWEEN’、’NOT BETWEEN’の際のみ配列をサポート)。

‘meta_query’ => array(array(‘type'(string)))

カスタムフィールドタイプ。使える値は’NUMERIC’(数値)、’BINARY’(バイナリ)、’CHAR’(文字列)、’DATE’(日付)、’DATETIME’(日時)、’DECIMAL’(少数)、’SIGNED’(符号付き整数)、’TIME’(時間)、’UNSIGNED’(符号なし整数)。デフォルト値は’CHAR’。

compare(string)

テストする演算子。使える値は’=’、’!=’、’>’、’>=’、'<‘、'<=’、’LIKE’、’NOT LIKE’、’IN’、’NOT IN’、’BETWEEN’、’NOT BETWEEN’。デフォルト値は’=’。

$args = array(
'meta_key' => 'key',
  'meta_value' => 'value',
  'meta_value_num' => 10,
  'meta_compare' => '=',
  'meta_query' => array(
    array(
      'key' => 'color',
      'value' => 'blue',
      'type' => 'CHAR',
      'compare' => '='
    ),
    array(
      'key' => 'price',
      'value' => array( 1,200 ),
      'compare' => 'NOT LIKE'
    )
);

権限引数

ユーザーが適切な権限を持っていれば、公開済みの投稿と同様に、プライベートの記事を表示します。

perm(string)

使える値は’readable’と’editable’。

$args = array(
'perm' => 'readable'
);

一通り覚えちゃえば何でも出来る気になる!!

思いのほか、引数がいっぱいあって、色んな事ができる。あとは、この引数を使ったアイデアだけですね。

それでは。