query_posts

(1.5.0以降)
query_posts - 条件を指定して投稿情報をロードする

説明

array query_posts( mixed $query )
投稿情報を条件を指定して検索し、マッチしたすべてのデータをグローバル変数$postsに、その先頭データを$postにロードする。

パラメータ

  • $query
    検索条件を指定する文字列または連想配列。文字列の場合はname=valueの形式で指定し、複数の条件はname1=value1&name2=value2のように'&'の後に続ける。主なキーワードは次の通り(一部は連想配列のみで有効)。
    キーワード意味
    p投稿ID
    post__in取得する投稿IDを配列で指定(検索条件は必ず連想配列を使う)
    post__not_in除外する投稿IDを配列で指定(検索条件は必ず連想配列を使う)
    ignore_sticky_posts先頭固定表示(sticky)の投稿情報を含めない場合はtrueを指定(省略時はfalse)
    s検索キーワード(投稿タイトルおよび本文を検索)
    exact検索キーワードを完全一致にする場合はtrueを、部分一致の場合はfalseを指定(省略時はfalse)
    cat何れかのカテゴリーに属する投稿情報はカテゴリーIDを、何れのカテゴリーにも属さない投稿情報は-を付けたカテゴリーIDを指定(複数指定する場合は,で区切る)
    category__in何れかのカテゴリーに属する投稿情報をカテゴリーID(複数指定する場合は,で区切る文字列ではなく連想配列を使う)で検索
    category__not_in何れのカテゴリーにも属さない投稿情報をカテゴリーID(複数指定する場合は,で区切る連想配列を使う)で検索
    category_name投稿情報の属するカテゴリーのスラッグ(複数指定する場合は,で区切る)
    tag何れかのタグが設定された投稿情報はタグスラッグ(複数指定する場合は,で区切る)で、すべてのタグが設定された投稿情報はタグスラッグを+で区切って指定
    tag_slug__in何れかのタグが設定された投稿情報をタグスラッグ(複数指定する場合は,で区切る)で検索
    tag_slug__andすべてのタグが設定された投稿情報をタグスラッグ(複数指定する場合は,で区切る)で検索
    tag__in何れかのタグが設定された投稿情報をタグID(複数指定する場合は,で区切る)で検索
    tag__not_in何れかのタグも設定されていない投稿情報をタグID(複数指定する場合は,で区切る)で検索
    meta_keyカスタムフィールドの名前
    meta_valueカスタムフィールドの値
    author投稿者ID
    author_name投稿者名
    orderソート順を示すASCかDESC(省略時はDESC)
    orderbyソート対象を示すauthor、date、category、title、modified、ID、rand、'comment_count'など(省略時は投稿日時)。
    ※クエリーパラメータに'meta_key'が指定されている場合は、'meta_value'および'meta_value_num'が使用できる。
    ※[4.2.0]クエリーパラメータに'meta_query'が指定されている場合、その連想配列のキー名を使用できる。
    posts_per_page最大取得件数(省略時は管理画面「表示設定」の「1ページの投稿数」)
    offset取得開始位置(先頭は0。省略時は取得件数とページ番号から算出)
    post_type投稿タイプを示す'post'、'page'、カスタム投稿タイプ名またはそれらの配列('any'を指定することで登録されているすべて投稿タイプ)
    attachment添付情報名(post_name)
    attachment_id添付情報のID
    subpostattachmentのエイリアス
    subpost_idattachment_idのエイリアス
    name投稿名
    m投稿日時(書式はYYYY~YYYYMMDDhhmmss。数字以外は取り除かれる)
    hour投稿日時の時
    minute投稿日時の分
    second投稿日時の秒
    year投稿日時の年
    monthnum投稿日時の月
    day投稿日時の日
    date_query日付に関連する検索条件を配列で指定。使い方は「投稿日の検索が自由自在に」を参照。
    fields取得したい項目名('ids'の場合は投稿IDのみ、'id=>parent'の場合は投稿IDおよび親ID(投稿IDがキーで中身が親IDの配列)、そのほかの場合は全部)
    nopaging1を指定した場合、posts_per_pageの指定値を無視して条件にマッチする全件数を取得
    tax_queryタクソノミーに関連する条件を配列で指定。配列の形式は次の通り。
    array( 'relation' => 'AND',
    	array(
    		'taxonomy' => '',
    		'terms' => array(),
    		'include_children' => true,
    		'field' => 'term_id',
    		'operator' => 'IN'
    	),
    )
    ・'relation'には、'OR'または'AND'のいずれかを指定(省略時は'AND')。
    ・詳細条件を指定する配列は複数指定でき、'relation'の指定にしたがって条件を組み合わせる。
    ・詳細条件の'taxonomy'には、'category'、'post_tag'、'post_format'などのタクソノミー名を指定。
    ・詳細条件の'terms'には、タクソノミーの値を配列で指定。
    ・詳細条件の'field'には、'term_id'、'slug'などのフィールド名を指定。
    ・詳細条件の'operator'には、'AND'、'IN'、'NOT IN'の何れかを指定。
    meta_queryカスタムフィールドに関連する条件を配列で指定。配列の形式は次の通り。
    array( 'relation' => 'AND',
    	array(
    		'key' => 文字列,
    		'value' => 文字列または配列,
    		'compare' => '=',
    		'type' => 'CHAR'
    	),
    )
    ・'relation'には、'OR'または'AND'のいずれかを指定(省略時は'AND')。
    ・詳細条件を指定する配列は複数指定でき、'relation'の指定にしたがって条件を組み合わせる。
    ・詳細条件の'key'には、カスタムフィールドの名前を指定。
    ・詳細条件の'value'には、カスタムフィールドの値を文字列または配列(複数の値を指定する場合)で指定。
    ・詳細条件の'compare'には、条件として'='、'!='、'>'、'>='、'<'、'<='、'LIKE'、'NOT LIKE'、'IN'、'NOT IN'、'BETWEEN'、'NOT BETWEEN'の何れかを指定(省略時は'=')。
    ・詳細条件の'type'には、値('value')のデータ型として'NUMERIC'、'BINARY'、'CHAR'、'DATE'、'DATETIME'、'DECIMAL'、'SIGNED'、'TIME'、'UNSIGNED'の何れかを指定(省略時は'CHAR')。
    ※[4.2.0]複数のカスタムフィールドの条件を指定し、かつそれらの項目でソートしたい場合は、そのカスタムフィールド条件の配列のキー名に任意の文字列(下記の'meta1'や'meta2')を指定することでそれを'orderby'パラメータに指定できる。
    array( 'relation' => 'AND',
    	'meta1'=>array(
    		'key' => 文字列,
    		'value' => 値1,
    		'compare' => '>',
    		'type' => 'DECIMAL'
    	),
    	'meta2'=>array(
    		'key' => 文字列,
    		'value' => 値2,
    		'compare' => '<',
    		'type' => 'DATE'
    	),
    )

返り値

マッチしたすべてのデータが格納された配列を返す。データの中身は、基本的に投稿情報すべてになるが、パラメータとして'fields'の値が'ids'が指定された場合は投稿IDの配列、'id=>parent'を指定指定された場合はキーが投稿IDで中身が親投稿IDとなる。

注意

現バージョンでは、カテゴリーとタグに関する条件を同時に指定できない。また、WordPressシステムがデフォルトの条件でロードしていた投稿情報はこの呼び出しによって上書きされてしまうので、必要に応じて退避しておくか、WP_Queryクラスを使用する。
パラメータnameは投稿名であり、投稿タイトルではない。
パラメータmは実際の検索前に数字以外の文字は除外され、年月日時分秒の順に分割される(年のみ4桁、ほかは2桁)。具体的には、「m=2011年04月01日」と指定された場合は、「year=2011&monthnum=04&day=01」と同じ意味となる。

参考:
投稿日の検索が自由自在に
query_posts(WP_Queryクラス)でカテゴリーを絞り込む
query_posts(WP_Queryクラス)で投稿タグを絞り込む
query_posts(WP_Queryクラス)で'tax_query'を使いこなす
query_posts(WP_Queryクラス)でカスタムフィールドを使う
もうquery_postsは呼ばない

使用例

  • カテゴリー名が'日記'の投稿情報をロードする。
    <?php query_posts( 'category_name=日記' ); ?>

ソースファイル

/wp-includes/query.php

関連

お勧めコンテンツ

ツイート引用が簡単になる仕組み(2012年6月8日 登録)

WordPress 3.4では、投稿記事の中にツイートのURLを記述するだけで、投稿ページにそれっぽい表示をしてくれるようになる。ちょっと気になったので、その仕組みを追っかけてみた。

一定時間でログアウトする(2013年5月23日 登録)

ログイン関係を調べている関係で、wp_set_auth_cookie関数に行き着く。ログイン画面の「ログイン状態を保持する」がチェックされた場合、クッキーの有効期限は14日間。チェックされていない場合は、ブラウザが閉じるまで常に有効となっているんだね。

メディアライブラリに絞り込み用の「投稿タグ」を追加する(2014年6月24日 登録)

この記事は、先月投稿したコラム「メディア(attachment)を拡張してより便利に活用する」の続編。メディアで「投稿タグ」を追加するだけで「メディアライブラリ」ページの投稿一覧の中には「タグ」カラムが追加されるが、今回はその「投稿タグ」で絞り込み検索に対応してみる。

Widgets on dashboard:プラグイン作ってみました(2014年5月6日 登録)

サイトバーなどのページ構成パーツとしてウィジェットを利用し、ある程度頻繁に更新している場合、毎回ウィジェットページを表示するのはちょっとだけ面倒かも。そんなわけで、シンプルにダッシュボードで直接編集できればいいかなと思い、調べてみました。

投稿内容に応じてwpautopを制御する(2013年8月13日 登録)

投稿内容を表示するthe_content関数では、wpautop関数がフィルターの1つとして呼び出され、改行をbrタグに変換したり、pタグで調整したりする。この機能自体は便利なのだが、きちんとデザインされたHTMLソースを流し込んだ場合はこの機能は好ましくない。そんなわけで、記事内容に応じてwpautop関数を制御できないか考えてみた。

最終更新日時 : 2015-04-28 16:42