当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「テンプレートタグ/query posts」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(2006年8月に作成した翻訳データの流し込み(暫定版、要フォーマット))
 
(パラメータ: WP_Query との整合性を保つため、関数リファレンス/WP_Query を参照するように誘導。)
 
(11人の利用者による、間の30版が非表示)
1行目: 1行目:
* 書式: <?php get_posts('arguments'); ?>  
+
<div id="Description">
* 説明: ループ内でクエリーを変更するために使う。詳しくは、[[The_Loop|WordPressループ解説ページ]]を参照。
+
== 説明 ==
* 位置: ループ内
+
</div>
* 引数:
+
 
** numberposts (整数)- 取得する記事の数。デフォルト値は5。
+
'''''注 1:''''' この関数はプラグインまたはテーマの中で使われることを想定されていません。後ほど出てくる説明にあるように、メインクエリーを変更するにはパフォーマンス面でも優れたより良いオプションが存在します。
** offset (整数)- 最新記事からのオフセット。例えば2を指定すると、最新記事2つは無視され、その前の記事を1つ目として取得する。デフォルト値は0。
+
 
** category (整数)- 出力するカテゴリーのID。デフォルト値は空(すべてのカテゴリーを出力)。
+
'''''注 2:''''' query_posts() はページ内のメインクエリーを書き換え、新しいクエリーのインスタンスと置き換えるために使う関数としては過度に単純化され、問題が発生しやすい方法です。非効率的で(SQL クエリを再実行します)、一部の状況では適切に実行することもできません(特にページング処理)。モダンな WordPress コードではもっと安定したメソッドを使うべきです。例えば[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]] フックを使った方法などです。ひとことで言うと、query_posts() は決して使うべきではありません。
** orderby (規定値)- 取得した記事の並べ方。さらに、これら以外のデータベースのwp_postテーブル内のフィールド値も指定できる。
+
 
*** post_title(記事名順)
+
以上のことをしっかり理解し、この関数を賢く活用してください。
*** post_date(記事の投稿日)
+
 
*** post_modified(記事の更新日順)
+
[[Image:avoid_query_posts.png|500px|right|WP_Query, query_posts and get_posts use cases explained]]
*** ID(デフォルト。記事ID順)
+
 
*** post_author(投稿者のID順)
+
<sup>[http://wordpress.stackexchange.com/questions/1753/when-should-you-use-wp-query-vs-query-posts-vs-get-posts 画像のソース: WP.SE/Andrey "Rarst" Savchenko]</sup>
*** post_name(記事の投稿スラッグ順)
+
 
** order (整数)- 取得した記事の並び順。orderbyで指定した並べ方に基づく。
+
<tt>query_posts()</tt> はWordPressが投稿を表示するのに使用しているメインクエリーを置き換える手段です。これはメインクエリーを一旦横に置いておき、新しいクエリーで上書きします。<tt>query_posts</tt> を呼び出したあとは、クエリーの改変を戻すために、<tt>wp_reset_query()</tt> を呼び出し、オリジナルのメインクエリーを復活させる必要があります。
*** asc(デフォルト。orderbyで指定したルールに従い、昇順に並べる)
+
 
*** desc(降順に並べる)
+
<tt>query_posts</tt> を使うことによって、ページ上のメインクエリーが置き換えられ、ページの読み込み速度に影響を与えることに留意してください。最悪の場合、倍かそれ以上の処理が発生します。簡単に使える代わりに、この関数は混乱と問題を引き起こす傾向があります。下記の注意をご覧ください。
* コード記述例:
+
 
<pre><nowiki><?php
+
一般的な投稿の取得には、[[関数リファレンス/WP_Query|WP_Query]] または [[テンプレートタグ/get_posts|get_posts]] を使ってください。
  $posts = get_posts('numberposts=3&category=1');
+
 
 +
<tt>query_posts</tt> の代わりに次のようにすることを'''強く'''推奨します:
 +
# アクション [[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]] を用いる。
 +
# pre_get_posts にフックした関数の中で [[関数リファレンス/is_main_query|is_main_query()]] を使ってメインクエリーであるかチェックする。
 +
# メインクエリーの場合のみ、それを変更する。
 +
 
 +
たとえば、ホームで、ふつうは最新の10件の投稿が表示されるでしょう。もし5件だけ表示したいのであれば <tt>query_posts()</tt> を使ってこのように書くことができます(ページ送りについては無視しています):
 +
 
 +
<pre>query_posts( 'posts_per_page=5' );</pre>
 +
 
 +
同じことを [[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]] を使って行うなら functions.php に次のように書きます:
 +
 
 +
<pre>
 +
function five_posts_on_homepage( $query ) {
 +
    if ( $query->is_home() && $query->is_main_query() ) {
 +
        $query->set( 'posts_per_page', '5' );
 +
    }
 +
}
 +
add_action( 'pre_get_posts', 'five_posts_on_homepage' );
 +
</pre>
 +
 
 +
'''注意:''' pre_get_posts アクションは[[Pages|固定ページ]]のリクエストでは動作しません。
 +
 
 +
<div id="Caveats">
 +
== 注意 ==
 +
</div>
 +
<tt>query_posts()</tt> はデータベースに問い合わせて投稿の一覧を生成するための、数ある方法のひとつに過ぎません。<tt>query_posts()</tt> を使うと決める前に、欠点も理解しておいてください。
 +
 
 +
<div id="Alters Main Loop">
 +
=== メインループを変更する ===
 +
</div>
 +
<tt>query_posts()</tt> はメインループを変更するためのものです。<tt>query_posts()</tt> はそのために、メインループを生成するクエリーを置き換えます。いったん <tt>query_posts()</tt> を使うと、投稿にもとづいたグローバル変数やテンプレートタグも変更されます。<tt>query_posts()</tt> を呼び出したあとは、条件分岐タグも置き換えられてしまいます。このことが意図しない結果を引き起こすかもしれません。
 +
 
 +
<div id="Secondary Loops">
 +
=== 派生的なループ ===
 +
</div>
 +
派生的な一覧 (例えばページの下部に関連記事を表示したり、サイドバーのウィジェットでリンクの一覧を出したり等) を表示したい場合は、[[関数リファレンス/WP_Query|WP_Query]] の新しいインスタンスを生成するか、[[テンプレートタグ/get_posts|get_posts()]] を使ってください。
 +
 
 +
もし <tt>query_posts()</tt> を使う場合は、用が済んだら必ず <tt>wp_reset_query()</tt> を呼び出してください。
 +
 
 +
<div id="Pagination">
 +
=== ページ送り ===
 +
</div>
 +
'paged' クエリー引数を適切に指定していないと、ページ送りが正しく動作しない可能性があります。「[[Pagination#Adding_the_.22paged.22_parameter_to_a_query|クエリに "paged" パラメーターを追加]]」を参照してください。
 +
 
 +
<div id="Additional SQL Queries">
 +
=== SQLクエリーが追加発行される ===
 +
</div>
 +
もし <tt>query_posts</tt> をテンプレートで使用する場合、そのテンプレートを読み込むまでに WordPress はすでにデータベースへの問い合わせを実行し、データの取り出しを終えています(どのテンプレートを読み込むかが決まったということは、すでに処理が終わっているということですから!)。そのため、<tt>query_posts()</tt> を使ってデフォルトのクエリーを上書きして結果を得るには、どうしても再度データベースに問い合わせし再計算する必要があります。
 +
 
 +
このことは、小規模なブログベースのウェブサイトを扱っているのであれば、必ずしも問題であるとは言えません。しかしデータベースが大きい大規模でトラフィックの多いウェブサイトの開発者であれば、デフォルトのクエリーが呼び出される前に直接変更するなどの代替案を検討するほうがいいかもしれません。[[プラグイン_API/アクションフック一覧/request|request]] フィルターでまさにこれを実現できるでしょう。
 +
 
 +
データベースへ問い合わせる SQL を生成するのに使われる内部的な <tt>$query</tt> オブジェクトを改変するには、'parse_query' と '[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]]' フィルターも利用できます。
 +
 
 +
 
 +
<div id="Usage">
 +
== 使い方 ==
 +
</div>
 +
<pre>
 +
<?php
 +
// クエリ(メインクエリを改変)
 +
query_posts( $args );
 +
 
 +
// ループ(改変したメインクエリ)
 +
if ( have_posts() ) :
 +
    while ( have_posts() ) : the_post();
 +
        echo '<li>';
 +
        the_title();
 +
        echo '</li>';
 +
    endwhile;
 +
else:
 +
    // 何も取得されなかった
 +
endif;
 +
 
 +
// クエリをリセット
 +
wp_reset_query();
 
?>
 
?>
<h2>最新アウトドア関連情報</h2>
+
</pre>
   <ul>
+
 
 +
[[テンプレート]]ファイルのひとつに対して、[[ループ]]が始まる前の部分に <tt>query_posts()</tt> の呼び出しを記述します。<tt>WP_Query</tt> オブジェクトがそのパラメータを使って新しい SQL クエリを生成します。このようにすると、WordPress は URL 経由で受け取った他のパラメータを無視します(ページ番号やカテゴリーなど)。
 +
 
 +
<div id="Preserving_the_Original_Query_Parameters">
 +
=== オリジナルクエリの保持(ページングなど)===
 +
</div>
 +
デフォルトでは query_posts を実行すると、引数で指定した変数を除きページング,カテゴリー,日付などの現在のページのクエリ変数はすべて上書きされます。この時、オリジナルのクエリを保持したい場合は、<tt>query_poats()</tt> の引数にグローバル変数である <tt>$query_string</tt>を用いることができます。
 +
 
 +
例えば、残りの投稿文字列に影響をおよぼすこと無く投稿の表示順を保持する時、[[ループ]]の前に下記を記述することができます。
 +
 
 +
<pre>
 +
global $query_string;
 +
query_posts( $query_string . '&order=ASC' );
 +
</pre>
 +
 
 +
<tt>query_posts()</tt> をこのように用いる時、<nowiki>''</nowiki>で囲まれたパラメーターはアンド記号 <tt>&amp;</tt> で始まる必要があります。
 +
 
 +
 
 +
あるいは、元のクエリ配列を引数配列に統合することもできます。
 +
 
 +
<pre>
 +
global $wp_query;
 +
$args = array_merge( $wp_query->query, array( 'post_type' => 'product' ) );
 +
query_posts( $args );
 +
</pre>
 +
 
 +
 
 +
<div id="Combining_Parameters">
 +
=== 引数の組み合わせ ===
 +
</div>
 +
引数はアンド記号 (<tt>&amp;</tt>) を使って複数組み合わせて指定することができます:
 +
 
 +
query_posts( 'cat=3&year=2004' );
 +
 
 +
「最新の投稿」ページで、カテゴリー ID が 13 かつ今月の投稿を表示する場合:
 +
 
 +
if (is_home()) {
 +
        query_posts( $query_string . '&cat=13&monthnum=' . date( 'n', current_time( 'timestamp' ) ) );
 +
}
 +
 
 +
[[Version 2.3|バージョン 2.3]] で、カテゴリー ID 1 と 3 に含まれる投稿を2件、タイトルの降順で表示する場合:
 +
 
 +
query_posts( array( 'category__and' => array(1,3), 'posts_per_page' => 2, 'orderby' => 'title', 'order' => 'DESC' ) );
 +
 
 +
カテゴリー ID が 1 で "apples" のタグ付けがされた投稿を表示する場合:
 +
 
 +
query_posts( 'cat=1&tag=apples' );
 +
 
 +
複数のタグを同時に指定する場合は「+」を用います。下記はカテゴリー ID が 1 で、"apples"と"oranges"のタグがついた投稿を表示します:
 +
 
 +
query_posts( 'cat=1&tag=apples+oranges' );
 +
 
 +
 
 +
<div id="Parameters">
 +
== パラメータ ==
 +
</div>
 +
 
 +
<p class="information">'''参考:'''パラメータの詳細は [[クラスリファレンス/WP_Query#Parameters|WP_Query クラスのパラメータの説明]]をご覧ください。</p>
 +
 
 +
以下の用例は WP_Query オブジェクトに対しても利用できます。
 +
 
 +
<!-- ############ ここから旧記述。WP_Query と整合させるため削除 ############
 +
ここでの記述例は <tt>[[関数リファレンス/WP_Query|WP_Query]]</tt> オブジェクトでも使えるものですが、もちろんこれが全てではありません。パラメーターを組み合わせることで、より実用的なクエリが可能になります。パラメーターの詳細は[[関数リファレンス/WP_Query#Parameters|こちら]]を参照してください。
 +
 
 +
<div id="Author Parameters">
 +
=== 投稿者引数 ===
 +
</div>
 +
ある投稿者に関連付けられた投稿を表示する。
 +
 
 +
* '''<tt>author</tt>''' (''整数'') - ユーザー ID。
 +
* '''<tt>author_name</tt>''' (''文字列'') - '<tt>user_nicename</tt>' (姓・名・ニックネームではなく)。
 +
 
 +
'''ある投稿者の投稿を表示する'''
 +
 
 +
ユーザーIDを用いて投稿者を特定する場合:
 +
 
 +
query_posts( 'author=123' );
 +
 
 +
'<tt>user_nicename</tt>' (ユーザーのスラッグ)を用いて投稿者を特定する場合:
 +
 
 +
query_posts( 'author_name=rami' );
 +
 
 +
'''複数投稿者の投稿を表示する'''
 +
 
 +
複数の投稿者の投稿を表示する場合:
 +
 
 +
query_posts( 'author=2,6,17,38' );
 +
 
 +
'''ある投稿者の投稿を表示しない'''
 +
 
 +
特定の投稿者「以外」の投稿を全て表示させる場合は、IDの前に <tt>'-' (マイナス)</tt> をつけます:
 +
 
 +
query_posts( 'author=-123' );
 +
 
 +
<div id="Category_Parameters">
 +
=== カテゴリー引数 ===
 +
</div>
 +
指定したカテゴリーに分類された投稿を表示する。
 +
 
 +
* '''<tt>cat</tt>''' (整数)- カテゴリー ID。
 +
* '''<tt>category_name</tt>''' (文字列)- カテゴリースラッグを指定(カテゴリー名ではない)。
 +
* '''<tt>category__and</tt>''' (配列)- カテゴリー ID の配列。指定した複数のカテゴリーすべてに含まれる投稿のみを表示。
 +
* '''<tt>category__in</tt>''' (配列)- カテゴリー ID の配列。指定した複数のカテゴリーいずれかに含まれる投稿のみを表示。
 +
* '''<tt>category__not_in</tt>''' (配列)- カテゴリー ID の配列。指定した複数のカテゴリーのいずれにもに含まれない投稿のみを表示。
 +
 
 +
'''ひとつのカテゴリーの投稿を表示'''
 +
 
 +
ID で指定したカテゴリー(とその子孫カテゴリー)に含まれる投稿のみを表示。
 +
 
 +
query_posts( 'cat=4' );
 +
 
 +
カテゴリースラッグで指定したカテゴリー(とその子孫カテゴリー)に含まれる投稿のみを表示。
 +
 
 +
query_posts( 'category_name=staff' );
 +
 
 +
'''複数のカテゴリーの投稿を表示'''
 +
 
 +
ID で指定した複数のカテゴリーに含まれる投稿のみを表示。
 +
 
 +
query_posts( 'cat=2,6,17,38' );
 +
 
 +
スラッグで指定した複数のカテゴリーに含まれる投稿のみを表示。
 +
 
 +
query_posts( 'category_name=staff,news' );
 +
 
 +
'''指定カテゴリーの投稿を除外'''
 +
 
 +
'-'(マイナス)記号を前につけたカテゴリー ID '以外' の投稿を表示。
 +
 
 +
query_posts( 'cat=-3' );
 +
 
 +
'''複数カテゴリーの指定方法'''
 +
 
 +
ID で指定した複数のカテゴリーすべてに含まれるカテゴリーを表示。以下はカテゴリー ID 2 と 6 の両方に含まれる投稿を表示。
 +
 
 +
query_posts( array( 'category__and' => array( 2, 6 ) ) );
 +
 
 +
カテゴリー ID 2 または 6 に含まれる投稿を表示するには、前述の cat か category__in(こちらは子孫カテゴリーを含みません)を使う。
 +
 
 +
query_posts( array( 'category__in' => array( 2, 6 ) ) );
 +
 
 +
また、以下の方法でも複数のカテゴリーを除外できる。
 +
 
 +
query_posts( array( 'category__not_in' => array( 2, 6 ) ) );
 +
 
 +
<div id="Tag_Parameters">
 +
=== タグ引数 ===
 +
</div>
 +
指定したタグがつけられた投稿を表示する。
 +
* '''<tt>tag</tt>''' (文字列)- タグスラッグを指定。
 +
* '''<tt>tag_id</tt>''' (整数)- タグ ID を指定。コンマ区切りにした複数 ID の文字列も指定可能。
 +
* '''<tt>tag__and</tt>''' (配列)- タグ ID の配列。指定した複数のタグのすべてを含む投稿のみを表示。
 +
* '''<tt>tag__in</tt>''' (配列)- タグ ID の配列。指定した複数のタグのいずれかを含む投稿のみを表示。
 +
* '''<tt>tag__not_in</tt>''' (配列)- タグ ID の配列。指定した複数のタグのいずれも含まない投稿のみを表示。
 +
* '''<tt>tag_slug__and</tt>''' (配列)- タグスラッグの配列。指定した複数のタグすべてを含む投稿のみを表示。
 +
* '''<tt>tag_slug__in</tt>''' (配列)- タグスラッグの配列。指定した複数のタグのいずれかを含む投稿のみを表示。
 +
 
 +
'''指定した1つのタグを含む投稿を表示'''
 +
 
 +
タグのスラッグを用いて特定のタグのみ表示させる場合:
 +
 
 +
query_posts('tag=cooking');
 +
 
 +
タグのIDを用いて特定のタグのみ表示させる場合:
 +
 
 +
query_posts( 'tag_id=13' );
 +
 
 +
 +
'''指定した複数のタグを含む投稿を表示'''
 +
 
 +
指定したタグのいずれかを含む投稿を表示。
 +
 
 +
query_posts('tag=bread,baking');
 +
 
 +
指定した3つのタグすべてを含む投稿を表示。
 +
 
 +
query_posts('tag=bread+baking+recipe');
 +
 
 +
'''複数タグの指定方法'''
 +
 
 +
タグ ID 37 と 47 の両方を含む投稿を表示。
 +
 
 +
query_posts( array( 'tag__and' => array( 37, 47 ) ) );
 +
 
 +
タグ ID 37 または 47 のいずれかを含む投稿を表示するには、前述の <tt>tag</tt> か <tt>tag__in</tt> を使う。
 +
 
 +
query_posts( array( 'tag__in' => array( 37, 47 ) ) );
 +
 
 +
タグ ID 37 と 47 のいずれも含まない投稿を表示。
 +
 
 +
query_posts( array( 'tag__not_in' => array( 37, 47 ) ) );
 +
 
 +
<tt>tag_slug__in</tt> と <tt>tag_slug__and</tt> はタグスラッグを指定する他は上記と同様です。
 +
 
 +
[http://boren.nu/archives/2007/10/01/taxonomy-intersections-and-unions/ Ryan's discussion of Tag intersections and unions] も参照してください。
 +
 
 +
<div id="Taxonomy_Parameters">
 +
=== タクソノミー引数 ===
 +
</div>
 +
特定の[[カスタム分類|タクソノミー]]に関連付けられた投稿を表示。
 +
 
 +
*  '''<tt>{tax}</tt>''' (''文字列'') - タクソノミースラッグ。
 +
*  '''<tt>tax_query</tt>''' (''配列'') - .
 +
 
 +
'''シンプルタクソノミークエリ'''
 +
 
 +
'people' カスタムタクソノミーで 'bob' というスラッグのタグがつけられた投稿を表示。
 +
 
 +
query_posts( array( 'people' => 'bob', 'posts_per_page' => 10 ) );
 +
 
 +
'''複数のタクソノミー処理''' ([[Version 3.1|バージョン 3.1]] 以降)
 +
 
 +
複数のカスタムタクソノミーの投稿を表示。
 +
 
 +
<pre>
 +
$args = array(
 +
'tax_query' => array(
 +
'relation' => 'AND',
 +
array(
 +
'taxonomy' => 'movie_janner',
 +
'field' => 'slug',
 +
'terms' => array( 'action', 'commedy' ),
 +
),
 +
array(
 +
'taxonomy' => 'actor',
 +
'field' => 'id',
 +
'terms' => array( 103, 115, 206 ),
 +
'operator' => 'NOT IN',
 +
)
 +
)
 +
)
 +
query_posts( $args );
 +
</pre>
 +
 
 +
<div id="Author_Parameters">
 +
=== 投稿者引数 ===
 +
</div>
 +
指定した ID や名前の投稿者による投稿を表示する。
 +
*  <tt>author=3</tt> (整数)- 表示する投稿者の ID を指定。
 +
*  <tt>author=-3</tt> (整数)- 除外する投稿者の ID を指定。
 +
*  <tt>author_name=Harriet</tt> (文字列)- 投稿者のニックネームを指定(日本語も可)。
 +
 
 +
'''注意:''' <tt>author_name</tt> は <tt>user_nicename</tt> フィールドの値を指定します。<tt>author</tt> には ID を指定します。
 +
 
 +
'''author=1 のすべての [[Pages|固定ページ]] をタイトル順, 先頭固定表示無しで表示'''
 +
query_posts('caller_get_posts=1&author=1&post_type=page&post_status=publish&orderby=title&order=ASC');
 +
 
 +
<div id="Post_.26_Page_Parameters">
 +
=== 投稿・固定ページ引数 ===
 +
</div>
 +
ブログ投稿や固定ページに関連付けられた post を表示。
 +
 
 +
* '''<tt>p</tt>''' (''整数'')- 投稿 ID を指定。
 +
* '''<tt>name</tt>''' (''文字列'') - [[ブログ入門#Post Slugs|投稿スラッグ]] を指定。
 +
* '''<tt>page_id</tt>''' (''整数'') - 固定ページ ID を指定。
 +
* '''<tt>pagename</tt>''' (''文字列'') - 固定ページスラッグを指定。
 +
* '''<tt>post_parent</tt>''' (''整数'') - 固定ページ ID を指定。子ページのみを返す。
 +
* '''<tt>post__in</tt>''' (''配列'') - 投稿IDを用いて、それのみを指定する。
 +
* '''<tt>post__not_in</tt>''' (''配列'') - 投稿IDを用いて、それ以外を指定する。
 +
* '''<tt>post_type</tt>''' (''string'' / ''array'') - [[Post Types|投稿タイプ]]を用いて指定する。初期値は <tt>post</tt>';
 +
** '<tt>post</tt>'
 +
** '<tt>page</tt>'
 +
** '<tt>revision</tt>'
 +
** '<tt>attachment</tt>'
 +
** '<tt>any</tt>' - revision以外すべてのタイプ
 +
** カスタム投稿タイプ (例: movies)
 +
* '''<tt>post_status</tt>''' (''文字列'' / ''配列'') - 公開状態を用いて指定する。投稿の[[Post Status]]を参照, 初期値は '<tt>publish</tt>';
 +
** '<tt>publish</tt>' - 公開になっている投稿もしくは固定ページ
 +
** '<tt>pending</tt>' - レビュー待ち
 +
** '<tt>draft</tt>' - 下書きの投稿もしくは固定ページ
 +
** '<tt>auto-draft</tt>' - 本文のない、自動下書き投稿
 +
** '<tt>future</tt>' - 未来の日付で公開される投稿
 +
** '<tt>private</tt>' - 非公開になっている投稿
 +
** '<tt>inherit</tt>' - リビジョン。 [[関数リファレンス/get_children|get_children]]も参照のこと。 
 +
** '<tt>trash</tt>' - ゴミ箱にある投稿([[Version 2.9]]で追加されたパラメータ)
 +
 
 +
'''ID を指定して投稿・固定ページを表示'''
 +
 
 +
特定の ID の投稿を表示。
 +
 
 +
query_posts( 'p=7' );
 +
 
 +
特定の ID の固定ページを表示。
 +
 
 +
query_posts( 'page_id=7' );
 +
 
 +
'''スラッグを指定して投稿・固定ページを表示'''
 +
 
 +
投稿を表示:
 +
 
 +
query_posts( 'name=about-my-life' );
 +
 
 +
固定ページを表示:
 +
 
 +
query_posts( 'pagename=contact' );
 +
 
 +
'''子ページを表示'''
 +
 
 +
親ページ・子ページのスラッグを指定して表示(スラッグはスラッシュで区切る):
 +
 
 +
query_posts( 'pagename=parent_slug/child_slug' );
 +
 
 +
親ページ ID を指定して子ページを表示:
 +
 
 +
query_posts( 'post_parent=93' );
 +
 
 +
'''複数の投稿/固定ページの取り扱い'''
 +
 
 +
特定の投稿IDのみを表示:
 +
 
 +
query_posts( array( 'post__in' => array( 2, 5, 12, 14, 20 ) ) );
 +
 
 +
特定の投稿IDを除外して表示:
 +
 
 +
query_posts( array( 'post__not_in' => array( 2, 5, 12, 14, 20 ) ) );
 +
 
 +
注意: 同一のクエリーで 'post__in' と 'post__not_in' の併用はできません。
 +
 
 +
'''投稿タイプを指定して投稿を表示'''
 +
 
 +
ページのみを表示。
 +
 
 +
query_posts( 'post_type=page' );
 +
 
 +
'<tt>any</tt>' 投稿タイプを表示 (履歴以外のすべてのタイプを取得)。
 +
 
 +
query_posts( 'post_type=any' );
 +
 
 +
カスタム投稿タイプを含む複数の投稿タイプを表示。
 +
 
 +
query_posts( array( 'post_type' => array( 'post', 'page', 'movie', 'book' ) ) );
 +
 
 +
'''状態を指定して投稿を表示'''
 +
 
 +
下書きのみを表示。
 +
 
 +
query_posts( 'post_status=draft' );
 +
 
 +
複数の投稿状態を指定して表示。
 +
 
 +
query_posts( array( 'post_status' => array( 'pending', 'draft', 'future' ) ) );
 +
 
 +
<div id="Pagination_Parameters">
 +
 
 +
=== ページ送り引数 ===
 +
</div>
 +
 
 +
[[関数リファレンス/WP Query#Pagination_Parameters|<tt>WP_Query</tt> の「ページ送りパラメータ」セクション]]を見てください。
 +
 
 +
<div id="Offset_Parameter">
 +
 
 +
=== オフセット引数 ===
 +
</div>
 +
表示される投稿の先頭から指定した件数をスキップします。
 +
* <tt>offset</tt> (整数)- 投稿の先頭からスキップする件数を指定。
 +
 
 +
以下は、最新の投稿(1件)に続く5件の投稿を表示。
 +
 
 +
query_posts('posts_per_page=5&offset=1');
 +
 
 +
<div id="Order_Orderby_Parameters">
 +
=== 並び順・並べ替え引数 ===
 +
</div>
 +
取得した投稿を並べ替える。
 +
 
 +
* '''<tt>order</tt>''' (''文字列'') - '<tt>orderby</tt>' 引数を使った際の並び順
 +
** '<tt>ASC</tt>' - 昇順。小さい値から大きい値の順(1, 2, 3; a, b, c)
 +
** '<tt>DESC</tt>' - 降順。大きい値から小さい値の順(3, 2, 1; c, b, a)
 +
 
 +
* '''<tt>orderby</tt>''' (''文字列'') - 記事を並べ替える条件:
 +
** '<tt>none</tt>' - 順番指定なし([[Version 2.8|バージョン 2.8]] 以降のみ)
 +
** '<tt>ID</tt>' - 投稿IDで並べ替え
 +
** '<tt>author</tt>' - 記事の著者名で並べ替え
 +
** '<tt>title</tt>' - 記事のタイトルで並べ替え
 +
** '<tt>date</tt>' - 記事の投稿日で並べ替え
 +
** '<tt>modified</tt>' - 記事の更新日で並べ替え
 +
** '<tt>parent</tt>' - 投稿または固定ページの親のIDで並べ替え
 +
** '<tt>rand</tt>' - ランダムに並べ替え
 +
** '<tt>comment_count</tt>' - コメント数で並べ替え([[Version 2.9|バージョン 2.9]] 以降)
 +
** '<tt>menu_order</tt>' - ページの「順序」で並べ替え。たいていの場合 [[Pages|固定ページ]] (''順序'' フィールドはページ属性欄にあります) や [[添付ファイル]] (並び順は「ギャラリーを作成」ダイアログで、ドラッグ&ドロップで指定します)の表示に使われますが、どのような投稿タイプでも別個の '<tt>menu_order</tt>' 引数を使えます (すべて、初期値は <var>0</var>です)。
 +
** '<tt>meta_value</tt>' - 引数 '<tt>meta_key=keyname</tt>' と同時に使う必要があります。また、カスタムフィールドの値が数字の場合、期待しない結果になることがあります (例: 1, 3, 4, 6, 34, 56…… と並べようとしても 1, 3, 34, 4, 56, 6……となる)。
 +
** '<tt>meta_value_num</tt>' - カスタムフィールドの数値で並べ替え ([[Version 2.8]]より)。
 +
** '<tt>post__in</tt>' - Preserve post ID order given in the post__in array (available with Version 3.5).
 +
 
 +
'''記事タイトルの降順で並び替えて表示する'''
 +
 
 +
記事タイトルの降順で並び替えて表示:
 +
 
 +
query_posts( 'orderby=title&order=DESC' );
 +
 
 +
'''ランダムに表示する'''
 +
 
 +
ランダムに表示:
 +
 
 +
query_posts( 'orderby=rand&posts_per_page=1' );
 +
 
 +
'''参照数の多い記事を表示する'''
 +
 
 +
コメント数で並べ替えて表示:
 +
 
 +
query_posts( 'orderby=comment_count&order=DESC' );
 +
 
 +
<div id="Sticky_Post_Parameters">
 +
 
 +
=== 先頭固定投稿引数 ===
 +
</div>
 +
 
 +
[[関数リファレンス/WP Query#Sticky_Post_Parameters|<tt>WP_Query</tt> の「先頭固定投稿パラメータ」セクション]]を見てください。
 +
 
 +
<div id="Time_Parameters">
 +
 
 +
=== 日時引数 ===
 +
</div>
 +
指定した日時の間に投稿された投稿を表示。
 +
 
 +
* '''<tt>year</tt>''' (''int'') - 4桁の年(例:2011)
 +
* '''<tt>monthnum</tt>''' (''int'') - 月(1〜12)
 +
* '''<tt>w</tt>''' (''int'') - 0〜53 で年間の週を指定。[http://dev.mysql.com/doc/refman/5.1/ja/date-and-time-functions.html#function_week MySQL WEEK command Mode=1] を使っている。
 +
* '''<tt>day</tt>''' (''int'') - 日(1〜31)
 +
* '''<tt>hour</tt>''' (''int'') - 時(0〜23)
 +
* '''<tt>minute</tt>''' (''int'') - 分 (0〜60)
 +
* '''<tt>second</tt>''' (''int'') - 秒(0〜60)
 +
 
 +
'''今日の投稿を表示'''
 +
 
 +
$today = getdate();
 +
query_posts( 'year=' . $today["year"] . '&monthnum=' . $today["mon"] . '&day=' . $today["mday"] );
 +
 
 +
'''現在の週の投稿のみを表示'''
 +
 
 +
$week = date('W');
 +
$year = date('Y');
 +
query_posts( 'year=' . $year . '&w=' . $week );
 +
 
 +
'''12月20日の投稿を表示'''
 +
 
 +
query_posts( 'monthnum=12&day=20' );
 +
 +
'''Note:''' The queries above return posts for a specific date period in history, i.e. "Posts from X year, X month, X day". They are unable to fetch posts from a timespan relative to the present, so queries like "Posts from the last 30 days" or "Posts from the last year" are not possible with a basic query, and require use of the posts_where filter to be completed. The examples below use the posts_where [[Plugin_API#Filters | filter]], and should be modifyable for most time-relative queries.
 +
 
 +
'''2009年3月15日の投稿を表示'''
 +
 
 +
<pre>
 +
// Create a new filtering function that will add our where clause to the query
 +
function filter_where( $where = '' ) {
 +
// posts for March 1 to March 15, 2010
 +
$where .= " AND post_date >= '2010-03-01' AND post_date < '2010-03-16'";
 +
return $where;
 +
}
 +
add_filter( 'posts_where', 'filter_where' );
 +
 
 +
query_posts( $query_string );
 +
</pre>
 +
 
 +
'''最近30日間の投稿を表示'''
 +
<pre>
 +
<pre>
 +
// Create a new filtering function that will add our where clause to the query
 +
function filter_where( $where = '' ) {
 +
// posts in the last 30 days
 +
$where .= " AND post_date > '" . date('Y-m-d', strtotime('-30 days')) . "'";
 +
return $where;
 +
}
 +
add_filter( 'posts_where', 'filter_where' );
 +
 
 +
query_posts( $query_string );
 +
</pre>    
 +
 
 +
'''30〜60日前の投稿を表示'''
 +
<pre>
 +
<pre>
 +
// Create a new filtering function that will add our where clause to the query
 +
function filter_where( $where = '' ) {
 +
// posts  30 to 60 days old
 +
$where .= " AND post_date >= '" . date('Y-m-d', strtotime('-60 days')) . "'" . " AND post_date <= '" . date('Y-m-d', strtotime('-30 days')) . "'";
 +
return $where;
 +
}
 +
add_filter( 'posts_where', 'filter_where' );
 +
 
 +
query_posts( $query_string );
 +
</pre>
 +
 
 +
<div id="Custom_Field_Parameters">
 +
=== カスタムフィールド引数 ===
 +
</div>
 +
カスタムフィールドのキーまたは値を元に投稿を表示。 
 +
 
 +
* '''<tt>meta_key</tt>''' (''string'') - Custom field key.
 +
* '''<tt>meta_value</tt>''' (''string'') - Custom field value.
 +
* '''<tt>meta_compare</tt>''' (''string'') - '<tt>meta_value=</tt>' で指定された値を比較する演算子。デフォルトは '=' で, '!='、'>'、'>='、'<'、'<=' も使える。
 +
 
 +
キーが 'color' で値が 'blue' のカスタムフィールドを持つ投稿を表示。
 +
 
 +
query_posts( 'meta_key=color&meta_value=blue' );
 +
 
 +
値は問わず、キーが 'color' のカスタムフィールドを持つ投稿を表示。
 +
 
 +
query_posts( 'meta_key=color' );
 +
 
 +
キーは問わず、値が 'blue' のカスタムフィールドを持つ投稿を表示。
 +
 
 +
query_posts( 'meta_value=color' );
 +
 
 +
キーは問わず、値が 'green' のカスタムフィールドを持つ[[Pages|固定ページ]]を表示。
 +
 
 +
query_posts( 'post_type=page&meta_value=green' );
 +
 
 +
Returns posts with a custom field value of zero (0), regardless of the custom field key:
 +
 
 +
query_posts( 'meta_value'='_wp_zero_value' );
 +
 
 +
キーが 'color' で値が 'blue' でないカスタムフィールドを持つ投稿と[[Pages|固定ページ]]の両方を表示。
 +
 
 +
query_posts( 'post_type=any&meta_key=color&meta_compare=!=&meta_value=blue' );
 +
 
 +
キーが 'miles' で値が 22 以下のカスタムフィールドを持つ投稿を表示。注:値は数値ではなく文字列として扱われているため「99」は「100」より大きくなります。
 +
query_posts( 'meta_key=miles&meta_compare=<=&meta_value=22' );
 +
 
 +
############ ここまで旧記述。WP_Query と整合させるため削除 ############ -->
 +
 +
 
 +
<div id="Examples">
 +
== コード記述例 ==
 +
</div>
 +
<div id="Exclude_Categories_From_Your_Home_Page">
 +
=== 「最新の投稿」ページから指定カテゴリーを除く ===
 +
</div>
 +
<tt>index.php</tt> ファイルに以下のコードを書くと、カテゴリー ID が 3 ''以外の'' 投稿を表示します。
 +
 
 +
<pre>
 
<?php
 
<?php
  foreach($posts as $post) :
+
  if ( is_home() ) {
 +
      query_posts( 'cat=-3' );
 +
  }
 
?>
 
?>
    <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
+
</pre>
<?php endforeach; ?>
+
 
  </ul></nowiki></pre>
+
複数のカテゴリー ID を指定できる([[Version 3.3.1|バージョン 3.3.1]] で検証済)。
* 出力例:
+
<pre>
<pre><nowiki><h2>最新アウトドア関連情報</h2>
+
<?php
 +
  if ( is_home() ) {
 +
      query_posts( 'cat=-1,-2,-3' );
 +
  }
 +
?>
 +
</pre>
 +
 
 +
<div id="Retrieve_a_Particular_Post">
 +
=== 特定の投稿を表示 ===
 +
</div>
 +
特定の投稿を表示するには次にコードが使えます。
 +
 
 +
<pre>
 +
<?php
 +
query_posts( 'p=5' );
 +
?>
 +
</pre>
 +
 
 +
'''参考:'''特定の投稿が「添付」の場合、''p'' の代わりに ''attachment_id'' を用います。
 +
 
 +
<pre>
 +
<?php
 +
query_posts( 'attachment_id=5' );
 +
?>
 +
</pre>
 +
 
 +
''続きを読む'' を表示したい場合は、グローバル変数 <tt>$more</tt> を 0 にします。
 +
 
 +
<pre>
 +
<?php
 +
// 投稿 ID が 5 の投稿を表示する
 +
query_posts( 'p=5' );
 +
 
 +
// 投稿の始めの部分のみ表示するため $more を 0 にする
 +
global $more;
 +
$more = 0;
 +
 
 +
// ループ
 +
while (have_posts()) : the_post();
 +
  the_content( 'Read the full post &raquo;' );
 +
endwhile;
 +
?>
 +
</pre>
 +
 
 +
2008年5月に投稿された、カテゴリー ID 1 と 3 の投稿タイトルを1ページに5件ずつ表示する:
 +
 
 +
<pre><?php if (have_posts()) :  query_posts('posts_per_page=5&cat=1,3&monthnum=5&year=2008'); ?>
 +
  <?php while (have_posts()) : the_post(); ?>
 +
    <?php the_title(); ?>
 +
<?php endwhile; endif; ?>
 +
</pre>
 +
 
 +
カテゴリー ID 2 と 6 のいずれにも含まれないすべての投稿のタイトルをリストとして表示する:
 +
 
 +
<pre><?php if (have_posts()) :  query_posts(array('category__not_in' => array(2,6))); ?>
 
   <ul>
 
   <ul>
    <li><a href="http://example.com/?p=12">山登り</a></li>
+
  <?php while (have_posts()) : the_post(); ?>
    <li><a href="http://example.com/?p=6">滝修行</a></li>
+
    <li><?php the_title(); ?></li>
    <li><a href="http://example.com/?p=3">キャンプへ</a></li>
+
  <?php endwhile; endif; ?>
  </ul></nowiki></pre>
+
  </ul>
 +
</pre>
 +
 
 +
<div id="All Posts in a Category">
 +
=== カテゴリーの全投稿 ===
 +
</div>
 +
管理画面の「設定」>「表示設定」で設定する「1ページに表示する最大投稿数」のパラメーターが適用されます。これを上書きするためには、 <tt>'post_per_page'</tt> パラメーターを設定します。以下が例です:
 +
 
 +
<pre>
 +
query_posts( array ( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );
 +
</pre>
 +
 
 +
これにより、指定されたカテゴリーの'''全て'''の投稿を表示させます。
 +
 
 +
 
 +
しかし、サブカテゴリーまたは子カテゴリーでは「カテゴリー名」が常に使えるとは限りません(別のサブカテゴリーまたは子カテゴリーと重複する場合がある)。そこで「カテゴリースラッグ」を用いる方が良いでしょう。詳しくは <tt>[[関数リファレンス/is_category|is_category()]]</tt> を参照してください。
 +
 
 +
<pre>
 +
if ( is_category( 'category-slug' ) ) :
 +
 
 +
query_posts( array( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );
 +
 
 +
endif;
 +
</pre>
 +
 
 +
<div id="Syndication Feeds">
 +
=== RSS/Atom フィードで表示する最新の投稿数 ===
 +
</div>
 +
管理画面の「設定」>「表示設定」で設定する「RSS/Atom フィードで表示する最新の投稿数」または '<tt>posts_per_rss</tt>' パラメーターは、フィードで使われるクエリーの '<tt>posts_per_page</tt>' パラメーターを上書きします。
 +
 
 +
 
 +
これをさらに上書きするため (例えば全ての適合する投稿を必要とするカスタムしたICSフィード等) には、以下のように <tt>"post_limits"</tt> フィルターを用います:
 +
 
 +
<pre>
 +
if ( isset ( $query->query_vars['feed'] ) and ( $query->query_vars['feed'] == 'ics' ) )
 +
{
 +
add_filter( 'post_limits', '__return_empty' );
 +
}
 +
</pre>
 +
 
 +
 
 +
<div id="Passing_variables_to_query_posts">
 +
=== query_posts に変数を与える ===
 +
</div>
 +
query_posts に変数を与える方法をいくつか紹介します。どれを使用してもかまいませんので、必要に応じて[[The Loop|WordPress ループ]] の前に記述してください:
 +
 
 +
<div id="Example_1">
 +
==== 記述例 1 ====
 +
</div>
 +
この例は、query_posts を実行する前にクエリ文字列を連結します。まず変数に値を代入し、次に変数と文字列を結合して、実行します。ここではカテゴリー ID を変数で与えることにします。
 +
 
 +
<pre>
 +
// 現在のカテゴリー ID を変数に代入
 +
$categoryvariable = $cat; 
 +
 
 +
// クエリを連結
 +
$args = 'cat=' . $categoryvariable . '&orderby=date&order=ASC';
 +
 
 +
// クエリを実行
 +
query_posts( $args );
 +
</pre>
 +
 
 +
<div id="Example_2">
 +
==== 記述例 2 ====
 +
</div>
 +
次の例では、二重引用符を使って PHP に式を評価させます。まず、現在の年・月を表示し、<tt>query_posts</tt> で公開日が現在の年・月に該当する投稿を表示します。投稿の並び順は日付の昇順で、公開日の古い順に表示します。
 +
 +
<pre>
 +
$current_year = date('Y');
 +
$current_month = date('m');
 +
 
 +
query_posts( "cat=22&year=$current_year&monthnum=$current_month&order=ASC" );
 +
</pre>
 +
 
 +
<div id="Example_3">
 +
==== 記述例 3 ====
 +
</div>
 +
この例では、ページネーションを使ってすべての投稿を表示する場合を説明します。デフォルトの <tt>$query_string</tt> を使って <tt>query_posts</tt> ですべての投稿を表示させることができます。<tt>posts_per_page</tt> の値には -1 か各ページに表示したい投稿の数を指定します。後者の場合には [[テンプレートタグ/posts_nav_link|posts_nav_link()]] でページを移動する手段を提供しましょう。
 +
 
 +
<pre>
 +
query_posts( $query_string . '&posts_per_page=-1' );
 +
</pre>
 +
 
 +
<div id="Example_4">
 +
==== 記述例 4 ====
 +
</div>
 +
<tt>$query_string</tt> 変数を使わずに、引数を配列に入れる方法もあります。複雑な条件を与えるときはこの方がすっきりして読みやすいでしょう。例えば、記述例 2 のクエリは以下のようになります:
 +
 
 +
<pre>
 +
$args = array(
 +
'cat'      => 22,
 +
'year'    => $current_year,
 +
'monthnum' => $current_month,
 +
'order'    => 'ASC'
 +
);
 +
query_posts( $args );
 +
</pre>
 +
 
 +
この方法は、変数ごとに1行ずつ記述すると読み易くなります。
 +
 
 +
<div id="Example_5">
 +
==== 記述例 5 ====
 +
</div>
 +
記述例 4で示した配列形式を使って、複数のタクソノミーを問い合わせることもできます。これは単純に、タクソノミーのスラッグに対してコンマ区切りの文字列を渡すだけです(文字列ひとつがタームひとつに相当)。次の例では、植木等''または''高倉健が出演している映画(カスタム投稿タイプ 'movie')の投稿を全て抽出します。
 +
 
 +
<pre>
 +
$args = array(
 +
'post_type'=> 'movie',
 +
'actor'    => 'Hitoshi Ueki, Ken Takakura',
 +
'order'    => 'ASC'
 +
);
 +
query_posts( $args );
 +
</pre>
 +
 
 +
 
 +
<div id="Change Log">
 +
== 変更履歴 ==
 +
</div>
 +
新規導入 : [[Version 1.5|1.5.0]]
 +
 
 +
<div id="Source File">
 +
== ソースファイル ==
 +
</div>
 +
<tt>query_posts()</tt> は {{Trac|wp-includes/query.php}} にあります。
 +
 
 +
<div id="Resources">
 +
== リソース ==
 +
</div>
 +
* WordPress がクエリをどのように生成/処理するかについてもっと突っ込んだ議論については、これらの記事をみてください:[[Query Overview|クエリ概要]] および [[Custom Queries|カスタムクエリ]]
 +
* 'pre_get_posts' を使ってデフォルトのクエリを適切にカスタマイズする - [http://www.billerickson.net/customize-the-wordpress-query/#example-category Bill Erickson - Customize the Wordpress Query] or [http://developer.wordpress.com/2012/05/14/querying-posts-without-query_posts/ John James Jacoby - Querying Posts Without query_posts]
 +
* あなたはクエリを知らない - [http://www.slideshare.net/andrewnacin/you-dont-know-query-wordcamp-netherlands-2012 - Slides from WordCamp Netherlands 2012 by Andrew Nacin]
 +
 
 +
<!-- ######################## 旧内容ここから ########################
 +
* [http://ottopress.com/2010/wordpress-3-1-advanced-taxonomy-queries/ Advanced Taxonomy Queries in WordPress 3.1]
 +
* [http://wordpress.org/extend/plugins/post-types-order/ Change Order for Custom Post Types in WordPress 3.0]
 +
* [http://perishablepress.com/press/2008/01/22/6-ways-to-customize-wordpress-post-order/ Perishable Press - 6 Ways to Customize WordPress Post Order]
 +
* [http://www.nietoperzka.com/wptraining/custom-order-of-posts-on-main-page/ nietoperzka's Custom order of posts on the main page]
 +
* [http://www.darrenhoyt.com/2008/06/11/displaying-related-category-and-author-content-in-wordpress/ Displaying related category and author content]
 +
* [http://maymay.net/blog/2008/06/06/arbitrarily-exclude-posts-from-displaying-in-wordpress/ Exclude posts from displaying]
 +
* [http://boren.nu/archives/2007/10/01/taxonomy-intersections-and-unions/ Taxonomy Intersections and Unions for WordPress 2.3]
 +
* [http://www.ifelse.co.uk/archives/2005/04/10/make-wp-show-only-one-post-on-the-front-page/ If..Else - Make WordPress Show Only one Post on the Front Page]
 +
* [http://www.ifelse.co.uk/archives/2005/03/31/query_posts/ If..Else - Query Posts in WordPress 1.5]
 +
######################## 旧内容ここまで ######################## -->
 +
 
 +
<div id="Related">
 +
== 関連項目 ==
 +
</div>
 +
 
 +
{{Query Tags}}
 +
{{Query String Tag Footer}}
 +
{{PHP Function Tag Footer}}
 +
<!--
 +
{{Tag Footer}}
 +
-->
 +
 
 +
{{原文|Function Reference/query_posts|142256}} <!-- 21:59, 31 March 2014 Jcull76 版 -->
 +
 
 +
{{DEFAULTSORT:Query_posts}}
 +
[[Category:テンプレートタグ]]
 +
[[Category:wp2.8]]
 +
[[Category:wp2.9]]
  
[[en:Template Tags/get_posts]]
+
[[en:Function Reference/query posts]]
 +
[[it:Riferimento funzioni/query posts]]
 +
[[zh-hans:函数参考/query posts]]
 +
[[pt-br:Referência de Função/query posts]]

2015年11月16日 (月) 00:04時点における最新版

注 1: この関数はプラグインまたはテーマの中で使われることを想定されていません。後ほど出てくる説明にあるように、メインクエリーを変更するにはパフォーマンス面でも優れたより良いオプションが存在します。

注 2: query_posts() はページ内のメインクエリーを書き換え、新しいクエリーのインスタンスと置き換えるために使う関数としては過度に単純化され、問題が発生しやすい方法です。非効率的で(SQL クエリを再実行します)、一部の状況では適切に実行することもできません(特にページング処理)。モダンな WordPress コードではもっと安定したメソッドを使うべきです。例えばpre_get_posts フックを使った方法などです。ひとことで言うと、query_posts() は決して使うべきではありません。

以上のことをしっかり理解し、この関数を賢く活用してください。

WP_Query, query_posts and get_posts use cases explained

画像のソース: WP.SE/Andrey "Rarst" Savchenko

query_posts() はWordPressが投稿を表示するのに使用しているメインクエリーを置き換える手段です。これはメインクエリーを一旦横に置いておき、新しいクエリーで上書きします。query_posts を呼び出したあとは、クエリーの改変を戻すために、wp_reset_query() を呼び出し、オリジナルのメインクエリーを復活させる必要があります。

query_posts を使うことによって、ページ上のメインクエリーが置き換えられ、ページの読み込み速度に影響を与えることに留意してください。最悪の場合、倍かそれ以上の処理が発生します。簡単に使える代わりに、この関数は混乱と問題を引き起こす傾向があります。下記の注意をご覧ください。

一般的な投稿の取得には、WP_Query または get_posts を使ってください。

query_posts の代わりに次のようにすることを強く推奨します:

  1. アクション pre_get_posts を用いる。
  2. pre_get_posts にフックした関数の中で is_main_query() を使ってメインクエリーであるかチェックする。
  3. メインクエリーの場合のみ、それを変更する。

たとえば、ホームで、ふつうは最新の10件の投稿が表示されるでしょう。もし5件だけ表示したいのであれば query_posts() を使ってこのように書くことができます(ページ送りについては無視しています):

query_posts( 'posts_per_page=5' );

同じことを pre_get_posts を使って行うなら functions.php に次のように書きます:

function five_posts_on_homepage( $query ) {
    if ( $query->is_home() && $query->is_main_query() ) {
        $query->set( 'posts_per_page', '5' );
    }
}
add_action( 'pre_get_posts', 'five_posts_on_homepage' );

注意: pre_get_posts アクションは固定ページのリクエストでは動作しません。

注意

query_posts() はデータベースに問い合わせて投稿の一覧を生成するための、数ある方法のひとつに過ぎません。query_posts() を使うと決める前に、欠点も理解しておいてください。

メインループを変更する

query_posts() はメインループを変更するためのものです。query_posts() はそのために、メインループを生成するクエリーを置き換えます。いったん query_posts() を使うと、投稿にもとづいたグローバル変数やテンプレートタグも変更されます。query_posts() を呼び出したあとは、条件分岐タグも置き換えられてしまいます。このことが意図しない結果を引き起こすかもしれません。

派生的なループ

派生的な一覧 (例えばページの下部に関連記事を表示したり、サイドバーのウィジェットでリンクの一覧を出したり等) を表示したい場合は、WP_Query の新しいインスタンスを生成するか、get_posts() を使ってください。

もし query_posts() を使う場合は、用が済んだら必ず wp_reset_query() を呼び出してください。

'paged' クエリー引数を適切に指定していないと、ページ送りが正しく動作しない可能性があります。「クエリに "paged" パラメーターを追加」を参照してください。

SQLクエリーが追加発行される

もし query_posts をテンプレートで使用する場合、そのテンプレートを読み込むまでに WordPress はすでにデータベースへの問い合わせを実行し、データの取り出しを終えています(どのテンプレートを読み込むかが決まったということは、すでに処理が終わっているということですから!)。そのため、query_posts() を使ってデフォルトのクエリーを上書きして結果を得るには、どうしても再度データベースに問い合わせし再計算する必要があります。

このことは、小規模なブログベースのウェブサイトを扱っているのであれば、必ずしも問題であるとは言えません。しかしデータベースが大きい大規模でトラフィックの多いウェブサイトの開発者であれば、デフォルトのクエリーが呼び出される前に直接変更するなどの代替案を検討するほうがいいかもしれません。request フィルターでまさにこれを実現できるでしょう。

データベースへ問い合わせる SQL を生成するのに使われる内部的な $query オブジェクトを改変するには、'parse_query' と 'pre_get_posts' フィルターも利用できます。


使い方

<?php
// クエリ(メインクエリを改変)
query_posts( $args );

// ループ(改変したメインクエリ)
if ( have_posts() ) : 
    while ( have_posts() ) : the_post();
        echo '<li>';
        the_title();
        echo '</li>';
    endwhile; 
else:
    // 何も取得されなかった
endif;

// クエリをリセット
wp_reset_query();
?>

テンプレートファイルのひとつに対して、ループが始まる前の部分に query_posts() の呼び出しを記述します。WP_Query オブジェクトがそのパラメータを使って新しい SQL クエリを生成します。このようにすると、WordPress は URL 経由で受け取った他のパラメータを無視します(ページ番号やカテゴリーなど)。

オリジナルクエリの保持(ページングなど)

デフォルトでは query_posts を実行すると、引数で指定した変数を除きページング,カテゴリー,日付などの現在のページのクエリ変数はすべて上書きされます。この時、オリジナルのクエリを保持したい場合は、query_poats() の引数にグローバル変数である $query_stringを用いることができます。

例えば、残りの投稿文字列に影響をおよぼすこと無く投稿の表示順を保持する時、ループの前に下記を記述することができます。

global $query_string;
query_posts( $query_string . '&order=ASC' );

query_posts() をこのように用いる時、''で囲まれたパラメーターはアンド記号 & で始まる必要があります。


あるいは、元のクエリ配列を引数配列に統合することもできます。

global $wp_query;
$args = array_merge( $wp_query->query, array( 'post_type' => 'product' ) );
query_posts( $args );


引数の組み合わせ

引数はアンド記号 (&) を使って複数組み合わせて指定することができます:

query_posts( 'cat=3&year=2004' );

「最新の投稿」ページで、カテゴリー ID が 13 かつ今月の投稿を表示する場合:

if (is_home()) {
       query_posts( $query_string . '&cat=13&monthnum=' . date( 'n', current_time( 'timestamp' ) ) );
}

バージョン 2.3 で、カテゴリー ID 1 と 3 に含まれる投稿を2件、タイトルの降順で表示する場合:

query_posts( array( 'category__and' => array(1,3), 'posts_per_page' => 2, 'orderby' => 'title', 'order' => 'DESC' ) );

カテゴリー ID が 1 で "apples" のタグ付けがされた投稿を表示する場合:

query_posts( 'cat=1&tag=apples' );

複数のタグを同時に指定する場合は「+」を用います。下記はカテゴリー ID が 1 で、"apples"と"oranges"のタグがついた投稿を表示します:

query_posts( 'cat=1&tag=apples+oranges' );


パラメータ

参考:パラメータの詳細は WP_Query クラスのパラメータの説明をご覧ください。

以下の用例は WP_Query オブジェクトに対しても利用できます。


コード記述例

「最新の投稿」ページから指定カテゴリーを除く

index.php ファイルに以下のコードを書くと、カテゴリー ID が 3 以外の 投稿を表示します。

<?php
   if ( is_home() ) {
      query_posts( 'cat=-3' );
   }
?>

複数のカテゴリー ID を指定できる(バージョン 3.3.1 で検証済)。

<?php
   if ( is_home() ) {
      query_posts( 'cat=-1,-2,-3' );
   }
?>

特定の投稿を表示

特定の投稿を表示するには次にコードが使えます。

<?php
query_posts( 'p=5' );  
?>

参考:特定の投稿が「添付」の場合、p の代わりに attachment_id を用います。

<?php
query_posts( 'attachment_id=5' );  
?>

続きを読む を表示したい場合は、グローバル変数 $more を 0 にします。

<?php
// 投稿 ID が 5 の投稿を表示する
query_posts( 'p=5' );

// 投稿の始めの部分のみ表示するため $more を 0 にする
global $more;
$more = 0;

// ループ
while (have_posts()) : the_post();
  the_content( 'Read the full post »' );
endwhile;
?>

2008年5月に投稿された、カテゴリー ID 1 と 3 の投稿タイトルを1ページに5件ずつ表示する:

<?php if (have_posts()) :  query_posts('posts_per_page=5&cat=1,3&monthnum=5&year=2008'); ?>
  <?php while (have_posts()) : the_post(); ?>
    <?php the_title(); ?>
<?php endwhile; endif; ?>

カテゴリー ID 2 と 6 のいずれにも含まれないすべての投稿のタイトルをリストとして表示する:

<?php if (have_posts()) :  query_posts(array('category__not_in' => array(2,6))); ?>
  <ul>
   <?php while (have_posts()) : the_post(); ?>
     <li><?php the_title(); ?></li>
   <?php endwhile; endif; ?>
  </ul>

カテゴリーの全投稿

管理画面の「設定」>「表示設定」で設定する「1ページに表示する最大投稿数」のパラメーターが適用されます。これを上書きするためには、 'post_per_page' パラメーターを設定します。以下が例です:

query_posts( array ( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );

これにより、指定されたカテゴリーの全ての投稿を表示させます。


しかし、サブカテゴリーまたは子カテゴリーでは「カテゴリー名」が常に使えるとは限りません(別のサブカテゴリーまたは子カテゴリーと重複する場合がある)。そこで「カテゴリースラッグ」を用いる方が良いでしょう。詳しくは is_category() を参照してください。

if ( is_category( 'category-slug' ) ) :

	query_posts( array( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );

endif; 

RSS/Atom フィードで表示する最新の投稿数

管理画面の「設定」>「表示設定」で設定する「RSS/Atom フィードで表示する最新の投稿数」または 'posts_per_rss' パラメーターは、フィードで使われるクエリーの 'posts_per_page' パラメーターを上書きします。


これをさらに上書きするため (例えば全ての適合する投稿を必要とするカスタムしたICSフィード等) には、以下のように "post_limits" フィルターを用います:

if ( isset ( $query->query_vars['feed'] ) and ( $query->query_vars['feed'] == 'ics' ) )
{
	add_filter( 'post_limits', '__return_empty' );
}


query_posts に変数を与える

query_posts に変数を与える方法をいくつか紹介します。どれを使用してもかまいませんので、必要に応じてWordPress ループ の前に記述してください:

記述例 1

この例は、query_posts を実行する前にクエリ文字列を連結します。まず変数に値を代入し、次に変数と文字列を結合して、実行します。ここではカテゴリー ID を変数で与えることにします。

// 現在のカテゴリー ID を変数に代入
$categoryvariable = $cat;  

// クエリを連結
$args = 'cat=' . $categoryvariable . '&orderby=date&order=ASC'; 

// クエリを実行
query_posts( $args ); 

記述例 2

次の例では、二重引用符を使って PHP に式を評価させます。まず、現在の年・月を表示し、query_posts で公開日が現在の年・月に該当する投稿を表示します。投稿の並び順は日付の昇順で、公開日の古い順に表示します。

$current_year = date('Y');
$current_month = date('m');

query_posts( "cat=22&year=$current_year&monthnum=$current_month&order=ASC" );

記述例 3

この例では、ページネーションを使ってすべての投稿を表示する場合を説明します。デフォルトの $query_string を使って query_posts ですべての投稿を表示させることができます。posts_per_page の値には -1 か各ページに表示したい投稿の数を指定します。後者の場合には posts_nav_link() でページを移動する手段を提供しましょう。

query_posts( $query_string . '&posts_per_page=-1' );

記述例 4

$query_string 変数を使わずに、引数を配列に入れる方法もあります。複雑な条件を与えるときはこの方がすっきりして読みやすいでしょう。例えば、記述例 2 のクエリは以下のようになります:

$args = array(
	'cat'      => 22,
	'year'     => $current_year,
	'monthnum' => $current_month,
	'order'    => 'ASC'
);
query_posts( $args );

この方法は、変数ごとに1行ずつ記述すると読み易くなります。

記述例 5

記述例 4で示した配列形式を使って、複数のタクソノミーを問い合わせることもできます。これは単純に、タクソノミーのスラッグに対してコンマ区切りの文字列を渡すだけです(文字列ひとつがタームひとつに相当)。次の例では、植木等または高倉健が出演している映画(カスタム投稿タイプ 'movie')の投稿を全て抽出します。

$args = array(
	'post_type'=> 'movie',
	'actor'    => 'Hitoshi Ueki, Ken Takakura',
	'order'    => 'ASC'
);
query_posts( $args );


変更履歴

新規導入 : 1.5.0

ソースファイル

query_posts()wp-includes/query.php にあります。

リソース


記事

コード・ドキュメンテーション

  • クラス: WP_Query - WP_Query クラスの詳細な全容
  • クラス: WP_Comment_Query - コメント関連のクエリのためのクラス
  • クラス: WP_User_Query - ユーザー関連のクエリのためのクラス
  • オブジェクト: $wpdb - $wpdb オブジェクトの使い方全容
  • 関数: set_query_var()
  • 関数: get_query_var()
  • 関数: query_posts() - 追加のカスタムクエリを作成
  • 関数: get_post() - 項目の ID を取得しデータベース内にあるその投稿のレコードを返す
  • 関数: get_posts() - 投稿の配列を返すことに特化した関数
  • 関数: get_pages() - ページの配列を返すことに特化した関数
  • 関数: have posts() - クエリが投稿を返すか否かを判断する条件関数
  • 関数: the_post() - クエリ後に自動的にループを設定する
  • 関数: rewind_posts() - 現状のループをリセットする
  • 関数: setup_postdata() - ループ内で個別の結果を得るためのクエリデータを設定する
  • 関数: wp_reset_postdata() - 直前のクエリを復元する (通常はループ内の別のループの後に用いられる)
  • 関数: wp_reset_query()
  • 関数: is_main_query() - 変更されるクエリがメインのクエリであることを確認する
  • アクションフック: pre_get_posts - WordPressクエリが実行される前に変更する
  • アクションフック: the_post - post クエリの後で post オブジェクトを変更する
  • フィルターフック: found_posts - WP_Query オブジェクトの found_posts 値を変更する


テンプレートタグへのクエリ文字列型パラメータの渡し方関数リファレンステンプレートタグ目次もご覧ください。


テンプレートタグへの PHP 関数型パラメータの渡し方関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/query_posts最新版との差分