• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(先頭固定投稿引数: 最新翻訳へ揃えるため WP_Query の同セクションへ誘導。)
(パラメータ: WP_Query との整合性を保つため、関数リファレンス/WP_Query を参照するように誘導。)
 
13行目: 13行目:
 
<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>
 
<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>
  
<tt>query_posts()</tt>はWordPressが投稿を表示するのに使用しているメインクエリーを置き換える手段です。これはメインクエリーを一旦横に置いておき、新しいクエリーで上書きします。<tt>query_posts</tt>を呼び出したあとは、クエリーの改変を戻すために、<tt>wp_reset_query()</tt>を呼び出し、オリジナルのメインクエリーを復活させる必要があります。
+
<tt>query_posts()</tt> はWordPressが投稿を表示するのに使用しているメインクエリーを置き換える手段です。これはメインクエリーを一旦横に置いておき、新しいクエリーで上書きします。<tt>query_posts</tt> を呼び出したあとは、クエリーの改変を戻すために、<tt>wp_reset_query()</tt> を呼び出し、オリジナルのメインクエリーを復活させる必要があります。
  
<tt>query_posts</tt>を使うことによって、ページ上のメインクエリーが置き換えられ、ページの読み込み速度に影響を与えることに留意してください。最悪の場合、倍かそれ以上の処理が発生します。簡単に使える代わりに、この関数は混乱と問題を引き起こす傾向があります。下記の注意をご覧ください。
+
<tt>query_posts</tt> を使うことによって、ページ上のメインクエリーが置き換えられ、ページの読み込み速度に影響を与えることに留意してください。最悪の場合、倍かそれ以上の処理が発生します。簡単に使える代わりに、この関数は混乱と問題を引き起こす傾向があります。下記の注意をご覧ください。
  
一般的な投稿の取得には、[[関数リファレンス/WP_Query|WP_Query]]か、[[テンプレートタグ/get_posts|get_posts]]を使ってください。
+
一般的な投稿の取得には、[[関数リファレンス/WP_Query|WP_Query]] または [[テンプレートタグ/get_posts|get_posts]] を使ってください。
  
<tt>query_posts</tt> ではなく [[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]] フィルターを用い、[[関数リファレンス/is_main_query|is_main_query]] でチェックしてメインクエリーを変更することが'''強く'''推奨されています。
+
<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>を使ってこのように書くことができます(ページ送りについては無視しています)。
+
たとえば、ホームで、ふつうは最新の10件の投稿が表示されるでしょう。もし5件だけ表示したいのであれば <tt>query_posts()</tt> を使ってこのように書くことができます(ページ送りについては無視しています):
  
 
<pre>query_posts( 'posts_per_page=5' );</pre>
 
<pre>query_posts( 'posts_per_page=5' );</pre>
  
functions.phpで[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]]を使って同じことをするなら、このように書けます。
+
同じことを [[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]] を使って行うなら functions.php に次のように書きます:
  
 
<pre>
 
<pre>
36行目: 39行目:
 
</pre>
 
</pre>
  
'''注意:'''pre_get_postsアクションは[[Pages|固定ページ]]のリクエストでは動作しません。
+
'''注意:''' pre_get_posts アクションは[[Pages|固定ページ]]のリクエストでは動作しません。
  
 
<div id="Caveats">
 
<div id="Caveats">
 
== 注意 ==
 
== 注意 ==
 
</div>
 
</div>
<tt>query_posts()</tt>はデータベースに問い合わせて投稿の一覧を生成するための、数ある方法のひとつに過ぎません。<tt>query_posts()</tt>を使うと決める前に、欠点も理解しておいてください。
+
<tt>query_posts()</tt> はデータベースに問い合わせて投稿の一覧を生成するための、数ある方法のひとつに過ぎません。<tt>query_posts()</tt> を使うと決める前に、欠点も理解しておいてください。
  
 
<div id="Alters Main Loop">
 
<div id="Alters Main Loop">
 
=== メインループを変更する ===
 
=== メインループを変更する ===
 
</div>
 
</div>
<tt>query_posts()</tt>はメインループを変更するためのものです。<tt>query_posts()</tt>はそのために、メインループを生成するクエリーを置き換えます。いったん<tt>query_posts()</tt>を使うと、投稿にもとづいたグローバル変数やテンプレートタグも変更されます。<tt>query_posts()</tt>を呼び出したあとは、条件分岐タグも置き換えられてしまいます。このことが意図しない結果を引き起こすかもしれません。
+
<tt>query_posts()</tt> はメインループを変更するためのものです。<tt>query_posts()</tt> はそのために、メインループを生成するクエリーを置き換えます。いったん <tt>query_posts()</tt> を使うと、投稿にもとづいたグローバル変数やテンプレートタグも変更されます。<tt>query_posts()</tt> を呼び出したあとは、条件分岐タグも置き換えられてしまいます。このことが意図しない結果を引き起こすかもしれません。
  
 
<div id="Secondary Loops">
 
<div id="Secondary Loops">
 
=== 派生的なループ ===
 
=== 派生的なループ ===
 
</div>
 
</div>
派生的な一覧 (例えばページの下部に関連記事を表示したり、サイドバーのウィジェットでリンクの一覧を出したり等) を表示したい場合は、[[関数リファレンス/WP_Query|WP_Query]]の新しいインスタンスを生成するか、[[テンプレートタグ/get_posts|get_posts()]]を使ってください。
+
派生的な一覧 (例えばページの下部に関連記事を表示したり、サイドバーのウィジェットでリンクの一覧を出したり等) を表示したい場合は、[[関数リファレンス/WP_Query|WP_Query]] の新しいインスタンスを生成するか、[[テンプレートタグ/get_posts|get_posts()]] を使ってください。
  
もし<tt>query_posts()</tt>を使う場合は、用が済んだら必ず<tt>wp_reset_query()</tt>を呼び出してください。
+
もし <tt>query_posts()</tt> を使う場合は、用が済んだら必ず <tt>wp_reset_query()</tt> を呼び出してください。
  
 
<div id="Pagination">
 
<div id="Pagination">
 
=== ページ送り ===
 
=== ページ送り ===
 
</div>
 
</div>
'paged' クエリー引数を適切に指定していないと、ページ送りが正しく動作しない可能性があります:[http://codex.wordpress.org/Pagination#Adding_the_.22paged.22_parameter_to_a_query 英語版Codex "adding the paged parameter"を参照してください。]
+
'paged' クエリー引数を適切に指定していないと、ページ送りが正しく動作しない可能性があります。「[[Pagination#Adding_the_.22paged.22_parameter_to_a_query|クエリに "paged" パラメーターを追加]]」を参照してください。
  
 
<div id="Additional SQL Queries">
 
<div id="Additional SQL Queries">
 
=== SQLクエリーが追加発行される ===
 
=== SQLクエリーが追加発行される ===
 
</div>
 
</div>
<tt>query_posts</tt>をテンプレートで使用する場合、WordPressはすでにデータベースへの問い合わせを実行し、テンプレートを読み込む頃にはデータの取り出しを終えています (なぜなら、どのテンプレートが読み込まれるかが決まったということは、すでに処理が終わっているということですから!)。そのため、<tt>query_posts()</tt>を使ってデフォルトのクエリーを上書きして結果を得るには、どうしても再度データベースに問い合わせし再計算する必要があります。
+
もし <tt>query_posts</tt> をテンプレートで使用する場合、そのテンプレートを読み込むまでに WordPress はすでにデータベースへの問い合わせを実行し、データの取り出しを終えています(どのテンプレートを読み込むかが決まったということは、すでに処理が終わっているということですから!)。そのため、<tt>query_posts()</tt> を使ってデフォルトのクエリーを上書きして結果を得るには、どうしても再度データベースに問い合わせし再計算する必要があります。
  
このことは、小規模なブログベースのウェブサイトを扱っているのであれば、必ずしも問題であるとは言えません。データベースが大きい大規模でトラフィックの多いウェブサイトの開発者であれば、デフォルトのクエリーが呼び出される前に直接変更するなどの代替案を検討するほうがいいかもしれません。[[プラグイン_API/アクションフック一覧/request|request]]フィルターでまさにこれを実現できるでしょう。
+
このことは、小規模なブログベースのウェブサイトを扱っているのであれば、必ずしも問題であるとは言えません。しかしデータベースが大きい大規模でトラフィックの多いウェブサイトの開発者であれば、デフォルトのクエリーが呼び出される前に直接変更するなどの代替案を検討するほうがいいかもしれません。[[プラグイン_API/アクションフック一覧/request|request]] フィルターでまさにこれを実現できるでしょう。
  
'parse_query' と '[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]]' フィルターも内部的に <tt>$query</tt> オブジェクトを改変しデータベースへ問い合わせるSQLを生成するのに使われます。
+
データベースへ問い合わせる SQL を生成するのに使われる内部的な <tt>$query</tt> オブジェクトを改変するには、'parse_query' と '[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]]' フィルターも利用できます。
  
<!-- ########################## 旧記述ここから ##########################
 
<tt>query_posts</tt> は [[The Loop|WordPress ループ]] で表示される投稿を変更するために使います。この関数は URL で使われるのと同じ書式の各種引数(例:<tt>p=4</tt> なら 投稿 ID が 4 の投稿のみを表示)を受け取ります。
 
 
URL から得られたクエリを変更することはトラブルの元になります。[[Conditional Tags|条件分岐タグ]] のようなページの判定を組み合わせることで、URL を一切変えることなく投稿 の見せ方をカスタマイズすることができます。
 
 
よくある利用例:
 
*  フロントページに任意の投稿を表示する(管理画面の [[管理パネル#Settings|設定]] > [[管理パネル/表示設定|表示設定]] で固定ページを指定することもできます)。
 
*  指定した期間の投稿すべてを表示する。
 
*  フロントページに最新の投稿(だけ)を表示する。
 
*  投稿の表示順序を変更する。
 
*  特定のカテゴリーに含まれる投稿だけを表示する。
 
*  1つまたは複数のカテゴリーに含まれる投稿を除く。
 
 
<div id="Important_notes">
 
== 重要事項 ==
 
</div>
 
query_posts() 関数はメインの WordPress ループ''だけ''を変更するためのものです。新たなループを作るためのものではありません。メインループの他にループが必要な場合は、[[テンプレートタグ/get_posts|get_posts()]] を使ってください。メインループの他で query_posts() を使用すると、メインループが不正な状態になり期待する結果が得られません。
 
 
query_posts() 関数はページのメインクエリを上書きし、置き換えます。他の目的で使用しないでください。
 
 
query_posts() 関数は新しい [[関数リファレンス/WP_Query|WP_Query]] オブジェクトを作成し、グローバル ''wp_query'' 変数に割り当てます。[[テンプレートタグ/get_posts|get_posts()]] 関数は、グローバルエリアをまったく上書きすることなく新しい [[関数リファレンス/WP_Query|WP_Query]] オブジェクトを作成します。
 
 
########################## 旧記述ここまで ########################## -->
 
  
 
<div id="Usage">
 
<div id="Usage">
98行目: 78行目:
 
<pre>
 
<pre>
 
<?php
 
<?php
 
+
// クエリ(メインクエリを改変)
// クエリ
+
 
query_posts( $args );
 
query_posts( $args );
  
// ループ
+
// ループ(改変したメインクエリ)
 
if ( have_posts() ) :  
 
if ( have_posts() ) :  
  while ( have_posts() ) : the_post();
+
    while ( have_posts() ) : the_post();
      echo '<li>';
+
        echo '<li>';
  the_title();
+
        the_title();
  echo '</li>';
+
        echo '</li>';
  endwhile;  
+
    endwhile;  
 
else:
 
else:
 +
    // 何も取得されなかった
 
endif;
 
endif;
  
116行目: 96行目:
 
?>
 
?>
 
</pre>
 
</pre>
 +
 +
[[テンプレート]]ファイルのひとつに対して、[[ループ]]が始まる前の部分に <tt>query_posts()</tt> の呼び出しを記述します。<tt>WP_Query</tt> オブジェクトがそのパラメータを使って新しい SQL クエリを生成します。このようにすると、WordPress は URL 経由で受け取った他のパラメータを無視します(ページ番号やカテゴリーなど)。
  
 
<div id="Preserving_the_Original_Query_Parameters">
 
<div id="Preserving_the_Original_Query_Parameters">
167行目: 149行目:
  
  
 
+
<div id="Parameters">
<!-- ########################## 古い記載。重複につきコメントアウト
+
== パラメータ ==
<div id="Usage_Note">
+
=== 注意事項 ===
+
 
</div>
 
</div>
<tt>query_posts()</tt> は [[テンプレート|テンプレート]] ファイル内で [[The Loop|WordPress ループ]] が始まる前に記述します。<tt>wp_query</tt> オブジェクトは与えられた引数から新しい SQL クエリを作ります。このとき、WordPress は(ページ番号やカテゴリーのような)URL から得られた引数を無視します。もしその情報が必要なら、<tt>query_posts()</tt> の引数としてグローバル変数の <tt>$query_string</tt> を与えます。
 
  
例えば、他のクエリ引数に影響を与えずに投稿の表示順序だけを指定したいなら [[The Loop|WordPress ループ]] の前に以下のように記述します:
+
<p class="information">'''参考:'''パラメータの詳細は [[クラスリファレンス/WP_Query#Parameters|WP_Query クラスのパラメータの説明]]をご覧ください。</p>
  
<pre>
+
以下の用例は WP_Query オブジェクトに対しても利用できます。
global $query_string;
+
query_posts( $query_string . "&order=ASC" );
+
</pre>
+
  
この形式で <tt>query_posts()</tt> を使う場合は、二重引用符で囲んだ引数をアンド記号(&)で始めてください。または複数の値の引数を追加する場合、配列にする必要があります。
+
<!-- ############ ここから旧記述。WP_Query と整合させるため削除 ############
 
+
<pre>
+
global $query_string;
+
parse_str( $query_string, $args );
+
$args[post_type] = array( 'post', 'video' );
+
query_posts( $args );
+
</pre>
+
 
+
さらに、元のクエリ配列を引数配列に統合することもできます。
+
 
+
<pre>
+
global $wp_query;
+
$args = array_merge( $wp_query->query, array( 'post_type' => 'product' ) );
+
query_posts( $args );
+
</pre>
+
 
+
 
+
<div id="Usage_Tips">
+
=== 使い方のヒント ===
+
</div>
+
管理画面の 設定 > 表示設定 にある "1ページに表示する最大投稿数" パラメータで通常の表示件数を指定できます。これを変更するには 'posts_per_page' 引数を使います:
+
<pre>
+
query_posts( 'category_name=The Category Name&posts_per_page=-1' );  // 指定カテゴリーに含まれるすべての投稿を表示
+
</pre>
+
 
+
The "Syndication feeds show the most recent" or "posts per rss" parameters in Settings > Reading will overwrite any posts_per_page parameter in a query used in a feed. To overcome use (for example in a a custom ics feed, where all matching posts are required), use the "posts_limit" filter as follows:
+
 
+
<pre>
+
if ( isset ( $query->query_vars['feed'] ) and ( $query->query_vars['feed'] == 'ics' ) )
+
add_filter( 'post_limits', 'no_limits_for_feed' );
+
 
+
function no_limits_for_feed( $limits ) {
+
return '';
+
}
+
</pre>
+
 
+
 
+
########################## 古い記載。重複につきコメントアウト -->
+
 
+
<div id="Parameters">
+
== パラメーター ==
+
</div>
+
 
ここでの記述例は <tt>[[関数リファレンス/WP_Query|WP_Query]]</tt> オブジェクトでも使えるものですが、もちろんこれが全てではありません。パラメーターを組み合わせることで、より実用的なクエリが可能になります。パラメーターの詳細は[[関数リファレンス/WP_Query#Parameters|こちら]]を参照してください。
 
ここでの記述例は <tt>[[関数リファレンス/WP_Query|WP_Query]]</tt> オブジェクトでも使えるものですが、もちろんこれが全てではありません。パラメーターを組み合わせることで、より実用的なクエリが可能になります。パラメーターの詳細は[[関数リファレンス/WP_Query#Parameters|こちら]]を参照してください。
  
679行目: 613行目:
 
キーが 'miles' で値が 22 以下のカスタムフィールドを持つ投稿を表示。注:値は数値ではなく文字列として扱われているため「99」は「100」より大きくなります。
 
キーが 'miles' で値が 22 以下のカスタムフィールドを持つ投稿を表示。注:値は数値ではなく文字列として扱われているため「99」は「100」より大きくなります。
 
  query_posts( 'meta_key=miles&meta_compare=<=&meta_value=22' );
 
  query_posts( 'meta_key=miles&meta_compare=<=&meta_value=22' );
 +
 +
############ ここまで旧記述。WP_Query と整合させるため削除 ############ -->
 
   
 
   
  
 
<div id="Examples">
 
<div id="Examples">
 
 
== コード記述例 ==
 
== コード記述例 ==
 
</div>
 
</div>
710行目: 645行目:
 
=== 特定の投稿を表示 ===
 
=== 特定の投稿を表示 ===
 
</div>
 
</div>
特定の投稿を表示。
+
特定の投稿を表示するには次にコードが使えます。
  
 
<pre>
 
<pre>
718行目: 653行目:
 
</pre>
 
</pre>
  
'''注:'''特定の投稿が「添付」の場合、''p''の代わりに''attachment_id''を用います。
+
'''参考:'''特定の投稿が「添付」の場合、''p'' の代わりに ''attachment_id'' を用います。
  
 
<pre>
 
<pre>
765行目: 700行目:
 
=== カテゴリーの全投稿 ===
 
=== カテゴリーの全投稿 ===
 
</div>
 
</div>
管理画面の「設定」→「表示設定」で設定する「1ページに表示する最大投稿数」のパラメーターが適用されます。これを上書きするためには、 <tt>'post_per_page'</tt> パラメーターを設定します。以下が例です:
+
管理画面の「設定」>「表示設定」で設定する「1ページに表示する最大投稿数」のパラメーターが適用されます。これを上書きするためには、 <tt>'post_per_page'</tt> パラメーターを設定します。以下が例です:
  
 
<pre>
 
<pre>
774行目: 709行目:
  
  
しかし、サブカテゴリーまたは子カテゴリーでは「カテゴリー名」が常に使えるとは限らないため、「カテゴリースラッグ」を用いる方が良いとされます。詳しくは、 <tt>[[Function_Reference/is_category|is_category()]]</tt> を参照してください。
+
しかし、サブカテゴリーまたは子カテゴリーでは「カテゴリー名」が常に使えるとは限りません(別のサブカテゴリーまたは子カテゴリーと重複する場合がある)。そこで「カテゴリースラッグ」を用いる方が良いでしょう。詳しくは <tt>[[関数リファレンス/is_category|is_category()]]</tt> を参照してください。
  
 
<pre>
 
<pre>
 
if ( is_category( 'category-slug' ) ) :
 
if ( is_category( 'category-slug' ) ) :
  
query_posts( array( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );
+
query_posts( array( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );
  
 
endif;  
 
endif;  
787行目: 722行目:
 
=== RSS/Atom フィードで表示する最新の投稿数 ===
 
=== RSS/Atom フィードで表示する最新の投稿数 ===
 
</div>
 
</div>
管理画面の「設定」→「表示設定」で設定する「RSS/Atom フィードで表示する最新の投稿数」または '<tt>posts_per_rss</tt>' パラメーターは、フィードで使われるクエリーの '<tt>posts_per_page</tt>' パラメーターを上書きします。
+
管理画面の「設定」>「表示設定」で設定する「RSS/Atom フィードで表示する最新の投稿数」または '<tt>posts_per_rss</tt>' パラメーターは、フィードで使われるクエリーの '<tt>posts_per_page</tt>' パラメーターを上書きします。
  
  
これをさらに上書きするため (例えば全ての適合する投稿を必要とするカスタムしたICSフィード等) には、以下のように <tt>"post_limit"</tt> フィルターを用います:  
+
これをさらに上書きするため (例えば全ての適合する投稿を必要とするカスタムしたICSフィード等) には、以下のように <tt>"post_limits"</tt> フィルターを用います:  
  
 
<pre>
 
<pre>
805行目: 740行目:
 
query_posts に変数を与える方法をいくつか紹介します。どれを使用してもかまいませんので、必要に応じて[[The Loop|WordPress ループ]] の前に記述してください:
 
query_posts に変数を与える方法をいくつか紹介します。どれを使用してもかまいませんので、必要に応じて[[The Loop|WordPress ループ]] の前に記述してください:
  
<div id=" Example_1">
+
<div id="Example_1">
=== 記述例 1 ===
+
==== 記述例 1 ====
 
</div>
 
</div>
 
この例は、query_posts を実行する前にクエリ文字列を連結します。まず変数に値を代入し、次に変数と文字列を結合して、実行します。ここではカテゴリー ID を変数で与えることにします。
 
この例は、query_posts を実行する前にクエリ文字列を連結します。まず変数に値を代入し、次に変数と文字列を結合して、実行します。ここではカテゴリー ID を変数で与えることにします。
  
 
<pre>
 
<pre>
// 現在のカテゴリー ID を変数に代入
+
// 現在のカテゴリー ID を変数に代入
$categoryvariable = $cat;   
+
$categoryvariable = $cat;   
+
 
// クエリを連結
+
// クエリを連結
$args = 'cat=' . $categoryvariable . '&orderby=date&order=ASC';  
+
$args = 'cat=' . $categoryvariable . '&orderby=date&order=ASC';  
+
 
// クエリを実行
+
// クエリを実行
  query_posts( $args );  
+
query_posts( $args );  
 
</pre>
 
</pre>
  
 
<div id="Example_2">
 
<div id="Example_2">
=== 記述例 2 ===
+
==== 記述例 2 ====
 
</div>
 
</div>
 
次の例では、二重引用符を使って PHP に式を評価させます。まず、現在の年・月を表示し、<tt>query_posts</tt> で公開日が現在の年・月に該当する投稿を表示します。投稿の並び順は日付の昇順で、公開日の古い順に表示します。
 
次の例では、二重引用符を使って PHP に式を評価させます。まず、現在の年・月を表示し、<tt>query_posts</tt> で公開日が現在の年・月に該当する投稿を表示します。投稿の並び順は日付の昇順で、公開日の古い順に表示します。
 
   
 
   
 
<pre>
 
<pre>
$current_year = date('Y');
+
$current_year = date('Y');
$current_month = date('m');
+
$current_month = date('m');
+
 
query_posts( "cat=22&year=$current_year&monthnum=$current_month&order=ASC" );
+
query_posts( "cat=22&year=$current_year&monthnum=$current_month&order=ASC" );
 
</pre>
 
</pre>
  
 
<div id="Example_3">
 
<div id="Example_3">
=== 記述例 3 ===
+
==== 記述例 3 ====
 
</div>
 
</div>
 
この例では、ページネーションを使ってすべての投稿を表示する場合を説明します。デフォルトの <tt>$query_string</tt> を使って <tt>query_posts</tt> ですべての投稿を表示させることができます。<tt>posts_per_page</tt> の値には -1 か各ページに表示したい投稿の数を指定します。後者の場合には [[テンプレートタグ/posts_nav_link|posts_nav_link()]] でページを移動する手段を提供しましょう。
 
この例では、ページネーションを使ってすべての投稿を表示する場合を説明します。デフォルトの <tt>$query_string</tt> を使って <tt>query_posts</tt> ですべての投稿を表示させることができます。<tt>posts_per_page</tt> の値には -1 か各ページに表示したい投稿の数を指定します。後者の場合には [[テンプレートタグ/posts_nav_link|posts_nav_link()]] でページを移動する手段を提供しましょう。
  
 
<pre>
 
<pre>
query_posts( $query_string . '&posts_per_page=-1' );
+
query_posts( $query_string . '&posts_per_page=-1' );
 
</pre>
 
</pre>
  
 
<div id="Example_4">
 
<div id="Example_4">
=== 記述例 4 ===
+
==== 記述例 4 ====
 
</div>
 
</div>
<tt>$query_string</tt> 変数を使わずに、引数を配列に入れる方法もあります。例えば、記述例 2 のクエリは以下のようになります:
+
<tt>$query_string</tt> 変数を使わずに、引数を配列に入れる方法もあります。複雑な条件を与えるときはこの方がすっきりして読みやすいでしょう。例えば、記述例 2 のクエリは以下のようになります:
  
 
<pre>
 
<pre>
860行目: 795行目:
  
 
<div id="Example_5">
 
<div id="Example_5">
=== 記述例 5 ===
+
==== 記述例 5 ====
 
</div>
 
</div>
記述例 4で示した配列を複数のタクソノミーに入れることも可能です。これは単純にタクソノミーのスラッグをコンマで分割した文字列として代入するだけです。この例では、植木等''または''高倉健が出演している映画の投稿を全て抽出します。
+
記述例 4で示した配列形式を使って、複数のタクソノミーを問い合わせることもできます。これは単純に、タクソノミーのスラッグに対してコンマ区切りの文字列を渡すだけです(文字列ひとつがタームひとつに相当)。次の例では、植木等''または''高倉健が出演している映画(カスタム投稿タイプ 'movie')の投稿を全て抽出します。
  
 
<pre>
 
<pre>
877行目: 812行目:
 
== 変更履歴 ==
 
== 変更履歴 ==
 
</div>
 
</div>
[[Version 1.5|1.5.0]]から導入されました。
+
新規導入 : [[Version 1.5|1.5.0]]
  
 
<div id="Source File">
 
<div id="Source File">
883行目: 818行目:
 
</div>
 
</div>
 
<tt>query_posts()</tt> は {{Trac|wp-includes/query.php}} にあります。
 
<tt>query_posts()</tt> は {{Trac|wp-includes/query.php}} にあります。
 
  
 
<div id="Resources">
 
<div id="Resources">
 
== リソース ==
 
== リソース ==
 
</div>
 
</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://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://wordpress.org/extend/plugins/post-types-order/ Change Order for Custom Post Types in WordPress 3.0]
897行目: 836行目:
 
* [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/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]
 
* [http://www.ifelse.co.uk/archives/2005/03/31/query_posts/ If..Else - Query Posts in WordPress 1.5]
<!--We need resources from other sources for this article-->
+
######################## 旧内容ここまで ######################## -->
  
{{原文|Template Tags/query posts|136311}}<!-- 21:31, 25 September 2013 Seanchayes 版 -->
+
<div id="Related">
 
+
== 関連項目 ==
== 関連 ==
+
</div>
  
 
{{Query Tags}}
 
{{Query Tags}}
910行目: 849行目:
 
-->
 
-->
  
{{DEFAULTSORT:Query posts}}
+
{{原文|Function Reference/query_posts|142256}} <!-- 21:59, 31 March 2014 Jcull76 版 -->
 +
 
 +
{{DEFAULTSORT:Query_posts}}
 
[[Category:テンプレートタグ]]
 
[[Category:テンプレートタグ]]
 
[[Category:wp2.8]]
 
[[Category:wp2.8]]
 
[[Category:wp2.9]]
 
[[Category:wp2.9]]
  
[[en:Template Tags/query_posts]]
+
[[en:Function Reference/query posts]]
 +
[[it:Riferimento funzioni/query posts]]
 
[[zh-hans:函数参考/query posts]]
 
[[zh-hans:函数参考/query posts]]
 
[[pt-br:Referência de Função/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最新版との差分