WP_Tax_Query クラスの使い方｜説明・引数・注意点

説明

基本構文

tax_query => array( array( 'taxonomy' => '...', 'field' => '...', 'terms' => ... ) )

引数

• taxonomy：タクソノミー名
• field：term_id / slug / name
• terms：タームの値（配列可）
• operator：IN / NOT IN / AND
• include_children：子タームを含めるか

戻り値

WP_Query の引数として使います。

使い方（サンプル）

$q = new WP_Query( array(
	'post_type' => 'post',
	'tax_query' => array(
		array(
			'taxonomy' => 'category',
			'field'    => 'slug',
			'terms'    => 'news',
		),
	),
) );

注意点

• field の指定を間違えると、結果が空になります。
• 子タームも含まれるのが既定です。除外するときは include_children を false にします。

実務での使いどころ

• WP_Query の tax_query に渡す条件（タームでの絞り込み）を、理解するとき。
• 複数のタクソノミーを、組み合わせて、絞り込むとき。

よくあるミスと対処

• field の指定（term_id・slug・name）と、terms の値の種類が、一致していない。
• 階層ありのタクソノミーで、子ターム（include_children）が、既定で含まれることを、知らない。
• relation を指定せず、条件が、すべて AND になる。

NG例

'tax_query' => array(
	array( 'taxonomy' => 'news_cat', 'terms' => 'important' ), // field の既定は term_id。スラッグでは、一致しない
),

OK例

'tax_query' => array(
	array(
		'taxonomy' => 'news_cat',
		'field'    => 'slug',
		'terms'    => 'important',
	),
),

使い分け早見表

関連項目

WP_Query、WP_Meta_Query

公式リファレンス：WP_Tax_Query | WordPress Developer Resources