トップの記事の一覧から、お知らせやコラムのような特定のカテゴリーだけを外したい。一覧に出す記事の数を、トップとカテゴリーのページで変えたい。こうしたときに使うのが、pre_get_posts というフックです。
テンプレートの中で query_posts() を使っても見た目は変わりますが、ページ送りがおかしくなります。ここでは、pre_get_posts の書き方と、管理画面やサブのループまで変えてしまわない書き方を、実際に数えた数字と一緒に書きます。
コードは、このサイトの作業環境(WordPress 7.1.3・PHP 8.3)で実際に動かして確認しました。記事の数やページの数は、このサイトの記事で数えたものです。
pre_get_posts とは
WordPress は、ページを開くと、URL から「どの記事を何本出すか」を決めて、データベースから記事を読みます。このときのクエリを「メインのクエリ」と言います。
pre_get_posts は、メインのクエリがデータベースを読む直前に呼ばれるフックです。ここで条件を足すと、WordPress は変えたあとの条件で記事を読み、ページ送りの数も 404 の判定も、その条件で計算します。
コードは、テーマ(子テーマがあれば子テーマ)の functions.php に書きます。テンプレートのファイルには書きません。
いちばん大事なこと:is_admin() と is_main_query()
pre_get_posts は、メインのクエリだけでなく、すべての WP_Query で呼ばれます。管理画面の投稿の一覧、ウィジェット、関連記事、get_posts() で読む一覧も対象です。
そのため、最初に次の 2 つで「それ以外」を外します。これを忘れるのが、いちばんのつまずき所です。
function my_pre_get_posts( $query ) {
// 管理画面と、メインでないクエリは変えない
if ( is_admin() || ! $query->is_main_query() ) {
return;
}
// ここに、変えたい条件を書く
}
add_action( 'pre_get_posts', 'my_pre_get_posts' );
| 書き方 | 役目 |
|---|---|
is_admin() |
管理画面(投稿の一覧など)のときは何もしない |
$query->is_main_query() |
メインのクエリのときだけ変える。ウィジェットや関連記事のクエリは変えない |
$query->set( 名前, 値 ) |
クエリの条件を変える |
ページの種類を見るときも、is_home() ではなく $query->is_home() のように、渡された $query のほうで見ます。is_home() は、いつもメインのクエリのことを答えるので、ほかのクエリのときにまちがえます。
確認した:2 行がないとどうなるか
作業環境で、2 行のチェックを書かずに「コラム」のカテゴリーを外すコードを置いて、前と後を比べました。サブのループは、フッターで get_posts() と new WP_Query() を呼んで試しています。
function my_exclude_column_bad( $query ) {
$query->set( 'category__not_in', array( 200 ) ); // 200 はコラムの ID
}
add_action( 'pre_get_posts', 'my_exclude_column_bad' );
| 見た所 | 何もしないとき | チェックのない形 | チェックのある形 |
|---|---|---|---|
| トップの一覧(全部の記事の数) | 189 | 179 | 179 |
| 管理画面の投稿の一覧(公開の記事の数) | 189 | 179(コラムが管理画面から見えない) | 189 |
「コラムの新着 3 本」の get_posts() |
3 本 | 0 本 | 3 本 |
「新着 5 本」の new WP_Query() |
コラム 4 本を含む 5 本 | コラムを含まない 5 本 | コラム 4 本を含む 5 本 |
チェックのない形では、トップの一覧だけでなく、管理画面の投稿の一覧からもコラムが消えました。「コラムの新着」を出すつもりのサブのループは、1 本も出なくなりました。
get_posts() は、ふだんはフィルターを通さない(suppress_filters が true)関数です。それでも pre_get_posts は動くので、2 行のチェックが要ります。
特定のカテゴリーを外す
トップの一覧から、カテゴリーを外す形です。カテゴリーの ID は、管理画面の「投稿」→「カテゴリー」で、カテゴリーの編集画面を開いたときの URL の tag_ID= の数で分かります。
function my_exclude_category( $query ) {
if ( is_admin() || ! $query->is_main_query() ) {
return;
}
if ( $query->is_home() ) {
$query->set( 'category__not_in', array( 200 ) ); // 外すカテゴリーの ID
}
}
add_action( 'pre_get_posts', 'my_exclude_category' );
外したいカテゴリーが 2 つ以上なら、array( 200, 201 ) のように並べます。記事が 2 つのカテゴリーに入っていて、その片方が外すカテゴリーなら、その記事は一覧に出ません。
category__not_in と cat に負の数の違い
カテゴリーを外す書き方は、もう 1 つあります。cat に、ID の前に「-」を付けた値を指定する形です。
$query->set( 'cat', '-200' );
2 つの違いは、子のカテゴリーまで外すかどうかです。WordPress 7.1.3 の wp-includes/class-wp-query.php では、cat の負の数は子のカテゴリーを含めて外し(include_children が true)、category__not_in は書いた ID だけを外します(false)。
作業環境で、子のカテゴリー(「WordPress 6.4.3」など)を持つ親のカテゴリー「WordPress」で試しました。記事はどれも子のカテゴリーに入っていて、親のカテゴリーに直接入っている記事はありません。
| 書き方 | トップの一覧の記事の数 | ページ送り |
|---|---|---|
| 何もしない | 189 | 19 ページ |
category__not_in に親の ID |
189(1 本も外れない) | 19 ページ |
cat に親の ID の負の数 |
19(子のカテゴリーの記事も外れる) | 2 ページ |
親のカテゴリーで子もまとめて外したいときは cat の負の数、その ID だけを外したいときは category__not_in を使います。思ったより記事が減った・減らないときは、この違いを疑ってください。
表示する数を変える
一覧に出す記事の数は、ふだんは管理画面の「設定」→「表示設定」の「1 ページに表示する最大投稿数」で決まります。ページの種類ごとに変えたいときは、posts_per_page を変えます。
function my_posts_per_page( $query ) {
if ( is_admin() || ! $query->is_main_query() ) {
return;
}
if ( $query->is_home() || $query->is_archive() ) {
$query->set( 'posts_per_page', 5 );
}
}
add_action( 'pre_get_posts', 'my_posts_per_page' );
作業環境(表示設定は 10 本)で、トップの一覧が 5 本・38 ページになり、2 ページ目には 6 本目からの 5 本が出ました。カテゴリーのページも 5 本ずつになりました。
トップだけ変える
トップの一覧だけ、コラムを外して 6 本にする例です。$query->is_home() でないときは、すぐに戻ります。
function my_home_query( $query ) {
if ( is_admin() || ! $query->is_main_query() ) {
return;
}
if ( ! $query->is_home() ) {
return;
}
$query->set( 'category__not_in', array( 200 ) );
$query->set( 'posts_per_page', 6 );
}
add_action( 'pre_get_posts', 'my_home_query' );
| ページ | 記事の数 | 1 ページの本数 | ページ送り |
|---|---|---|---|
| トップ | 179(コラムの 10 本が外れた) | 6 | 30 ページ(31 ページ目は 404) |
| カテゴリー「機能追加」 | 60(変わらない) | 10 | 6 ページ |
| カテゴリー「コラム」 | 10(変わらない) | 10 | 1 ページ |
is_home() は「投稿の一覧のページ」のときに true です。表示設定でトップを固定ページにしているときは、トップではなく「投稿ページ」に決めたページで true になります。違いは「is_home() と is_front_page() の違い」にまとめています。
カテゴリーのページだけ変える
決まったカテゴリーのページだけ、1 ページに 20 本出す例です。is_category() には、ID・スラッグ・名前を渡せます。
function my_category_query( $query ) {
if ( is_admin() || ! $query->is_main_query() ) {
return;
}
if ( $query->is_category( 'custom' ) ) { // カテゴリーのスラッグ
$query->set( 'posts_per_page', 20 );
}
}
add_action( 'pre_get_posts', 'my_category_query' );
| ページ | 1 ページの本数 | ページ送り |
|---|---|---|
| カテゴリー「機能追加」(60 本) | 20 | 3 ページ(4 ページ目は 404) |
| カテゴリー「コラム」 | 10(変わらない) | 1 ページ |
| トップ | 10(変わらない) | 19 ページ |
すべてのカテゴリーのページを変えたいときは、$query->is_category() のように何も渡さずに書きます。カテゴリーの一覧(カテゴリーそのもの)の並び順を変えたいときは、「カテゴリーの並び順を変える」を見てください。
query_posts() を使わない理由
テンプレートの中で query_posts() を呼んでも、一覧の内容は変わります。ただし、これはメインのクエリを変えるのではなく、メインのクエリが動いたあとに、別のクエリで置き換えるものです。
query_posts( 'posts_per_page=5&cat=-200' );
if ( have_posts() ) :
while ( have_posts() ) : the_post();
// 一覧の 1 本
endwhile;
endif;
作業環境で、テンプレートを読む前(template_redirect)に同じ query_posts() を呼んで、ページ送りを見ました。比べるために、同じ条件を pre_get_posts で書いた形も試しています。
| 見た所 | query_posts() | pre_get_posts(同じ条件) |
|---|---|---|
| 記事の一覧を読むクエリ | 2 回(もとのクエリ+置き換えたクエリ) | 1 回 |
| 1 ページ目の内容 | コラムを外した 5 本 | 同じ 5 本 |
| 2 ページ目(/page/2)の内容 | 1 ページ目と同じ 5 本 | 6 本目からの 5 本 |
| どこまでページがあるか | もとのクエリ(10 本ずつ・19 ページ)で決まる。置き換えたクエリは 36 ページ分あるのに、20 ページ目から先(30 ページ目なども)は 404 | 変えたあとの条件で決まる(36 ページ・37 ページ目は 404) |
2 ページ目が 1 ページ目と同じになったのは、置き換えたクエリにページの番号(paged)を渡していないためです。番号を渡しても、URL が 404 になるかどうかは、もとのクエリのページの数で決まったままです。
WordPress の公式の資料(developer.wordpress.org)の query_posts() のページにも、プラグインやテーマで使わないように書かれています。一覧の条件を変えるのは pre_get_posts、別の一覧を足すのは new WP_Query() と使い分けます。
気をつける所
外した記事は、ページ送りの数に入らない
pre_get_posts で外した記事は、記事の数にもページ送りにも入りません。作業環境では、コラムを外したトップは 179 本・18 ページになり、19 ページ目は 404 になりました。
サイドバーの件数とずれる
カテゴリーの一覧や、年ごとのアーカイブの一覧の「(10)」のような件数は、pre_get_posts では変わりません。これらは WP_Query を通らずに数えているためです。
| 見た所(コラムをトップから外したとき) | 数 |
|---|---|
| トップの一覧の記事の数 | 179 |
wp_list_categories() のコラムの件数 |
10(変わらない) |
wp_get_archives() の年ごとの件数の合計 |
189(変わらない) |
トップから外しただけなら、カテゴリーのページや年のアーカイブには記事が出るので、件数のとおりです。アーカイブのページでも外したときは、件数とページの本数が合わなくなるので、件数を出さないか、そのカテゴリーをウィジェットから外します。
テーマやプラグインの pre_get_posts とぶつかる
テーマやプラグインにも、pre_get_posts を使っているものがあります。このサイトのテーマにも、お知らせのアーカイブの本数を変えるものなどがありました。
思ったとおりに変わらないときは、テーマの中を探して、同じページで同じ条件を変えていないかを見ます。あとから呼ばれたほうが勝つので、add_action( 'pre_get_posts', 'my_pre_get_posts', 20 ); のように順番の数を大きくすると、あとで動かせます。
grep -rn "pre_get_posts" --include=*.php wp-content/themes wp-content/plugins
一覧ではなく、検索のフォームでカテゴリーを絞りたいときは「カテゴリで絞り込める検索フォーム」を見てください。こちらは、検索のクエリにカテゴリーの条件を足す形です。
まとめ
一覧の条件は query_posts() ではなく pre_get_posts で変え、最初に is_admin() と is_main_query() で管理画面とサブのループを外しておきます。

