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

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(en:Template Tags/get_posts 19:48, 15 May 2007 SebastienCastiel の版)
 
(タクソノミーパラメータ: 非推奨の書式を明示。)
 
(8人の利用者による、間の23版が非表示)
1行目: 1行目:
== Description ==
+
== 説明 ==
  
This is a simple tag for creating multiple loops.
+
<tt>get_posts</tt> の最も適切な使い方は、パラメータに基づいて投稿データの配列を作成することです。最近の投稿あるいはパラメータに一致した投稿を取得します。[[ループ#複数のループ|複数のループ]]を作成するのに <tt>get_posts</tt> を使用する事もできます。ただしこの場合は <tt>new WP_Query</tt> を使用して <tt>[[Class_Reference/WP_Query|WP_Query]]</tt> を直接参照するほうが好ましいでしょう。
  
== Usage ==
+
<tt>[[関数リファレンス/get_pages|get_pages]]</tt> とパラメータが似ていますが実装方法はかなり異なっており、適切に使う必要があります。<tt>get_posts</tt> は <tt>[[Class_Reference/WP_Query|WP_Query]]</tt> を使用していますが、<tt>get_pages</tt> はデータベースに直接クエリを投げます。それぞれ実装の差異を反映したパラメータになっています。
  
%%% <?php get_posts('arguments'); ?> %%%
+
<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> オブジェクトを参照するため、メインループに影響を与えません。
  
== Examples ==
+
メインクエリが実行される前に変更したい場合は、<tt>[[プラグイン API/アクションフック一覧/pre get posts|pre_get_posts]]</tt> フックを使用することができます。ページの中で、いくつかのパラメータで指定した投稿データを呼び出したい場合は、<tt>get_posts</tt> が最適でしょう。
  
===Generate list===
 
  
If you had your blog configured to show just one post on the front page, but you also wanted to show links and excerpts to the previous five posts with the category ID of 1, you could use code like this:
+
===デフォルトの使い方===
  
<nowiki> <ul>
+
<pre>
<?php
+
<?php $args = array(
global $post;
+
'posts_per_page'  => 5,
$myposts = get_posts('numberposts=5&offset=1&category=1');
+
'offset'          => 0,
foreach($myposts as $post) :
+
'category'        => '',
?>
+
'category_name'    => '',
    <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a> --- <?php the_excerpt(); ?></li>
+
'orderby'          => 'date',
<?php endforeach; ?>
+
'order'            => 'DESC',
</ul></nowiki>
+
'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.)
 +
 
 +
== 用例 ==
 +
 
 +
=== オフセットのあるリストの生成 ===
  
'''Note:''' The above query should only be made on a category that has more than one post.
+
フロントページで 1 件だけ表示してから、カテゴリーID が 1 の投稿へのリンクをそれに先行する 5 件分表示したい場合、下記のようにします。
  
=== Generate another list ===
 
In the event you want to show ten posts sorted alphabetically in ascending order on your web page, you could do the following to grab the posted date, title and excerpt:
 
 
<pre>
 
<pre>
 +
<ul>
 
<?php
 
<?php
$postslist = get_posts('numberposts=10&order=ASC&orderby=post_title');
+
 
foreach ($postslist as $post) : start_wp(); ?>
+
 
<?php the_date(); echo "<br />"; ?>
+
$args = array( 'posts_per_page' => 5, 'offset'=> 1, 'category' => 1 );
<?php the_title(); ?>  
+
 
<?php the_excerpt(); ?>  
+
$myposts = get_posts( $args );
<?php endforeach; ?>
+
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>
 
</pre>
  
===Access all post data===
+
'''注:''' ''2件以上の記事がないカテゴリで上記のクエリを使うと何も表示されません。''
 +
 
 +
=== 前後の投稿へのリンクがある投稿 ===
 +
 
 +
前後の投稿へのリンクがある投稿を作成することができます。
 +
下記のようにします。
  
For various reasons some data is not available to get_posts by default, such as post content through [[Template Tags/the_content|the_content()]], or the ID. This is solved by calling an internal function, setup_postdata(), with the $post array:
 
 
<pre><?php
 
<pre><?php
$lastposts = get_posts('numberposts=3');
+
$postlist = get_posts( 'sort_column=menu_order&amp;sort_order=asc' );
 +
$posts = array();
 +
foreach ( $postlist as $post ) {
 +
  $posts[] += $post->ID;
 +
}
  
foreach($lastposts as $post) :
+
$current = array_search( get_the_ID(), $posts );
    setup_postdata($post);
+
$prevID = $posts[$current-1];
    ?>
+
$nextID = $posts[$current+1];
    <a href="<?php the_permalink(); ?>" id="post-<?php the_ID(); ?>"><?php the_title(); ?></a>
+
?>
    <?php the_content(); ?>
+
 
<?php endforeach; ?>
+
<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 --></pre>
 +
 
 +
==== オフセットのリセット ====
 +
 
 +
ループの後で、foreach 実行前の記事が必要な場合は、以下のように記述します。
 +
 
 +
<pre>
 +
<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>
 
</pre>
 
</pre>
  
Another way to access the ID, without having to call setup_postdata, is to just do "$post->ID", or "$post->post_data" for the content. This lets you avoid calling internal functions.
+
=== 全記事データにアクセスする ===
  
== Parameters ==
+
get_posts では、デフォルトの状態では利用できない記事データが一部あります。<tt>[[テンプレートタグ/the_content|the_content()]]</tt> のコンテンツや ID などです。内部関数 <tt>setup_postdata()</tt> に、引数として $post 配列を与えることで解決できます。
  
; numberposts : (''integer'') Number of posts to return. Defaults to <tt>5</tt>.
+
<pre>
; offset : (''integer'') Offset from latest post. Defaults to <tt>0</tt>.
+
<?php
; category : (''integer'') Only show posts from this category ID. There is no default.
+
$args = array( 'posts_per_page' => 3 );
; orderby : ("string") Sort Posts by one of various values, including:
+
$lastposts = get_posts( $args );
:* <tt>'post_title'</tt> - Sort alphabetically by Page/post title (Default).
+
foreach ( $lastposts as $post ) :
:* <tt>'post_date'</tt> - Sort by creation time.
+
  setup_postdata( $post ); ?>
:* <tt>'post_modified'</tt> - Sort by time last modified.
+
<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
:* <tt>'ID'</tt> - Sort by numeric Post ID.
+
<?php the_content(); ?>
:* <tt>'post_author'</tt> - Sort by author numeric ID.
+
<?php endforeach;
:* <tt>'post_name'</tt> - Sort alphabetically by Post slug.
+
wp_reset_postdata(); ?>
:*'''Note:''' The ''orderby'' value can be the name of any field in the [[Database Description|wp_post table]].
+
</pre>
; order : (''string'') Sort order for options. Valid values:
+
:* <tt>'ASC'</tt> - Sort from lowest to highest (Default).
+
:* <tt>'DESC'</tt> - Sort from highest to lowest.
+
  
== Related ==
+
<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 コマンドを使用します。
  
{{Tag General Tags}}
+
<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();
 +
?>
 +
</pre>
 +
 
 +
=== ランダムに表示する ===
 +
 
 +
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>
 +
</pre>
 +
 
 +
=== 添付ファイルを全て表示する ===
 +
 
 +
テンプレートの [[The_Loop|Loops]] 外に記述します。
 +
 
 +
<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>
 +
<?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 );
 +
}
 +
}
 +
?>
 +
</pre>
 +
 
 +
=== スラッグをもとに投稿を取得する ===
 +
 
 +
投稿スラッグをもとに投稿 ID を取得できます。
 +
 
 +
<pre>
 +
<?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>
 +
 
 +
=== タクソノミーパラメータ ===
 +
 
 +
<p class="information">'''注:''' タクソノミー名をキーとする方法(以下の1番目の例)は、バージョン 3.1 以降は'''非推奨'''になりました。代わりに <code>'tax_query'</code> を使用してください(2番目の例)。</p>
 +
 
 +
特定のタクソノミーと関連する投稿を表示します。カスタム投稿タイプに対して登録されたタクソノミーを指定した場合、'category' ではなく代わりに '{custom_taxonomy_name}'(カスタムタクソノミー名)を使って下さい。例えば、"genre"(ジャンル)というタクソノミーがあり、"jazz" というジャンルに分類された投稿のみを表示したい時は以下のコードを使います。
 +
 
 +
<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>
 +
 
 +
以下の例では、"tax_query" を使い、"genre" カスタムタクソノミーの "jazz" に分類された投稿のみを取得します。
 +
 
 +
<pre>
 +
$args = array(
 +
'tax_query' => array(
 +
array(
 +
'taxonomy' => 'genre',
 +
'field' => 'slug',
 +
'terms' => 'jazz'
 +
)
 +
)
 +
);
 +
$postslist = get_posts( $args );
 +
</pre>
 +
 
 +
他の例については、<tt>WP_Query</tt> ドキュメンテーションの [[関数リファレンス/WP_Query#Taxonomy_Parameters|タクソノミーパラメータのセクション]]をご覧ください。
 +
 
 +
=== カスタムフィールドパラメータ ===
 +
 
 +
あるカスタムフィールドと関連する投稿のみを表示します。以下の例では、"meta_query" を使い、"product" 投稿タイプで "featured" というメタキーが "yes" という値を持つ投稿を取得します。:
 +
 
 +
<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}} にあります。
 +
 
 +
== 関連 ==
 +
 
 +
 
 +
{{Query Tags}}
  
 
{{Tag Footer}}
 
{{Tag Footer}}
 +
{{DEFAULTSORT:Get_posts}}
 +
[[Category:テンプレートタグ]]
 +
 +
[[en:Template_Tags/get_posts]]
 +
[[es:Etiquetas_de_plantilla/get_posts]]
 +
[[zh-cn:模版标签/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最新版との差分