WP_Query パラメーターcategory_name

category_name は、通常投稿をカテゴリーで絞り込みたい時に使える分かりやすい引数です。たとえば「ニュース」カテゴリーの記事だけを一覧にしたい場合、カテゴリーのスラッグが news なら category_name => ‘news’ のように書きます。

初心者がつまずきやすいのは、category_name という名前から、カテゴリーの表示名を入れると思ってしまう点です。実際に指定するのは、カテゴリー名ではなくスラッグです。

category_name は何を指定する引数か

category_name は、通常のカテゴリーに属する投稿を取得するための WP_Query 引数です。値には、カテゴリースラッグを指定します。

カテゴリーの表示名が「ニュース」でも、スラッグが news なら、category_name に入れるのは news です。日本語の表示名ではなく、URLなどにも使われるスラッグを指定する点を押さえます。

ここで大事なのは、category_name は通常のカテゴリーを対象にする短い書き方だということです。カスタムタクソノミーを絞り込みたい場合は、category_name ではなく tax_query を使う場面が多くなります。

また、カテゴリーIDで指定したい場合も、category_name ではありません。IDで指定するなら、cat や category__in など別の引数を確認します。

category_name、cat、tax_query の違い

category_name と混同しやすいのが cat と tax_query です。どれもカテゴリーや分類に関係しますが、指定する値や向いている場面が違います。

category_name はカテゴリースラッグで指定します。cat はカテゴリーIDで指定します。tax_query はカテゴリーだけでなく、タグやカスタムタクソノミーも含めた分類条件を配列で指定します。

単純に「このカテゴリーの投稿を出したい」だけなら、category_name は読みやすい選択肢です。一方で、カスタムタクソノミーや複数分類の条件を扱うなら、tax_query を検討します。

初心者向けには、まず category_name で1つのカテゴリーを絞り込むところから始めると理解しやすくなります。その後、条件が複雑になったら tax_query に進みます。

Builder での扱い

WP Query Builder では、category_name は通常カテゴリーをスラッグで絞り込む基本項目として扱う想定です。初心者向けには、「カテゴリーのスラッグ」と表示したほうが誤解が少なくなります。

画面上ではカテゴリー名を選ばせ、内部的には対応するスラッグを category_name に入れる形にすると分かりやすくなります。ユーザーにスラッグを直接入力させる場合は、表示名ではないことを明記します。

複雑なカテゴリー条件や、タグ、カスタムタクソノミーを含める場合は、Builder 側で tax_query に切り替える導線があると安全です。category_name はシンプルなカテゴリー絞り込み用として扱うと整理しやすくなります。

使いどころ・避けどころと実践確認

組み込みカテゴリーを1つのスラッグで手早く絞る、単純な投稿一覧に使います。

複数カテゴリーのAND・OR、除外、またはカスタムタクソノミーを扱う場合は tax_query を選びます。

管理画面の表示名ではなくスラッグを渡すため、名称変更後も実際のスラッグが要件と一致するか確認します。

category_name が向くのは単一スラッグで済む場合までで、条件が二つになった時点が tax_query へ移る目安です。

対象と非対象のカテゴリーへテスト投稿を分け、取得できた投稿IDと各投稿のタームを照合して、単一条件だけで成立するか確かめます。

実践記事で確認tax_queryでカテゴリー・タグ・タクソノミーを絞り込む

条件が複数へ広がる場合は、tax_query の条件と relation へ置き換える判断を実装例で確認できます。

記事を読む →

WordPressの仕様で確認するポイント

公式資料では、WP_Query の category_name は Category Parameters の中で確認できます。カテゴリーIDを使う引数や、複数カテゴリーを扱う引数も同じまとまりで確認できます。

複雑な分類条件を扱う場合は、同じ WP_Query の中にある Taxonomy Parameters も合わせて確認します。tax_query を使うと、カテゴリー以外のタクソノミーも含めて条件を整理できます。

category_name は、カテゴリースラッグで通常投稿を絞り込むための引数です。カテゴリー名ではなくスラッグを指定する点をまず確認します。

迷った時は、1つのカテゴリーだけを指定した最小構成で確認します。取得できることを確認してから、複数カテゴリー、ページネーション、並び順などを追加すると、原因を切り分けやすくなります。