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

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(英語版Codexの最新のDescription, Caveatsの項を翻訳)
(パラメータ: WP_Query との整合性を保つため、関数リファレンス/WP_Query を参照するように誘導。)
 
(5人の利用者による、間の16版が非表示)
1行目: 1行目:
{{Old}}
+
<div id="Description">
{{NeedTrans|一部}}
+
== 説明 ==
==説明<span id="Description"></span>==
+
</div>
<tt>query_posts()</tt>はWordPressのメインクエリーを変更し表示される投稿を変更する方法としては、最もかんたんですが、効率的ではなく、好まれない方法です。<tt>query_posts</tt>はメインクエリーをいったん横に置いておき、新しいクエリーで上書きします。<tt>query_posts</tt>を呼び出したあとは、クエリーの改変を戻すために、<tt>wp_reset_query()</tt>を呼び出し、オリジナルのメインクエリーを復活させる必要があります。
+
  
<tt>query_posts</tt>ではなく[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]]フィルターを用い、[[関数リファレンス/is_main_query|is_main_query]]でチェックしてメインクエリーを変更することが'''強く'''推奨されています。
+
'''''注 1:''''' この関数はプラグインまたはテーマの中で使われることを想定されていません。後ほど出てくる説明にあるように、メインクエリーを変更するにはパフォーマンス面でも優れたより良いオプションが存在します。
  
たとえば、ホームで、通常最新の10件の投稿が表示されているとします。もし5件だけ表示したいのであれば、<tt>query_posts()</tt>を使ってこのように書くことができます(ページ送りについては無視しています)。
+
'''''注 2:''''' query_posts() はページ内のメインクエリーを書き換え、新しいクエリーのインスタンスと置き換えるために使う関数としては過度に単純化され、問題が発生しやすい方法です。非効率的で(SQL クエリを再実行します)、一部の状況では適切に実行することもできません(特にページング処理)。モダンな WordPress コードではもっと安定したメソッドを使うべきです。例えば[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]] フックを使った方法などです。ひとことで言うと、query_posts() は決して使うべきではありません。
 +
 
 +
以上のことをしっかり理解し、この関数を賢く活用してください。
 +
 
 +
[[Image:avoid_query_posts.png|500px|right|WP_Query, query_posts and get_posts use cases explained]]
 +
 
 +
<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> を使うことによって、ページ上のメインクエリーが置き換えられ、ページの読み込み速度に影響を与えることに留意してください。最悪の場合、倍かそれ以上の処理が発生します。簡単に使える代わりに、この関数は混乱と問題を引き起こす傾向があります。下記の注意をご覧ください。
 +
 
 +
一般的な投稿の取得には、[[関数リファレンス/WP_Query|WP_Query]] または [[テンプレートタグ/get_posts|get_posts]] を使ってください。
 +
 
 +
<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>
 
<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>
21行目: 39行目:
 
</pre>
 
</pre>
  
==注意<span id="Caveats"></span>==
+
'''注意:''' pre_get_posts アクションは[[Pages|固定ページ]]のリクエストでは動作しません。
  
<tt>query_posts()</tt>はデータベースに問い合わせて投稿の一覧を生成するたくさんの方法のひとつに過ぎません。<tt>query_posts()</tt>を使うと決める前に、欠点も理解しておいてください。
+
<div id="Caveats">
 +
== 注意 ==
 +
</div>
 +
<tt>query_posts()</tt> はデータベースに問い合わせて投稿の一覧を生成するための、数ある方法のひとつに過ぎません。<tt>query_posts()</tt> を使うと決める前に、欠点も理解しておいてください。
  
===メインループを変更する<span id="AltersMainLoop"></span>===
+
<div id="Alters Main Loop">
 +
=== メインループを変更する ===
 +
</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>
 +
派生的な一覧 (例えばページの下部に関連記事を表示したり、サイドバーのウィジェットでリンクの一覧を出したり等) を表示したい場合は、[[関数リファレンス/WP_Query|WP_Query]] の新しいインスタンスを生成するか、[[テンプレートタグ/get_posts|get_posts()]] を使ってください。
  
===派生的なループ<span id="SecondaryLoops"></span>===
+
もし <tt>query_posts()</tt> を使う場合は、用が済んだら必ず <tt>wp_reset_query()</tt> を呼び出してください。
  
派生的な一覧(たとえば、ページの下部に関連記事を表示したり、サイドバーのウィジェットでリンクの一覧をだしたり)を表示したい場合は、[[関数リファレンス/WP_Query|WP_Query]]の新しいインスタンスを生成するか、[[テンプレートタグ/get_posts|get_posts]]を使ってください。
+
<div id="Pagination">
 +
=== ページ送り ===
 +
</div>
 +
'paged' クエリー引数を適切に指定していないと、ページ送りが正しく動作しない可能性があります。「[[Pagination#Adding_the_.22paged.22_parameter_to_a_query|クエリに "paged" パラメーターを追加]]」を参照してください。
  
もし<tt>query_posts()</tt>を使う場合は、用が済んだら必ず<tt>wp_reset_query()</tt>を呼び出してください。
+
<div id="Additional SQL Queries">
 +
=== SQLクエリーが追加発行される ===
 +
</div>
 +
もし <tt>query_posts</tt> をテンプレートで使用する場合、そのテンプレートを読み込むまでに WordPress はすでにデータベースへの問い合わせを実行し、データの取り出しを終えています(どのテンプレートを読み込むかが決まったということは、すでに処理が終わっているということですから!)。そのため、<tt>query_posts()</tt> を使ってデフォルトのクエリーを上書きして結果を得るには、どうしても再度データベースに問い合わせし再計算する必要があります。
  
===ページ送り<span id="Pagination"></span>===
+
このことは、小規模なブログベースのウェブサイトを扱っているのであれば、必ずしも問題であるとは言えません。しかしデータベースが大きい大規模でトラフィックの多いウェブサイトの開発者であれば、デフォルトのクエリーが呼び出される前に直接変更するなどの代替案を検討するほうがいいかもしれません。[[プラグイン_API/アクションフック一覧/request|request]] フィルターでまさにこれを実現できるでしょう。
  
'paged' クエリー引数を適切に指定していないと、ページ送りが正しく動作しない可能性があります:[http://codex.wordpress.org/Pagination#Adding_the_.22paged.22_parameter_to_a_query adding the paged parameter]
+
データベースへ問い合わせる SQL を生成するのに使われる内部的な <tt>$query</tt> オブジェクトを改変するには、'parse_query' と '[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]]' フィルターも利用できます。
  
===SQLクエリーが追加発行される<span id="AdditionalSQLQueries"></span>===
 
 
<tt>query_posts</tt>をテンプレートで使用する場合、WordPressはすでにデータベースへの問い合わせを実行し、テンプレートを読み込む頃にはデータの取り出しを終えています(なぜなら、どのテンプレートが読み込まれるかが決まったということは、すでに処理が終わっているということですから!)。そのため、<tt>query_posts()</tt>を使ってデフォルトのクエリーを上書きして結果を得るには、どうしても再度データベースに問い合わせし再計算する必要があります。
 
 
このことは、小規模なブログベースのウェブサイトを扱っているのであれば、必ずしも問題であるとは言えません。データベースが大きい大規模でトラフィックの多いウェブサイトの開発者であれば、デフォルトのクエリーが呼び出される前に直接変更できる代替案を検討するほうがいいかもしれません。[[プラグイン_API/アクションフック一覧/request|request]]フィルターでまさにこれを実現できるでしょう。
 
 
'parse_query' と '[[プラグイン_API/アクションフック一覧/pre_get_posts|pre_get_posts]]' フィルターも内部的に$queryオブジェクトを改変しデータベースへ問い合わせるSQLを生成するのに使われます。
 
 
<!-- 旧記述ここから
 
<tt>query_posts</tt> は [[The Loop|WordPress ループ]] で表示される投稿を変更するために使います。この関数は URL で使われるのと同じ書式の各種引数(例:<tt>p=4</tt> なら 投稿 ID が 4 の投稿のみを表示)を受け取ります。
 
 
URL から得られたクエリを変更することはトラブルの元になります。[[Conditional Tags|条件分岐タグ]] のようなページの判定を組み合わせることで、URL を一切変えることなく投稿 の見せ方をカスタマイズすることができます。
 
 
よくある利用例:
 
*  フロントページに任意の投稿を表示する(管理画面の [[管理パネル#Settings|設定]] > [[管理パネル/表示設定|表示設定]] で固定ページを指定することもできます)。
 
*  指定した期間の投稿すべてを表示する。
 
*  フロントページに最新の投稿(だけ)を表示する。
 
*  投稿の表示順序を変更する。
 
*  特定のカテゴリーに含まれる投稿だけを表示する。
 
*  1つまたは複数のカテゴリーに含まれる投稿を除く。
 
 
==重要事項<span id="Important_notes"></span>==
 
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]] オブジェクトを作成します。
 
 
旧記述ここまで -->
 
 
==使い方<span id="Usage"></span>==
 
  
 +
<div id="Usage">
 +
== 使い方 ==
 +
</div>
 
<pre>
 
<pre>
 
<?php
 
<?php
 
+
// クエリ(メインクエリを改変)
// クエリ
+
 
query_posts( $args );
 
query_posts( $args );
  
// ループ
+
// ループ(改変したメインクエリ)
 
if ( have_posts() ) :  
 
if ( have_posts() ) :  
  while ( have_posts() ) :  
+
    while ( have_posts() ) : the_post();
    the_post();
+
        echo '<li>';
      ..
+
        the_title();
  endwhile;  
+
        echo '</li>';
 +
    endwhile;  
 
else:
 
else:
  ..
+
    // 何も取得されなかった
 
endif;
 
endif;
  
 
// クエリをリセット
 
// クエリをリセット
 
wp_reset_query();
 
wp_reset_query();
 
 
?>
 
?>
 
</pre>
 
</pre>
  
===注意事項<span id="Usage_Note"></span>===
+
[[テンプレート]]ファイルのひとつに対して、[[ループ]]が始まる前の部分に <tt>query_posts()</tt> の呼び出しを記述します。<tt>WP_Query</tt> オブジェクトがそのパラメータを使って新しい SQL クエリを生成します。このようにすると、WordPress は URL 経由で受け取った他のパラメータを無視します(ページ番号やカテゴリーなど)。
  
<tt>query_posts()</tt> は [[テンプレート|テンプレート]] ファイル内で [[The Loop|WordPress ループ]] が始まる前に記述します。<tt>wp_query</tt> オブジェクトは与えられた引数から新しい SQL クエリを作ります。このとき、WordPress は(ページ番号やカテゴリーのような)URL から得られた引数を無視します。もしその情報が必要なら、<tt>query_posts()</tt> の引数としてグローバル変数の <tt>$query_string</tt> を与えます。
+
<div id="Preserving_the_Original_Query_Parameters">
 +
=== オリジナルクエリの保持(ページングなど)===
 +
</div>
 +
デフォルトでは query_posts を実行すると、引数で指定した変数を除きページング,カテゴリー,日付などの現在のページのクエリ変数はすべて上書きされます。この時、オリジナルのクエリを保持したい場合は、<tt>query_poats()</tt> の引数にグローバル変数である <tt>$query_string</tt>を用いることができます。
  
例えば、他のクエリ引数に影響を与えずに投稿の表示順序だけを指定したいなら [[The Loop|WordPress ループ]] の前に以下のように記述します:
+
例えば、残りの投稿文字列に影響をおよぼすこと無く投稿の表示順を保持する時、[[ループ]]の前に下記を記述することができます。
  
 
<pre>
 
<pre>
 
global $query_string;
 
global $query_string;
query_posts( $query_string . "&order=ASC" );
+
query_posts( $query_string . '&order=ASC' );
 
</pre>
 
</pre>
  
この形式で <tt>query_posts()</tt> を使う場合は、二重引用符で囲んだ引数をアンド記号(&)で始めてください。または複数の値の引数を追加する場合、配列にする必要があります。
+
<tt>query_posts()</tt> をこのように用いる時、<nowiki>''</nowiki>で囲まれたパラメーターはアンド記号 <tt>&amp;</tt> で始まる必要があります。
  
<pre>
 
global $query_string;
 
parse_str( $query_string, $args );
 
$args[post_type] = array( 'post', 'video' );
 
query_posts( $args );
 
</pre>
 
  
さらに、元のクエリ配列を引数配列に統合することもできます。
+
あるいは、元のクエリ配列を引数配列に統合することもできます。
  
 
<pre>
 
<pre>
121行目: 122行目:
 
</pre>
 
</pre>
  
==引数<span id=""></span>==
 
ここでの記述例がすべてではありません。引数を組み合わせることで、より実用的なクエリが可能になります。
 
  
===投稿者引数===
+
<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"のタグがついた投稿を表示します:
  
* '''<tt>author</tt>''' ''整数'') - use author id.
+
  query_posts( 'cat=1&tag=apples+oranges' );
*  '''<tt>author_name</tt>''' (''文字列'') - use '<tt>user_nicename</tt>' (NOT name).
+
 
 +
 
 +
<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>
 +
ある投稿者に関連付けられた投稿を表示する。
  
'''Show Posts for one Author'''
+
* '''<tt>author</tt>''' (''整数'') - ユーザー ID。
 +
* '''<tt>author_name</tt>''' (''文字列'') - '<tt>user_nicename</tt>' (姓・名・ニックネームではなく)。
  
Display posts by author, using author id:
+
'''ある投稿者の投稿を表示する'''
  
query_posts( 'author=123' );
+
ユーザーIDを用いて投稿者を特定する場合:
  
Display posts by author, using author '<tt>user_nicename</tt>':
+
query_posts( 'author=123' );
  
query_posts( 'author_name=rami' );
+
'<tt>user_nicename</tt>' (ユーザーのスラッグ)を用いて投稿者を特定する場合:
  
'''Show Posts From Several Authors'''
+
query_posts( 'author_name=rami' );
  
Display posts from several specific authors:
+
'''複数投稿者の投稿を表示する'''
  
query_posts( 'author=2,6,17,38' );
+
複数の投稿者の投稿を表示する場合:
  
'''Exclude Posts Belonging to an Author'''
+
query_posts( 'author=2,6,17,38' );
  
Display all posts ''except'' those from an author by prefixing its id with a '-' (minus) sign:
+
'''ある投稿者の投稿を表示しない'''
  
query_posts( 'author=-123' );
+
特定の投稿者「以外」の投稿を全て表示させる場合は、IDの前に <tt>'-' (マイナス)</tt> をつけます:
  
===カテゴリー引数<span id="Category_Parameters"></span>===
+
query_posts( 'author=-123' );
  
 +
<div id="Category_Parameters">
 +
=== カテゴリー引数 ===
 +
</div>
 
指定したカテゴリーに分類された投稿を表示する。
 
指定したカテゴリーに分類された投稿を表示する。
  
203行目: 241行目:
 
  query_posts( array( 'category__not_in' => array( 2, 6 ) ) );
 
  query_posts( array( 'category__not_in' => array( 2, 6 ) ) );
  
===タグ引数<span id="Tag_Parameters"></span>===
+
<div id="Tag_Parameters">
 +
=== タグ引数 ===
 +
</div>
 
指定したタグがつけられた投稿を表示する。
 
指定したタグがつけられた投稿を表示する。
 
* '''<tt>tag</tt>''' (文字列)- タグスラッグを指定。
 
* '''<tt>tag</tt>''' (文字列)- タグスラッグを指定。
215行目: 255行目:
 
'''指定した1つのタグを含む投稿を表示'''
 
'''指定した1つのタグを含む投稿を表示'''
  
Display posts that have this tag, using tag slug:
+
タグのスラッグを用いて特定のタグのみ表示させる場合:
  
 
  query_posts('tag=cooking');
 
  query_posts('tag=cooking');
  
Display posts that have this tag, using tag id:
+
タグのIDを用いて特定のタグのみ表示させる場合:
  
query_posts( 'tag_id=13' );
+
query_posts( 'tag_id=13' );
  
 
 
'''Show Posts From Several Tags'''
+
'''指定した複数のタグを含む投稿を表示'''
  
 
指定したタグのいずれかを含む投稿を表示。
 
指定したタグのいずれかを含む投稿を表示。
252行目: 292行目:
 
[http://boren.nu/archives/2007/10/01/taxonomy-intersections-and-unions/ Ryan's discussion of Tag intersections and unions] も参照してください。
 
[http://boren.nu/archives/2007/10/01/taxonomy-intersections-and-unions/ Ryan's discussion of Tag intersections and unions] も参照してください。
  
===タクソノミー引数<span id="Taxonomy_Parameters"></span>===
+
<div id="Taxonomy_Parameters">
 
+
=== タクソノミー引数 ===
特定の[[Taxonomies|タクソノミー]]に関連付けられた投稿を表示。
+
</div>
 +
特定の[[カスタム分類|タクソノミー]]に関連付けられた投稿を表示。
  
 
*  '''<tt>{tax}</tt>''' (''文字列'') - タクソノミースラッグ。
 
*  '''<tt>{tax}</tt>''' (''文字列'') - タクソノミースラッグ。
289行目: 330行目:
 
</pre>
 
</pre>
  
===投稿者引数<span id="Author_Parameters"></span>===
+
<div id="Author_Parameters">
 +
=== 投稿者引数 ===
 +
</div>
 
指定した ID や名前の投稿者による投稿を表示する。
 
指定した ID や名前の投稿者による投稿を表示する。
 
*  <tt>author=3</tt> (整数)- 表示する投稿者の ID を指定。
 
*  <tt>author=3</tt> (整数)- 表示する投稿者の ID を指定。
300行目: 343行目:
 
  query_posts('caller_get_posts=1&author=1&post_type=page&post_status=publish&orderby=title&order=ASC');
 
  query_posts('caller_get_posts=1&author=1&post_type=page&post_status=publish&orderby=title&order=ASC');
  
===投稿・固定ページ引数<span id="Post_.26_Page_Parameters"></span>===
+
<div id="Post_.26_Page_Parameters">
 +
=== 投稿・固定ページ引数 ===
 +
</div>
 
ブログ投稿や固定ページに関連付けられた post を表示。
 
ブログ投稿や固定ページに関連付けられた post を表示。
  
308行目: 353行目:
 
* '''<tt>pagename</tt>''' (''文字列'') - 固定ページスラッグを指定。
 
* '''<tt>pagename</tt>''' (''文字列'') - 固定ページスラッグを指定。
 
* '''<tt>post_parent</tt>''' (''整数'') - 固定ページ ID を指定。子ページのみを返す。
 
* '''<tt>post_parent</tt>''' (''整数'') - 固定ページ ID を指定。子ページのみを返す。
* '''<tt>post__in</tt>''' (''配列'') - use post ids. Specify posts to retrieve.
+
* '''<tt>post__in</tt>''' (''配列'') - 投稿IDを用いて、それのみを指定する。
* '''<tt>post__not_in</tt>''' (''配列'') - use post ids. Specify post NOT to retrieve.
+
* '''<tt>post__not_in</tt>''' (''配列'') - 投稿IDを用いて、それ以外を指定する。
* '''<tt>post_type</tt>''' (''string'' / ''array'') - use post types. Retrieves posts by [[Post Types]], default value is '<tt>post</tt>';
+
* '''<tt>post_type</tt>''' (''string'' / ''array'') - [[Post Types|投稿タイプ]]を用いて指定する。初期値は <tt>post</tt>';
 
** '<tt>post</tt>'
 
** '<tt>post</tt>'
 
** '<tt>page</tt>'
 
** '<tt>page</tt>'
 
** '<tt>revision</tt>'
 
** '<tt>revision</tt>'
 
** '<tt>attachment</tt>'
 
** '<tt>attachment</tt>'
** '<tt>any</tt>' - retrieves any type except revisions
+
** '<tt>any</tt>' - revision以外すべてのタイプ
** Custom Post Types (e.g. movies)
+
** カスタム投稿タイプ (例: movies)
* '''<tt>post_status</tt>''' (''string'' / ''array'') - use post status. Retrieves posts by [[Post Status]], default value is '<tt>publish</tt>';
+
* '''<tt>post_status</tt>''' (''文字列'' / ''配列'') - 公開状態を用いて指定する。投稿の[[Post Status]]を参照, 初期値は '<tt>publish</tt>';
** '<tt>publish</tt>' - a published post or page
+
** '<tt>publish</tt>' - 公開になっている投稿もしくは固定ページ
** '<tt>pending</tt>' - post is pending review
+
** '<tt>pending</tt>' - レビュー待ち
** '<tt>draft</tt>' - a post in draft status
+
** '<tt>draft</tt>' - 下書きの投稿もしくは固定ページ
** '<tt>auto-draft</tt>' - a newly created post, with no content
+
** '<tt>auto-draft</tt>' - 本文のない、自動下書き投稿
** '<tt>future</tt>' - a post to publish in the future
+
** '<tt>future</tt>' - 未来の日付で公開される投稿
** '<tt>private</tt>' - not visible to users who are not logged in
+
** '<tt>private</tt>' - 非公開になっている投稿
** '<tt>inherit</tt>' - a revision. see [[関数リファレンス/get_children|get_children]].  
+
** '<tt>inherit</tt>' - リビジョン。 [[関数リファレンス/get_children|get_children]]も参照のこと。  
** '<tt>trash</tt>' - post is in trashbin. added with [[Version 2.9]].
+
** '<tt>trash</tt>' - ゴミ箱にある投稿([[Version 2.9]]で追加されたパラメータ)
  
 
'''ID を指定して投稿・固定ページを表示'''
 
'''ID を指定して投稿・固定ページを表示'''
339行目: 384行目:
 
'''スラッグを指定して投稿・固定ページを表示'''
 
'''スラッグを指定して投稿・固定ページを表示'''
  
Display post by his <tt>slug</tt>:
+
投稿を表示:
  
 
  query_posts( 'name=about-my-life' );
 
  query_posts( 'name=about-my-life' );
  
Display page by his <tt>slug</tt>:
+
固定ページを表示:
  
 
  query_posts( 'pagename=contact' );
 
  query_posts( 'pagename=contact' );
  
'''Show Child Posts/Pages'''
+
'''子ページを表示'''
  
Display child pages using the slug of the parent and the child page, separated by a slash:
+
親ページ・子ページのスラッグを指定して表示(スラッグはスラッシュで区切る):
  
 
  query_posts( 'pagename=parent_slug/child_slug' );
 
  query_posts( 'pagename=parent_slug/child_slug' );
  
Display child pages using parent page ID:
+
親ページ ID を指定して子ページを表示:
  
 
  query_posts( 'post_parent=93' );
 
  query_posts( 'post_parent=93' );
  
'''Multiple Posts/Pages Handling'''
+
'''複数の投稿/固定ページの取り扱い'''
  
Display only the specify posts:
+
特定の投稿IDのみを表示:
  
 
  query_posts( array( 'post__in' => array( 2, 5, 12, 14, 20 ) ) );
 
  query_posts( array( 'post__in' => array( 2, 5, 12, 14, 20 ) ) );
  
Display all posts but NOT the specify ones:
+
特定の投稿IDを除外して表示:
  
 
  query_posts( array( 'post__not_in' => array( 2, 5, 12, 14, 20 ) ) );
 
  query_posts( array( 'post__not_in' => array( 2, 5, 12, 14, 20 ) ) );
  
Note: you cannot combine 'post__in' and 'post__not_in' in the same query.
+
注意: 同一のクエリーで 'post__in' 'post__not_in' の併用はできません。
  
 
'''投稿タイプを指定して投稿を表示'''
 
'''投稿タイプを指定して投稿を表示'''
393行目: 438行目:
 
  query_posts( array( 'post_status' => array( 'pending', 'draft', 'future' ) ) );
 
  query_posts( array( 'post_status' => array( 'pending', 'draft', 'future' ) ) );
  
===ページ送り引数<span id="Pagination_Parameters"></span>===
+
<div id="Pagination_Parameters">
  
* '''<tt>showposts</tt>''' (''整数'') - number of post to show per page. '''Deprecated''' in favor of 'posts_per_page'.
+
=== ページ送り引数 ===
* '''<tt>posts_per_page</tt>''' (''整数'') - number of post to show per page. Use <tt>'posts_per_page'=>-1</tt> to show all posts. Note if the query is in a feed, wordpress overwrites this parameter with the stored 'posts_per_rss' option. To reimpose the limit, try using the 'post_limits' filter.
+
</div>
* '''<tt>nopaging</tt>''' (''ブーリアン'') - 全ての投稿を表示するかページ送りを使うかを指定します。デフォルトは'false'でページ送りを使います。
+
* '''<tt>paged</tt>''' (''整数'') - number of page. Show the posts that would normally show up just on page X when using the "Older Entries" link.
+
  
Pagination Note: You should set <tt>get_query_var( 'page' );</tt> if you want your query to work with pagination. Since [[Version 3.0.2|Wordpress 3.0.2]], you do <tt>get_query_var( 'page' )</tt> instead of <tt>get_query_var( 'paged' )</tt>. The pagination parameter '<tt>paged</tt>' for <tt>query_posts()</tt> remains the same.
+
[[関数リファレンス/WP Query#Pagination_Parameters|<tt>WP_Query</tt> の「ページ送りパラメータ」セクション]]を見てください。
  
'''Show x Posts per page'''
+
<div id="Offset_Parameter">
  
Display 3 posts per page:
+
=== オフセット引数 ===
 
+
</div>
query_posts( 'posts_per_page=3' );
+
 
+
'''Show All Post'''
+
 
+
Display all posts in one page:
+
 
+
query_posts( 'posts_per_page=-1' );
+
 
+
Display all posts by disabling pagination:
+
 
+
query_posts( 'nopaging=true' );
+
 
+
'''Show Posts from page x'''
+
 
+
Display posts from page number 6:
+
 
+
query_posts( 'paged=6' );
+
 
+
'''Show Posts from Current Page'''
+
 
+
Display posts from current page:
+
 
+
$page = get_query_var( 'page' );
+
query_posts( 'paged=$page' );
+
 
+
===オフセット引数<span id="Offset_Parameter"></span>===
+
 
表示される投稿の先頭から指定した件数をスキップします。  
 
表示される投稿の先頭から指定した件数をスキップします。  
 
* <tt>offset</tt> (整数)- 投稿の先頭からスキップする件数を指定。
 
* <tt>offset</tt> (整数)- 投稿の先頭からスキップする件数を指定。
439行目: 456行目:
 
  query_posts('posts_per_page=5&offset=1');
 
  query_posts('posts_per_page=5&offset=1');
  
===並び順・並べ替え引数<span id="Order_.26_Orderby_Parameters"></span>===
+
<div id="Order_Orderby_Parameters">
 
+
=== 並び順・並べ替え引数 ===
 +
</div>
 
取得した投稿を並べ替える。
 
取得した投稿を並べ替える。
  
* '''<tt>order</tt>''' (''string'') - Designates the ascending or descending order of the '<tt>orderby</tt>' parameter.
+
* '''<tt>order</tt>''' (''文字列'') - '<tt>orderby</tt>' 引数を使った際の並び順
 
** '<tt>ASC</tt>' - 昇順。小さい値から大きい値の順(1, 2, 3; a, b, c)
 
** '<tt>ASC</tt>' - 昇順。小さい値から大きい値の順(1, 2, 3; a, b, c)
 
** '<tt>DESC</tt>' - 降順。大きい値から小さい値の順(3, 2, 1; c, b, a)
 
** '<tt>DESC</tt>' - 降順。大きい値から小さい値の順(3, 2, 1; c, b, a)
  
* '''<tt>orderby</tt>''' (''string'') - Sort retrieved posts by:
+
* '''<tt>orderby</tt>''' (''文字列'') - 記事を並べ替える条件:
 
** '<tt>none</tt>' - 順番指定なし([[Version 2.8|バージョン 2.8]] 以降のみ)
 
** '<tt>none</tt>' - 順番指定なし([[Version 2.8|バージョン 2.8]] 以降のみ)
** '<tt>ID</tt>' - Order by post id.
+
** '<tt>ID</tt>' - 投稿IDで並べ替え
** '<tt>author</tt>' - Order by author.
+
** '<tt>author</tt>' - 記事の著者名で並べ替え
** '<tt>title</tt>' - Order by title.
+
** '<tt>title</tt>' - 記事のタイトルで並べ替え
** '<tt>date</tt>' - Order by date.
+
** '<tt>date</tt>' - 記事の投稿日で並べ替え
** '<tt>modified</tt>' - Order by last modified date.
+
** '<tt>modified</tt>' - 記事の更新日で並べ替え
** '<tt>parent</tt>' - Order by post/page parent id.
+
** '<tt>parent</tt>' - 投稿または固定ページの親のIDで並べ替え
** '<tt>rand</tt>' - Random order.
+
** '<tt>rand</tt>' - ランダムに並べ替え
** '<tt>comment_count</tt>' - コメント数で並べ替え([[Version 2.9|バージョン 2.9]] 以降のみ)
+
** '<tt>comment_count</tt>' - コメント数で並べ替え([[Version 2.9|バージョン 2.9]] 以降)
** '<tt>menu_order</tt>' - Order by  Page Order. Used most often for [[Pages|固定ページ]] (''Order'' field in the Edit Page Attributes box) and for [[attachments]] (the integer fields in the Insert / Upload Media Gallery dialog), but could be used for any post type with distinct '<tt>menu_order</tt>' values (they all default to <var>0</var>).
+
** '<tt>menu_order</tt>' - ページの「順序」で並べ替え。たいていの場合 [[Pages|固定ページ]] (''順序'' フィールドはページ属性欄にあります) [[添付ファイル]] (並び順は「ギャラリーを作成」ダイアログで、ドラッグ&ドロップで指定します)の表示に使われますが、どのような投稿タイプでも別個の '<tt>menu_order</tt>' 引数を使えます (すべて、初期値は <var>0</var>です)
** '<tt>meta_value</tt>' - Note that a '<tt>meta_key=keyname</tt>' must also be present in the query. Note also that the sorting will be alphabetical which is fine for strings (i.e. words), but can be unexpected for numbers (e.g. 1, 3, 34, 4, 56, 6, etc, rather than 1, 3, 4, 6, 34, 56 as you might naturally expect).
+
** '<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>' - Order by numeric meta value (available with [[Version 2.8]]).
+
** '<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).
  
'''Show Posts sorted by Title, Descending order'''
+
'''記事タイトルの降順で並び替えて表示する'''
  
Display posts sorted by post title in a descending order:
+
記事タイトルの降順で並び替えて表示:
  
 
  query_posts( 'orderby=title&order=DESC' );
 
  query_posts( 'orderby=title&order=DESC' );
  
'''Show Random Post'''
+
'''ランダムに表示する'''
  
Display one random post:
+
ランダムに表示:
  
 
  query_posts( 'orderby=rand&posts_per_page=1' );
 
  query_posts( 'orderby=rand&posts_per_page=1' );
  
'''Show Popular Posts'''
+
'''参照数の多い記事を表示する'''
  
Display posts ordered by comment count:
+
コメント数で並べ替えて表示:
  
 
  query_posts( 'orderby=comment_count&order=DESC' );
 
  query_posts( 'orderby=comment_count&order=DESC' );
  
===先頭固定投稿引数<span id="Sticky_Post_Parameters"></span>===
+
<div id="Sticky_Post_Parameters">
===Sticky Post Parameters===
+
 
+
Show sticky post or ignore them.
+
 
+
* '''<tt>caller_get_posts</tt>''' (''bool'') - ignore sticky posts or not. '''Deprecated''' as of [[Version 3.1]] in favor of '<tt>ignore_sticky_posts</tt>'.
+
* '''<tt>ignore_sticky_posts</tt>''' (''bool'') - ignore sticky posts or not. Default value is 0, don't ignore. Ignore/exclude sticky posts being included at the beginning of posts returned, but the sticky post will still be returned in the natural order of that list of posts returned.
+
 
+
'''Show Sticky Posts'''
+
 
+
Display just the first sticky post:
+
 
+
$sticky = get_option( 'sticky_posts' );
+
query_posts( 'p=' . $sticky[0] );
+
 
+
Display just the first sticky post, if none return the last post published:
+
 
+
$args = array(
+
'posts_per_page' => 1,
+
'post__in'  => get_option( 'sticky_posts' ),
+
'ignore_sticky_posts' => 1
+
);
+
query_posts( $args );
+
 
+
Display just the first sticky post, if none return nothing:
+
 
+
$sticky = get_option( 'sticky_posts' );
+
$args = array(
+
'posts_per_page' => 1,
+
'post__in'  => $sticky,
+
'ignore_sticky_posts' => 1
+
);
+
query_posts( $args );
+
if ( $sticky[0] ) {
+
// insert here your stuff...
+
}
+
 
+
'''Don't Show Sticky Posts'''
+
 
+
Exclude all sticky posts from the query:
+
 
+
query_posts( array( 'post__not_in' => get_option( 'sticky_posts' ) ) );
+
 
+
Exclude sticky posts from a category. Return ALL posts within the category, but don't show sticky posts at the top. The 'sticky posts' will still show in their natural position (e.g. by date):
+
  
query_posts( 'ignore_sticky_posts=1&posts_per_page=3&cat=6' );
+
=== 先頭固定投稿引数 ===
 +
</div>
  
Exclude sticky posts from a category. Return posts within the category, but exclude sticky posts completely, and adhere to paging rules:
+
[[関数リファレンス/WP Query#Sticky_Post_Parameters|<tt>WP_Query</tt> の「先頭固定投稿パラメータ」セクション]]を見てください。
  
$paged = get_query_var( 'page' ) ? get_query_var( 'page' ) : 1;
+
<div id="Time_Parameters">
$sticky = get_option( 'sticky_posts' );
+
$args = array(
+
'cat' => 3,
+
'ignore_sticky_posts' => 1,
+
'post__not_in' => $sticky,
+
'paged' => $paged
+
);
+
query_posts( $args );
+
  
===日時引数<span id="Time_Parameters"></span>===
+
=== 日時引数 ===
 +
</div>
 
指定した日時の間に投稿された投稿を表示。
 
指定した日時の間に投稿された投稿を表示。
  
608行目: 578行目:
 
</pre>
 
</pre>
  
===カスタムフィールド引数<span id="Custom_Field_Parameters"></span>===
+
<div id="Custom_Field_Parameters">
 +
=== カスタムフィールド引数 ===
 +
</div>
 
カスタムフィールドのキーまたは値を元に投稿を表示。   
 
カスタムフィールドのキーまたは値を元に投稿を表示。   
  
641行目: 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' );
 
  
===引数の組み合わせ<span id="Combining_Parameters"></span>===
+
############ ここまで旧記述。WP_Query と整合させるため削除 ############ -->
引数はアンド記号(&)を使って複数組み合わせて指定することができます:
+
 
+
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' ) );
+
 
+
[[Version 2.3|バージョン 2.3]] と [[Version 2.5|バージョン 2.5]] では、カテゴリー ID が 1 で "apples" を含む投稿を表示することが期待される。
+
 
+
query_posts( 'cat=1&tag=apples' );
+
 
+
バグ:カテゴリーとタグを同時に指定する場合は「+」で同じタグを2つ指定してください。参照 [http://trac.wordpress.org/ticket/5433 Ticket #5433]
+
 
+
query_posts( 'cat=1&tag=apples+apples' );
+
 
   
 
   
注意:'cat=1&tag=apples+oranges' は期待する結果にはなりません。
 
 
==コード記述例<span id="Examples"></span>==
 
 
===「最新の投稿」ページから指定カテゴリーを除く<span id="Exclude_Categories_From_Your_Home_Page"></span>===
 
  
<tt>index.php</tt> ファイルに以下のコードを書くと、カテゴリー ID が 3 ''以外の'' 投稿を表示。
+
<div id="Examples">
 +
== コード記述例 ==
 +
</div>
 +
<div id="Exclude_Categories_From_Your_Home_Page">
 +
=== 「最新の投稿」ページから指定カテゴリーを除く ===
 +
</div>
 +
<tt>index.php</tt> ファイルに以下のコードを書くと、カテゴリー ID が 3 ''以外の'' 投稿を表示します。
  
 
<pre>
 
<pre>
682行目: 633行目:
 
</pre>
 
</pre>
  
複数のカテゴリー ID を指定できる([[Version 2.1.2|バージョン 2.1.2]] で検証済)。
+
複数のカテゴリー ID を指定できる([[Version 3.3.1|バージョン 3.3.1]] で検証済)。
 
<pre>
 
<pre>
 
<?php
 
<?php
691行目: 642行目:
 
</pre>
 
</pre>
  
===特定の投稿を表示<span id="Retrieve_a_Particular_Post"></span>===
+
<div id="Retrieve_a_Particular_Post">
 
+
=== 特定の投稿を表示 ===
特定の投稿を表示。
+
</div>
 +
特定の投稿を表示するには次にコードが使えます。
  
 
<pre>
 
<pre>
 
<?php
 
<?php
 
query_posts( 'p=5' );   
 
query_posts( 'p=5' );   
 +
?>
 +
</pre>
 +
 +
'''参考:'''特定の投稿が「添付」の場合、''p'' の代わりに ''attachment_id'' を用います。
 +
 +
<pre>
 +
<?php
 +
query_posts( 'attachment_id=5' ); 
 
?>
 
?>
 
</pre>
 
</pre>
721行目: 681行目:
 
2008年5月に投稿された、カテゴリー ID 1 と 3 の投稿タイトルを1ページに5件ずつ表示する:
 
2008年5月に投稿された、カテゴリー ID 1 と 3 の投稿タイトルを1ページに5件ずつ表示する:
  
<pre><nowiki><?php if (have_posts()) :  query_posts('posts_per_page=5&cat=1,3&monthnum=5&year=2008'); ?>
+
<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 while (have_posts()) : the_post(); ?>
     <h2><?php the_title(); ?></h2>
+
     <?php the_title(); ?>
<?php endwhile; endif; ?></nowiki></pre>
+
<?php endwhile; endif; ?>
 +
</pre>
  
 
カテゴリー ID 2 と 6 のいずれにも含まれないすべての投稿のタイトルをリストとして表示する:
 
カテゴリー ID 2 と 6 のいずれにも含まれないすべての投稿のタイトルをリストとして表示する:
  
<pre><nowiki><?php if (have_posts()) :  query_posts(array('category__not_in' => array(2,6))); ?>
+
<pre><?php if (have_posts()) :  query_posts(array('category__not_in' => array(2,6))); ?>
<ul>
+
  <ul>
<?php while (have_posts()) : the_post(); ?>
+
  <?php while (have_posts()) : the_post(); ?>
    <li><?php the_title(); ?></li>
+
    <li><?php the_title(); ?></li>
<?php endwhile; endif; ?>
+
  <?php endwhile; endif; ?>
</ul></nowiki></pre>
+
  </ul>
 +
</pre>
  
===query_posts に変数を与える<span id="Passing_variables_to_query_posts"></span>===
+
<div id="All Posts in a Category">
query_posts に変数を与える方法は2通りあります。どちらを使用してもかまいません。[[The Loop|WordPress ループ]] の前に記述してください:
+
=== カテゴリーの全投稿 ===
 +
</div>
 +
管理画面の「設定」>「表示設定」で設定する「1ページに表示する最大投稿数」のパラメーターが適用されます。これを上書きするためには、 <tt>'post_per_page'</tt> パラメーターを設定します。以下が例です:
  
==== 記述例 1 <span id=" Example_1"></span>====
+
<pre>
 +
query_posts( array ( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );
 +
</pre>
  
この例は、query_posts を実行する前にクエリ文字列を連結します。まず変数に値を代入し、変数と文字列を結合して、実行します。ここではカテゴリー ID を変数で与えることにします。
+
これにより、指定されたカテゴリーの'''全て'''の投稿を表示させます。
 +
 
 +
 
 +
しかし、サブカテゴリーまたは子カテゴリーでは「カテゴリー名」が常に使えるとは限りません(別のサブカテゴリーまたは子カテゴリーと重複する場合がある)。そこで「カテゴリースラッグ」を用いる方が良いでしょう。詳しくは <tt>[[関数リファレンス/is_category|is_category()]]</tt> を参照してください。
  
 
<pre>
 
<pre>
$categoryvariable = $cat;  // 現在のカテゴリー ID を変数に代入
+
if ( is_category( 'category-slug' ) ) :
$query = 'cat=' . $categoryvariable . '&orderby=date&order=ASC'; // クエリを連結
+
 
query_posts( $query ); // run the query // クエリを実行
+
query_posts( array( 'category_name' => 'my-category-slug', 'posts_per_page' => -1 ) );
 +
 
 +
endif;  
 
</pre>
 
</pre>
  
==== 記述例 2 <span id="Example_2"></span>====
+
<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> で公開日が現在の年・月に該当する投稿を表示します。投稿の並び順は日付の昇順で、公開日の古い順に表示します。
 
次の例では、二重引用符を使って PHP に式を評価させます。まず、現在の年・月を表示し、<tt>query_posts</tt> で公開日が現在の年・月に該当する投稿を表示します。投稿の並び順は日付の昇順で、公開日の古い順に表示します。
 
   
 
   
755行目: 764行目:
 
$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>
  
==== 記述例 3 <span id="Example_3"></span>====
+
<div id="Example_3">
 
+
==== 記述例 3 ====
この例では、ページングを使ってすべての投稿を表示する場合を説明します。デフォルトの <tt>$query_string</tt> を使って <tt>query_posts</tt> ですべての投稿を表示させることができます。<tt>posts_per_page</tt> の値には -1 か各ページに表示したい投稿の数を指定します。後者の場合には [[テンプレートタグ/posts_nav_link|posts_nav_link()]] でページを移動する手段を提供しましょう。
+
</div>
 +
この例では、ページネーションを使ってすべての投稿を表示する場合を説明します。デフォルトの <tt>$query_string</tt> を使って <tt>query_posts</tt> ですべての投稿を表示させることができます。<tt>posts_per_page</tt> の値には -1 か各ページに表示したい投稿の数を指定します。後者の場合には [[テンプレートタグ/posts_nav_link|posts_nav_link()]] でページを移動する手段を提供しましょう。
  
 
<pre>
 
<pre>
766行目: 777行目:
 
</pre>
 
</pre>
  
==== 記述例 4 <span id="Example_4"></span>====
+
<div id="Example_4">
 
+
==== 記述例 4 ====
<tt>$query_string</tt> 変数を使わずに、引数を配列に入れる方法もあります。例えば、記述例 2 のクエリは以下のようになります:
+
</div>
 +
<tt>$query_string</tt> 変数を使わずに、引数を配列に入れる方法もあります。複雑な条件を与えるときはこの方がすっきりして読みやすいでしょう。例えば、記述例 2 のクエリは以下のようになります:
  
 
<pre>
 
<pre>
782行目: 794行目:
 
この方法は、変数ごとに1行ずつ記述すると読み易くなります。
 
この方法は、変数ごとに1行ずつ記述すると読み易くなります。
  
=== オリジナルクエリの保持(ページングなど)<span id="Preserving_the_Original_Query_.28Pagination_etc..29"></span>===
+
<div id="Example_5">
デフォルトでは query_posts を実行すると、引数で指定した変数を除きページング,カテゴリー,日付などの現在のページのクエリ変数はすべて上書きされます。
+
==== 記述例 5 ====
 
+
</div>
オリジナルのクエリを保持したい場合は、query_poats の引数にオリジナルクエリの配列をマージしてください:
+
記述例 4で示した配列形式を使って、複数のタクソノミーを問い合わせることもできます。これは単純に、タクソノミーのスラッグに対してコンマ区切りの文字列を渡すだけです(文字列ひとつがタームひとつに相当)。次の例では、植木等''または''高倉健が出演している映画(カスタム投稿タイプ 'movie')の投稿を全て抽出します。
  
 
<pre>
 
<pre>
global $wp_query;
+
$args = array(
query_posts(
+
'post_type'=> 'movie',
array_merge(
+
'actor'    => 'Hitoshi Ueki, Ken Takakura',
array( 'cat' => 1 ),
+
'order'    => 'ASC'
$wp_query->query
+
);
)
+
query_posts( $args );
);</pre>
+
 
+
 
+
==使い方のヒント<span id="Usage_Tips"></span>==
+
管理画面の 設定 > 表示設定 にある "1ページに表示する最大投稿数" パラメータで通常の表示件数を指定できます。これを変更するには 'posts_per_page' 引数を使います:
+
<pre>
+
query_posts( 'category_name=The Category Name&posts_per_page=-1' ); // 指定カテゴリーに含まれるすべての投稿を表示
+
 
</pre>
 
</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>
+
<div id="Change Log">
if ( isset ( $query->query_vars['feed'] ) and ( $query->query_vars['feed'] == 'ics' ) )
+
== 変更履歴 ==
add_filter( 'post_limits', 'no_limits_for_feed' );
+
</div>
 +
新規導入 : [[Version 1.5|1.5.0]]
  
function no_limits_for_feed( $limits ) {
+
<div id="Source File">
return '';
+
== ソースファイル ==
}
+
</div>
</pre>
+
<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]
  
==リソース<span id="Resources"></span>==
+
<!-- ######################## 旧内容ここから ########################
 
* [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]
824行目: 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|99483}}<!-- 22:56, 25 January 2011 Ramiy 版 -->
+
<div id="Related">
 
+
== 関連項目 ==
==関連==
+
</div>
  
 
{{Query Tags}}
 
{{Query Tags}}
837行目: 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最新版との差分