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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(和訳)
(タクソノミーパラメータ: 非推奨の書式を明示。)
 
(8人の利用者による、間の21版が非表示)
1行目: 1行目:
<div id="Description">
 
 
== 説明 ==
 
== 説明 ==
</div>
 
  
テンプレートタグ [[テンプレートタグ/get_posts|<code>get_posts()</code>]] は、マルチループ(複数ループ)を作成するためのシンプルなタグです。
+
<tt>get_posts</tt> の最も適切な使い方は、パラメータに基づいて投稿データの配列を作成することです。最近の投稿あるいはパラメータに一致した投稿を取得します。[[ループ#複数のループ|複数のループ]]を作成するのに <tt>get_posts</tt> を使用する事もできます。ただしこの場合は <tt>new WP_Query</tt> を使用して <tt>[[Class_Reference/WP_Query|WP_Query]]</tt> を直接参照するほうが好ましいでしょう。
  
<div id="Usage">
+
<tt>[[関数リファレンス/get_pages|get_pages]]</tt> とパラメータが似ていますが実装方法はかなり異なっており、適切に使う必要があります。<tt>get_posts</tt> は <tt>[[Class_Reference/WP_Query|WP_Query]]</tt> を使用していますが、<tt>get_pages</tt> はデータベースに直接クエリを投げます。それぞれ実装の差異を反映したパラメータになっています。
== 使い方 ==
+
</div>
+
  
<?php get_posts('引数'); ?>
+
<tt>[[関数リファレンス/query_posts|query_posts]]</tt> も <tt>[[Class_Reference/WP_Query|WP_Query]]</tt> を使用していますが、グローバル変数 <tt>$wp_query</tt> を書き換えてメインループを直接変更しているので、使う場合は注意してください。一方、<tt>get_posts</tt> は新しい <tt>WP_Query</tt> オブジェクトを参照するため、メインループに影響を与えません。
 +
 
 +
メインクエリが実行される前に変更したい場合は、<tt>[[プラグイン API/アクションフック一覧/pre get posts|pre_get_posts]]</tt> フックを使用することができます。ページの中で、いくつかのパラメータで指定した投稿データを呼び出したい場合は、<tt>get_posts</tt> が最適でしょう。
 +
 
 +
 
 +
===デフォルトの使い方===
 +
 
 +
<pre>
 +
<?php $args = array(
 +
'posts_per_page'   => 5,
 +
'offset'          => 0,
 +
'category'        => '',
 +
'category_name'    => '',
 +
'orderby'          => 'date',
 +
'order'            => 'DESC',
 +
'include'          => '',
 +
'exclude'          => '',
 +
'meta_key'        => '',
 +
'meta_value'      => '',
 +
'post_type'        => 'post',
 +
'post_mime_type'  => '',
 +
'post_parent'      => '',
 +
'author'   => '',
 +
'post_status'      => 'publish',
 +
'suppress_filters' => true
 +
);
 +
$posts_array = get_posts( $args ); ?>
 +
</pre>
 +
 
 +
注: <tt>'numberposts'</tt> または <tt>'posts_per_page'</tt> のいずれかが利用できます。
 +
 
 +
== パラメータ ==
 +
 
 +
パラメータの使い方の例は、[[関数リファレンス/get_pages|<tt>get_pages()</tt>]] をごらんください。
 +
 
 +
<tt>get_posts()</tt> は [[Class_Reference/WP_Query|<tt>WP_Query</tt>]] クラスを利用して投稿を取得します。この関数で使えるパラメータについては、<tt>WP_Query</tt> ドキュメンテーションの[[Class_Reference/WP_Query#Parameters|the parameters section]] をごらんください。
 +
 
 +
'''注意: ''' get_posts は <tt>'suppress_filters' => true</tt> をデフォルトとします。一方、<tt>[[関数リファレンス/query_posts|query_posts()]]</tt> はデフォルトでフィルタを適用するので、WPML のようにクエリを変更するプラグインを使う場合はややこしく感じるかもしれません。また、<tt>'suppress_filters'</tt> が ''true'' の場合でも、<tt>pre_get_posts</tt> に追加されたフィルターは適用されます。<tt>'posts_*'</tt> と <tt>'comment_feed_*'</tt> に追加されたフィルターのみ、抑制されます。
 +
 
 +
'''注意: ''' category パラメータではカテゴリー名ではなくカテゴリー ID を指定する必要があります。
 +
 
 +
'''注意: ''' category パラメータはコンマ区切りの複数カテゴリー ID でもかまいません。これは、<tt>[http://core.trac.wordpress.org/browser/tags/3.3.1/wp-includes/post.php#L1369 get_posts()]</tt> 関数が 'category' パラメータを 'cat' として <tt>WP_Query</tt> に直接渡すからです。
 +
 
 +
'''注意: ''' category_name パラメータは カテゴリ名では、この場合、文字列にする必要があります。
 +
 
 +
 
 +
{{Parameter|'orderby'|文字列|取得した投稿をソートする|オプション|'date'}}
 +
 
 +
:* <tt>'none'</tt> - 順序無し (Version 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 で利用可能)
 +
:* <tt>'menu_order'</tt> - ページ順序。固定ページ (ページ属性で指定する) やアタッチメント (メディア投稿ダイアログの数値) で使われるが、<tt>'menu_order'</tt> 値 (デフォルトは 0) を持つ任意の投稿タイプで使用可能。
 +
:* <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>'meta_key=keyname'</tt> がある場合のみ有効。<tt>'meta_value'</tt> の項に記載の数字での並べ替えを行う。
 +
:* <tt>'post__in'</tt> - 'include' パラメータで渡したものと同じ順序に一致。
 +
:'''注:''' [[関数リファレンス/get_pages|<tt>get_pages()</tt>]] は <tt>'orderly'</tt> ではなく、<tt>'sort_column'</tt> を使用します。また [[関数リファレンス/get_pages|<tt>get_pages()</tt>]] は <tt>'post_'</tt> を前置します: <tt>'author, date, modified, parent, title, excerpt, content'</tt>
 +
 
 +
{{Parameter|'post_mime_type'|文字列 / 配列|mime types の一覧またはコンマ区切り|オプション}}
 +
 
 +
== 返り値 ==
 +
 
 +
; (配列) : [[クラスリファレンス/WP_Post|WP_Post]] オブジェクトのリスト。
 +
 
 +
<tt>[[関数リファレンス/get_pages|get_pages()]]</tt> と異なり、<tt>get_posts()</tt> は適切なコンテキスト(管理者の場合、など)では ''private'' ページを返します。 (参考: Andreas Kirsch, [http://blog.blackhc.net/2009/01/wordpress-hacking-ii/ WordPress Hacking II], January 24, 2009-- accessed 2012-11-09.)
  
<div id="Examples">
 
 
== 用例 ==
 
== 用例 ==
</div>
 
  
<div id="Generate_list">
+
=== オフセットのあるリストの生成 ===
=== リストの生成 ===
+
 
 +
フロントページで 1 件だけ表示してから、カテゴリーID が 1 の投稿へのリンクをそれに先行する 5 件分表示したい場合、下記のようにします。
 +
 
 +
<pre>
 +
<ul>
 +
<?php
 +
 
 +
 
 +
$args = array( 'posts_per_page' => 5, 'offset'=> 1, 'category' => 1 );
 +
 
 +
$myposts = get_posts( $args );
 +
foreach ( $myposts as $post ) : setup_postdata( $post ); ?>
 +
<li>
 +
<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
 +
</li>
 +
<?php endforeach;
 +
wp_reset_postdata();?>
 +
 
 +
</ul>
 +
</pre>
 +
 
 +
'''注:''' ''2件以上の記事がないカテゴリで上記のクエリを使うと何も表示されません。''
 +
 
 +
=== 前後の投稿へのリンクがある投稿 ===
 +
 
 +
前後の投稿へのリンクがある投稿を作成することができます。
 +
下記のようにします。
 +
 
 +
<pre><?php
 +
$postlist = get_posts( 'sort_column=menu_order&amp;sort_order=asc' );
 +
$posts = array();
 +
foreach ( $postlist as $post ) {
 +
  $posts[] += $post->ID;
 +
}
 +
 
 +
$current = array_search( get_the_ID(), $posts );
 +
$prevID = $posts[$current-1];
 +
$nextID = $posts[$current+1];
 +
?>
 +
 
 +
<div class="navigation">
 +
<?php if ( !empty( $prevID ) ): ?>
 +
<div class="alignleft">
 +
<a href="<?php echo get_permalink( $prevID ); ?>"
 +
  title="<?php echo get_the_title( $prevID ); ?>">Previous</a>
 +
</div>
 +
<?php endif;
 +
if ( !empty( $nextID ) ): ?>
 +
<div class="alignright">
 +
<a href="<?php echo get_permalink( $nextID ); ?>"
 +
title="<?php echo get_the_title( $nextID ); ?>">Next</a>
 
</div>
 
</div>
 +
<?php endif; ?>
 +
</div><!-- .navigation --></pre>
  
サイトのフロントページに最新の記事を 1件のみ表示するよう設定していて、その次から 5件かつカテゴリID 1 の記事へのリンクと抜粋文を表示したいとき、次のようにコードを書きます。
+
==== オフセットのリセット ====
 +
 
 +
ループの後で、foreach 実行前の記事が必要な場合は、以下のように記述します。
  
 
<pre>
 
<pre>
 
<ul>
 
<ul>
 
<?php
 
<?php
$myposts = get_posts('numberposts=5&offset=1&category=1');
+
global $post;
foreach($myposts as $post) :
+
$args = array( 'posts_per_page' => 5, 'offset'=> 1, 'category' => 1 );
 +
$myposts = get_posts( $args );
 +
foreach ( $myposts as $post ) :  
 +
  setup_postdata( $post ); ?>
 +
<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
 +
<?php endforeach;
 +
wp_reset_postdata(); ?>
 +
</ul>
 +
</pre>
 +
 
 +
=== 全記事データにアクセスする ===
 +
 
 +
get_posts では、デフォルトの状態では利用できない記事データが一部あります。<tt>[[テンプレートタグ/the_content|the_content()]]</tt> のコンテンツや ID などです。内部関数 <tt>setup_postdata()</tt> に、引数として $post 配列を与えることで解決できます。
 +
 
 +
<pre>
 +
<?php
 +
$args = array( 'posts_per_page' => 3 );
 +
$lastposts = get_posts( $args );
 +
foreach ( $lastposts as $post ) :
 +
  setup_postdata( $post ); ?>
 +
<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
 +
<?php the_content(); ?>
 +
<?php endforeach;
 +
wp_reset_postdata(); ?>
 +
</pre>
 +
 
 +
<tt>setup_postdata()</tt> を呼び出さずに投稿 ID またはコンテンツにアクセスしたり、([[Database_Description#Table:_wp_posts|the posts table]] に蓄積されている)任意の投稿データにアクセスするには、<tt>$post->COLUMN</tt> を使用できます。ここで <tt>COLUMN</tt> はデータのテーブルカラム名です。したがって、<tt>$post->ID</tt> は ID、 <tt>$post->post_content</tt> はコンテンツ、といった具合です。データを表示/出力するには、以下のように PHP echo コマンドを使用します。
 +
 
 +
<pre>
 +
<?php echo $post->ID; ?>
 +
</pre>
 +
 
 +
=== 最近の投稿をタイトル順に並べる ===
 +
 
 +
アルファベット順に昇順で最近の 10 件を表示するには、以下のコードで投稿日、タイトル、抜粋を表示します。
 +
 
 +
<pre>
 +
<?php
 +
$args = array( 'posts_per_page' => 10, 'order'=> 'ASC', 'orderby' => 'title' );
 +
$postslist = get_posts( $args );
 +
foreach ( $postslist as $post ) :
 +
  setup_postdata( $post ); ?>
 +
<div>
 +
<?php the_date(); ?>
 +
<br />
 +
<?php the_title(); ?> 
 +
<?php the_excerpt(); ?>
 +
</div>
 +
<?php
 +
endforeach;
 +
wp_reset_postdata();
 
?>
 
?>
    <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a> --- <?php the_excerpt(); ?></li>
+
</pre>
<?php endforeach; ?>
+
 
 +
=== ランダムに表示する ===
 +
 
 +
orderby パラメータに rand を指定して [[Glossary#MySQL|MySQL]] <tt>RAND()</tt> 関数を使用して最近の 5 件をランダムに表示します。
 +
 
 +
<pre>
 +
<ul>
 +
<?php
 +
$args = array( 'posts_per_page' => 5, 'orderby' => 'rand' );
 +
$rand_posts = get_posts( $args );
 +
foreach ( $rand_posts as $post ) :
 +
  setup_postdata( $post ); ?>
 +
<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
 +
<?php endforeach;
 +
wp_reset_postdata(); ?>
 
</ul>
 
</ul>
 
</pre>
 
</pre>
  
'''注:''' 上記クエリは、1件以上の記事があるカテゴリで使うべき。
+
=== 添付ファイルを全て表示する ===
  
<div id="Generate_another_list">
+
テンプレートの [[The_Loop|Loops]] 外に記述します。
=== 別のリストの生成 ===
+
</div>
+
  
ウェブページに 10件の記事をアルファベット順に表示したいとき、投稿日・タイトル・抜粋文を出すには次のようにします。
+
<pre>
 +
<?php
 +
$args = array( 'post_type' => 'attachment', 'posts_per_page' => -1, 'post_status' => 'any', 'post_parent' => null );
 +
$attachments = get_posts( $args );
 +
if ( $attachments ) {
 +
foreach ( $attachments as $post ) {
 +
setup_postdata( $post );
 +
the_title();
 +
the_attachment_link( $post->ID, false );
 +
the_excerpt();
 +
}
 +
wp_reset_postdata();
 +
}
 +
?>
 +
</pre>
 +
 
 +
=== 現在の記事の添付ファイルを表示する ===
 +
 
 +
[[The_Loop|ループ]]内(<var>$post->ID</var> が利用できるところ)に記述します。
  
 
<pre>
 
<pre>
 
<?php
 
<?php
$postslist = get_posts('numberposts=10&order=ASC&orderby=post_title');
+
$args = array( 'post_type' => 'attachment', 'posts_per_page' => -1, 'post_status' =>'any', 'post_parent' => $post->ID );  
foreach ($postslist as $post) :
+
$attachments = get_posts( $args );
setup_postdata($post);
+
if ( $attachments ) {
the_date();
+
foreach ( $attachments as $attachment ) {
echo "<br />";
+
echo apply_filters( 'the_title' , $attachment->post_title );
the_title();
+
the_attachment_link( $attachment->ID , false );
the_excerpt();
+
}
endforeach;
+
}
 
?>
 
?>
 
</pre>
 
</pre>
  
<div id="Access_all_post_data">
+
=== スラッグをもとに投稿を取得する ===
=== 全ての投稿データにアクセス ===
+
</div>
+
  
様々な理由から、デフォルトでは、記事 ID や [[テンプレートタグ/the_content|the_content()]] 経由での記事本文といったいくつかのデータが get_posts で取得できません。これは、内部関数 <code>setup_postdata()</code> を <code>$post</code> 配列で呼ぶことにより解決できます。
+
投稿スラッグをもとに投稿 ID を取得できます。
  
<pre><?php
+
<pre>
$lastposts = get_posts('numberposts=3');
+
<?php
 +
$the_slug = 'my-slug';
 +
$args=array(
 +
'name'          => $the_slug,
 +
'post_type'      => 'post',
 +
'post_status'    => 'publish',
 +
'posts_per_page' => 1
 +
);
 +
$my_posts = get_posts( $args );
 +
if( $my_posts ) {
 +
echo 'ID on the first post found ' . $my_posts[0]->ID;
 +
}
 +
?>
 +
</pre>
  
foreach($lastposts as $post) :
+
=== タクソノミーパラメータ ===
    setup_postdata($post);
+
 
    ?>
+
<p class="information">'''注:''' タクソノミー名をキーとする方法(以下の1番目の例)は、バージョン 3.1 以降は'''非推奨'''になりました。代わりに <code>'tax_query'</code> を使用してください(2番目の例)。</p>
    <a href="<?php the_permalink(); ?>" id="post-<?php the_ID(); ?>"><?php the_title(); ?></a>
+
 
    <?php the_content(); ?>
+
特定のタクソノミーと関連する投稿を表示します。カスタム投稿タイプに対して登録されたタクソノミーを指定した場合、'category' ではなく代わりに '{custom_taxonomy_name}'(カスタムタクソノミー名)を使って下さい。例えば、"genre"(ジャンル)というタクソノミーがあり、"jazz" というジャンルに分類された投稿のみを表示したい時は以下のコードを使います。
<?php endforeach; ?>
+
 
 +
<pre>
 +
<?php
 +
$args = array(
 +
'posts_per_page' => 8,
 +
'orderby' => 'rand',
 +
'post_type' => 'albums',
 +
'genre' => 'jazz',  // 非推奨のため 'tax_query' を使ってください
 +
'post_status' => 'publish'
 +
);
 +
$show_albums = get_posts( $args );
 +
?>
 
</pre>
 
</pre>
  
<code>setup_postdata</code> を呼ばずに ID 等を取得する別の方法としては、<code>"$post->ID"</code> や <code>"$post->post_data"</code>(記事本文)を持ちます。これで内部関数を呼ぶことを避けられます。
+
以下の例では、"tax_query" を使い、"genre" カスタムタクソノミーの "jazz" に分類された投稿のみを取得します。
(訳注:こちらの方が望ましいのか?)
+
  
<div id="Parameters">
+
<pre>
== パラメータ ==
+
$args = array(
</div>
+
'tax_query' => array(
 +
array(
 +
'taxonomy' => 'genre',
 +
'field' => 'slug',
 +
'terms' => 'jazz'
 +
)
 +
)
 +
);
 +
$postslist = get_posts( $args );
 +
</pre>
  
; numberposts
+
他の例については、<tt>WP_Query</tt> ドキュメンテーションの [[関数リファレンス/WP_Query#Taxonomy_Parameters|タクソノミーパラメータのセクション]]をご覧ください。
: (''整数'') 取得する投稿の数。初期値は <code>5</code>
+
; offset
+
: (''整数'') 先頭から何件の投稿を除外するか。初期値は <code>0</code>(除外しない)。
+
; category
+
: (''整数'') 指定したカテゴリID の投稿のみを返す。初期値はなし(全カテゴリ)。
+
; orderby
+
: (''文字列'') どの項目の値で投稿をソート(並べ替え)するか。次の値など:
+
:* <code>'post_title'</code> - ページ/記事タイトルのアルファベット順にソート (初期値)
+
:* <code>'post_date'</code> - 投稿日時順にソート
+
:* <code>'post_modified'</code> - 最終更新日時順にソート
+
:* <code>'ID'</code> - 投稿ID でソート
+
:* <code>'post_author'</code> - 著者の ID 番号でソート
+
:* <code>'post_name'</code> - 投稿スラッグのアルファベット順にソート
+
:* '''注:''' この値は [[データベース概要#Table:_wp_posts|wp_post テーブル]] のどのフィールド名でも指定できる。
+
; order
+
: (''文字列'') ソート順。有効値:
+
:* <code>'ASC'</code> - 昇順(値 小→大)にソート
+
:* <code>'DESC'</code> - 降順(値 大→小)にソート (初期値)
+
  
{{原文|Template Tags/get_posts}}
+
=== カスタムフィールドパラメータ ===
  
== 外部リンク ==
+
あるカスタムフィールドと関連する投稿のみを表示します。以下の例では、"meta_query" を使い、"product" 投稿タイプで "featured" というメタキーが "yes" という値を持つ投稿を取得します。:
  
* [http://bono.s201.xrea.com/2007/04/394-wp_get_posts/ power source* » WP: テンプレートタグ get_posts で新着記事リスト等を表示] (2007-04-07) -- 各種使用例
+
<pre>
 +
$args = array(
 +
'post_type' => 'product',
 +
'meta_query' => array(
 +
array(
 +
'key' => 'featured',
 +
'value' => 'yes',
 +
)
 +
)
 +
);
 +
$postslist = get_posts( $args );
 +
</pre>
 +
 
 +
他の例については、<tt>WP_Query</tt> ドキュメンテーションの [[関数リファレンス/WP_Query#Custom_Field_Parameters|カスタムフィールドパラメータのセクション]]をご覧ください。
 +
 
 +
==変更履歴==
 +
 
 +
* [[Version 1.2|1.2.0]] 以降
 +
 
 +
==ソースファイル==
 +
 
 +
<tt>get_posts()</tt> は {{Trac|wp-includes/post.php}} にあります。
  
<div id="Related">
 
 
== 関連 ==
 
== 関連 ==
</div>
 
  
{{Tag General Tags}}
 
{{Query String Tag Footer}}
 
  
{{DEFAULTSORT:get_posts}}
+
{{Query Tags}}
 +
 
 +
{{Tag Footer}}
 +
{{DEFAULTSORT:Get_posts}}
 +
[[Category:テンプレートタグ]]
 +
 
 +
[[en:Template_Tags/get_posts]]
 +
[[es:Etiquetas_de_plantilla/get_posts]]
 +
[[zh-cn:模版标签/get_posts}]]
  
[[en:Template Tags/get_posts]]
+
{{原文|Template Tags/get posts|152429}}<!-- 09:01, 27 June 2015‎ Bishoy.A 版 -->

2016年8月2日 (火) 12:05時点における最新版

説明

get_posts の最も適切な使い方は、パラメータに基づいて投稿データの配列を作成することです。最近の投稿あるいはパラメータに一致した投稿を取得します。複数のループを作成するのに get_posts を使用する事もできます。ただしこの場合は new WP_Query を使用して WP_Query を直接参照するほうが好ましいでしょう。

get_pages とパラメータが似ていますが実装方法はかなり異なっており、適切に使う必要があります。get_postsWP_Query を使用していますが、get_pages はデータベースに直接クエリを投げます。それぞれ実装の差異を反映したパラメータになっています。

query_postsWP_Query を使用していますが、グローバル変数 $wp_query を書き換えてメインループを直接変更しているので、使う場合は注意してください。一方、get_posts は新しい WP_Query オブジェクトを参照するため、メインループに影響を与えません。

メインクエリが実行される前に変更したい場合は、pre_get_posts フックを使用することができます。ページの中で、いくつかのパラメータで指定した投稿データを呼び出したい場合は、get_posts が最適でしょう。


デフォルトの使い方

<?php $args = array(
	'posts_per_page'   => 5,
	'offset'           => 0,
	'category'         => '',
	'category_name'    => '',
	'orderby'          => 'date',
	'order'            => 'DESC',
	'include'          => '',
	'exclude'          => '',
	'meta_key'         => '',
	'meta_value'       => '',
	'post_type'        => 'post',
	'post_mime_type'   => '',
	'post_parent'      => '',
	'author'	   => '',
	'post_status'      => 'publish',
	'suppress_filters' => true 
);
$posts_array = get_posts( $args ); ?>

注: 'numberposts' または 'posts_per_page' のいずれかが利用できます。

パラメータ

パラメータの使い方の例は、get_pages() をごらんください。

get_posts()WP_Query クラスを利用して投稿を取得します。この関数で使えるパラメータについては、WP_Query ドキュメンテーションのthe parameters section をごらんください。

注意: get_posts は 'suppress_filters' => true をデフォルトとします。一方、query_posts() はデフォルトでフィルタを適用するので、WPML のようにクエリを変更するプラグインを使う場合はややこしく感じるかもしれません。また、'suppress_filters'true の場合でも、pre_get_posts に追加されたフィルターは適用されます。'posts_*''comment_feed_*' に追加されたフィルターのみ、抑制されます。

注意: category パラメータではカテゴリー名ではなくカテゴリー ID を指定する必要があります。

注意: category パラメータはコンマ区切りの複数カテゴリー ID でもかまいません。これは、get_posts() 関数が 'category' パラメータを 'cat' として WP_Query に直接渡すからです。

注意: category_name パラメータは カテゴリ名では、この場合、文字列にする必要があります。


'orderby'
文字列) (オプション) 取得した投稿をソートする
初期値: 'date'
  • 'none' - 順序無し (Version 2.8 で利用可能)
  • 'ID' - 投稿 ID。パラメータ名は大文字
  • 'author' - 作成者
  • 'title' - タイトル
  • 'date' - 日付
  • 'modified' - 更新日
  • 'parent' - 親ページの ID
  • 'rand' - ランダム
  • 'comment_count' - コメント数 (Version 2.9 で利用可能)
  • 'menu_order' - ページ順序。固定ページ (ページ属性で指定する) やアタッチメント (メディア投稿ダイアログの数値) で使われるが、'menu_order' 値 (デフォルトは 0) を持つ任意の投稿タイプで使用可能。
  • 'meta_value' - クエリに 'meta_key=keyname' がある場合のみ有効。並べ替えはアルファベット順なので語句の場合は良いが、数字の場合は予想外の結果 (たとえば 1, 3, 4, 6, 34, 56 を期待するかもしれないが、1, 3, 34, 4, 56, 6 のようになる) になることがある。
  • 'meta_value_num' - メタフィールドの値。(Version 2.8 で利用可能)。クエリに 'meta_key=keyname' がある場合のみ有効。'meta_value' の項に記載の数字での並べ替えを行う。
  • 'post__in' - 'include' パラメータで渡したものと同じ順序に一致。
注: get_pages()'orderly' ではなく、'sort_column' を使用します。また get_pages()'post_' を前置します: 'author, date, modified, parent, title, excerpt, content'
'post_mime_type'
文字列 / 配列) (オプション) mime types の一覧またはコンマ区切り
初期値: なし

返り値

(配列) 
WP_Post オブジェクトのリスト。

get_pages() と異なり、get_posts() は適切なコンテキスト(管理者の場合、など)では private ページを返します。 (参考: Andreas Kirsch, WordPress Hacking II, January 24, 2009-- accessed 2012-11-09.)

用例

オフセットのあるリストの生成

フロントページで 1 件だけ表示してから、カテゴリーID が 1 の投稿へのリンクをそれに先行する 5 件分表示したい場合、下記のようにします。

<ul>
<?php


$args = array( 'posts_per_page' => 5, 'offset'=> 1, 'category' => 1 );

$myposts = get_posts( $args );
foreach ( $myposts as $post ) : setup_postdata( $post ); ?>
	<li>
		<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
	</li>
<?php endforeach; 
wp_reset_postdata();?>

</ul>

注: 2件以上の記事がないカテゴリで上記のクエリを使うと何も表示されません。

前後の投稿へのリンクがある投稿

前後の投稿へのリンクがある投稿を作成することができます。 下記のようにします。

<?php
$postlist = get_posts( 'sort_column=menu_order&sort_order=asc' );
$posts = array();
foreach ( $postlist as $post ) {
   $posts[] += $post->ID;
}

$current = array_search( get_the_ID(), $posts );
$prevID = $posts[$current-1];
$nextID = $posts[$current+1];
?>

<div class="navigation">
<?php if ( !empty( $prevID ) ): ?>
<div class="alignleft">
<a href="<?php echo get_permalink( $prevID ); ?>"
  title="<?php echo get_the_title( $prevID ); ?>">Previous</a>
</div>
<?php endif;
if ( !empty( $nextID ) ): ?>
<div class="alignright">
<a href="<?php echo get_permalink( $nextID ); ?>"
 title="<?php echo get_the_title( $nextID ); ?>">Next</a>
</div>
<?php endif; ?>
</div><!-- .navigation -->

オフセットのリセット

ループの後で、foreach 実行前の記事が必要な場合は、以下のように記述します。

<ul>
<?php
global $post;
$args = array( 'posts_per_page' => 5, 'offset'=> 1, 'category' => 1 );
$myposts = get_posts( $args );
foreach ( $myposts as $post ) : 
  setup_postdata( $post ); ?>
	<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
<?php endforeach;
wp_reset_postdata(); ?>
</ul>

全記事データにアクセスする

get_posts では、デフォルトの状態では利用できない記事データが一部あります。the_content() のコンテンツや ID などです。内部関数 setup_postdata() に、引数として $post 配列を与えることで解決できます。

<?php
$args = array( 'posts_per_page' => 3 );
$lastposts = get_posts( $args );
foreach ( $lastposts as $post ) :
  setup_postdata( $post ); ?>
	<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
	<?php the_content(); ?>
<?php endforeach; 
wp_reset_postdata(); ?>

setup_postdata() を呼び出さずに投稿 ID またはコンテンツにアクセスしたり、(the posts table に蓄積されている)任意の投稿データにアクセスするには、$post->COLUMN を使用できます。ここで COLUMN はデータのテーブルカラム名です。したがって、$post->ID は ID、 $post->post_content はコンテンツ、といった具合です。データを表示/出力するには、以下のように PHP echo コマンドを使用します。

<?php echo $post->ID; ?>

最近の投稿をタイトル順に並べる

アルファベット順に昇順で最近の 10 件を表示するには、以下のコードで投稿日、タイトル、抜粋を表示します。

<?php
$args = array( 'posts_per_page' => 10, 'order'=> 'ASC', 'orderby' => 'title' );
$postslist = get_posts( $args );
foreach ( $postslist as $post ) :
  setup_postdata( $post ); ?> 
	<div>
		<?php the_date(); ?>
		<br />
		<?php the_title(); ?>   
		<?php the_excerpt(); ?>
	</div>
<?php
endforeach; 
wp_reset_postdata();
?>

ランダムに表示する

orderby パラメータに rand を指定して MySQL RAND() 関数を使用して最近の 5 件をランダムに表示します。

<ul>
<?php
$args = array( 'posts_per_page' => 5, 'orderby' => 'rand' );
$rand_posts = get_posts( $args );
foreach ( $rand_posts as $post ) : 
  setup_postdata( $post ); ?>
	<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
<?php endforeach; 
wp_reset_postdata(); ?>
</ul>

添付ファイルを全て表示する

テンプレートの Loops 外に記述します。

<?php
$args = array( 'post_type' => 'attachment', 'posts_per_page' => -1, 'post_status' => 'any', 'post_parent' => null ); 
$attachments = get_posts( $args );
if ( $attachments ) {
	foreach ( $attachments as $post ) {
		setup_postdata( $post );
		the_title();
		the_attachment_link( $post->ID, false );
		the_excerpt();
	}
	wp_reset_postdata();
}
?>

現在の記事の添付ファイルを表示する

ループ内($post->ID が利用できるところ)に記述します。

<?php
$args = array( 'post_type' => 'attachment', 'posts_per_page' => -1, 'post_status' =>'any', 'post_parent' => $post->ID ); 
$attachments = get_posts( $args );
if ( $attachments ) {
	foreach ( $attachments as $attachment ) {
		echo apply_filters( 'the_title' , $attachment->post_title );
		the_attachment_link( $attachment->ID , false );
	}
}
?>

スラッグをもとに投稿を取得する

投稿スラッグをもとに投稿 ID を取得できます。

<?php
$the_slug = 'my-slug';
$args=array(
	'name'           => $the_slug,
	'post_type'      => 'post',
	'post_status'    => 'publish',
	'posts_per_page' => 1
);
$my_posts = get_posts( $args );
if( $my_posts ) {
	echo 'ID on the first post found ' . $my_posts[0]->ID;
}
?>

タクソノミーパラメータ

注: タクソノミー名をキーとする方法(以下の1番目の例)は、バージョン 3.1 以降は非推奨になりました。代わりに 'tax_query' を使用してください(2番目の例)。

特定のタクソノミーと関連する投稿を表示します。カスタム投稿タイプに対して登録されたタクソノミーを指定した場合、'category' ではなく代わりに '{custom_taxonomy_name}'(カスタムタクソノミー名)を使って下さい。例えば、"genre"(ジャンル)というタクソノミーがあり、"jazz" というジャンルに分類された投稿のみを表示したい時は以下のコードを使います。

<?php
$args = array(
	 'posts_per_page' => 8,
	 'orderby' => 'rand',
	 'post_type' => 'albums',
	 'genre' => 'jazz',  // 非推奨のため 'tax_query' を使ってください
	 'post_status' => 'publish'
);
$show_albums = get_posts( $args );
?>

以下の例では、"tax_query" を使い、"genre" カスタムタクソノミーの "jazz" に分類された投稿のみを取得します。

$args = array(
	'tax_query' => array(
		array(
			'taxonomy' => 'genre',
			'field' => 'slug',
			'terms' => 'jazz'
		)
	)
);
$postslist = get_posts( $args );

他の例については、WP_Query ドキュメンテーションの タクソノミーパラメータのセクションをご覧ください。

カスタムフィールドパラメータ

あるカスタムフィールドと関連する投稿のみを表示します。以下の例では、"meta_query" を使い、"product" 投稿タイプで "featured" というメタキーが "yes" という値を持つ投稿を取得します。:

$args = array(
	'post_type' => 'product',
	'meta_query' => array(
		array(
			'key' => 'featured',
			'value' => 'yes',
		)
	)
 );
$postslist = get_posts( $args );

他の例については、WP_Query ドキュメンテーションの カスタムフィールドパラメータのセクションをご覧ください。

変更履歴

ソースファイル

get_posts()wp-includes/post.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 値を変更する


関数リファレンステンプレートタグ目次もご覧ください。
[[zh-cn:模版标签/get_posts}]]

最新英語版: WordPress Codex » Template Tags/get posts最新版との差分