PARAMETER REFERENCE

基本・検索・並び順

何を何件、どの順番で取るか。クエリの骨組みを先に決めます。

このページで確認できること

迷っている条件に近い項目から確認し、必要な値と注意点へ進んでください。

取得する投稿タイプと公開状態を決めたい
検索対象をtitle・excerpt・contentへ限定したい
ページ送りを保ったまま件数と順番を整えたい

値・選択肢・前提

パラメーター名だけでなく、何を決める値か、どの選択肢が使えるかを同時に確認します。

パラメーター役割主な選択肢・注意

post_type取得する投稿タイプ

post / page / any / custom slug（複数可）tax_queryを使うと未指定時の既定値がanyになる場合があります。意図した投稿タイプは明示する方が読み返しやすくなります。

post_status公開状態で絞る

publish / pending / draft / future / private / inherit / any公開画面は通常publishです。attachmentではinheritが候補になり、privateやdraftは権限と表示場所を確認して使います。

sキーワード検索

検索語。先頭にhyphenを付けた語は除外語として扱える空ならsearch_columnsも出力されません。relevance順を選ぶなら検索語が必要です。

search_columns検索対象列を限定

post_title / post_excerpt / post_contentBuilderではs入力後に選べます。WordPress 6.2以降を対象にし、選びすぎて通常検索と同じ状態に戻さないようにします。

posts_per_page1ページの取得件数

1以上、または全件取得の -1-1ではoffsetが無視されます。件数が増えるサイトで全件取得を常用しない方が安全です。

paged取得するページ番号

1以上の整数。通常はget_query_var()から渡す固定フロントページではpageとの違いがあります。BuilderはWP_Queryへ渡すpagedを生成します。

offset先頭から指定件数を飛ばす

0以上の整数pagedと併用すると通常のページ計算を崩します。先頭だけ除外したいページングは別の設計を検討します。

order昇順・降順

ASC / DESC / defaultorderbyがpost__inなど指定配列順を保つ値の場合、orderを変えてもその並びは反転しません。

orderby並び替えの基準

date / modified / title / menu_order / comment_count / rand / relevance / post__in / post_name__in / post_parent__in / meta_value / meta_value_num指定配列順には対応する__in、meta順にはkeyを持つmeta_query、relevanceにはsが必要です。数値を文字列順で並べないようmeta_value_numを使い分けます。

組み合わせる前に確認すること

実装で起きやすい衝突を、条件を増やす前に確認します。

pagedとoffsetを気軽に重ねない

offsetは通常のページ番号計算を上書きし、2ページ目以降の重複や欠落につながります。

orderbyには前提条件がある

post__in順・slug順・parent順・meta順・relevance順は、それぞれ元になる指定がないと意味を持ちません。Builderは不足をerrorで止めます。

まず最小の骨組みで確認する

post_type、post_status、posts_per_pageだけで件数を見てから、検索や並び順を一つずつ足すと切り分けが速くなります。

最小構成の実装例

そのまま貼るのではなく、対象post typeとtemplateの使い方に合わせて調整してください。

PHP基本

$args = [    'post_type'      => 'post',    'post_status'    => 'publish',    'posts_per_page' => 10,    'paged'          => max( 1, get_query_var( 'paged' ) ),    'orderby'        => 'date',    'order'          => 'DESC',];

$args = [
    'post_type'      => 'post',
    'post_status'    => 'publish',
    'posts_per_page' => 10,
    'paged'          => max( 1, get_query_var( 'paged' ) ),
    'orderby'        => 'date',
    'order'          => 'DESC',
];

仕様の最終確認対象WordPress versionのcode referenceも確認してください。WordPress Developer Resources

ほかの分類を見る

条件を組み合わせるときは、隣り合う分類の値や前提もあわせて確認すると設定漏れを防げます。

次に確認すること

「基本」の値と注意点を確認できたら、ほかの分類との関係を見直し、実装例かBuilderで実際のクエリに落とし込んでみてください。

このページを活用する

あとで見返す・共有する

お気に入りに保存できます。役に立ったポイントは、いいねや共有で教えてください。

任意のご支援 役に立ったときだけ、活動を応援できます OFUSEはサイト・記事制作に使います。支援の有無で、読める内容や使える機能は変わりません。

OFUSEで記事制作を応援