WordPress get_template_part() の第3引数とパーツ側の $args

  • WordPress
  • PHP

テーマで共通ブロックを get_template_part() に切り出すとき、第3引数で値を渡す書き方がすっきりします。ここでは WordPress 5.5.0 以降の仕様を前提に、パーツ側の $args など周辺をまとめます。


呼び出しの形(例)

<?php get_template_part('parts/p-reserve', null, ['variant' => 'top']); ?>
  • 第1引数 … テーマ内のパス(拡張子なし)。parts/p-reserve.php を読むイメージ。
  • 第2引数null なら接尾辞なし。'sidebar' のように付けると parts/p-reserve-sidebar.php を優先して探す、などのルールがあります。
  • 第3引数 … パーツへ渡す 配列。公式の想定も 配列 です。

パーツ側で受け取る変数名は $args

第3引数で渡した配列は、コアの load_template()$args という引数名で受け取り、そのスコープでテンプレートが require されるため、パーツ内では常に $args という名前で参照できます。呼び出し側で $args = ... と書いているわけではありません。


$args の中に「何を入れるか」

コアがキーを決めているわけではなく、テーマ(そのパーツ)の仕様で自由です。実務では次のような値がよくあります。

  • バリエーション用の文字列(例: 'variant' => 'top'
  • 表示のオンオフ(真偽値)
  • ID やスラッグ
  • すでに親テンプレートで取ったオブジェクトや配列(パーツ内での二重取得を避ける)

欠けうるキーには、パーツ側で isset() やデフォルト値を置くと安全です。

<?php
$variant = isset($args['variant']) ? $args['variant'] : 'default';

文字列だけを第3引数に直接渡すことは、型・ドキュメント的に想定外です。意味のあるキーを1つ決めて、連想配列の値として文字列を渡す形にしてください。


数値だけの配列(キーなし)も渡せる

<?php get_template_part('parts/p-reserve', null, ['top']); ?>

この場合パーツ内の $args['top'](実質 $args[0] === 'top')です。可能ではありますが、順番に依存するので 連想配列の方が読みやすく保守しやすいことが多いです。


よくある誤解: $reserveArgs['variant'] だけ書いてよい?

いいえ。 コアが自動で用意するのは $args だけです。$reserve_args のような名前で読みたいなら、上記のように $reserve_args = $args を自分で書く必要があります。

また、呼び出しが ['top'] のときは $args['variant'] は存在しません(キーは 0)。呼び出しとパーツの取り方を揃えてください。


補足: 古い set_query_var() との比較

set_query_var() でクエリ変数に載せてから get_template_part() する方法もありますが、名前の衝突や流れが追いにくくなることがあります。第3引数は、その読み込みに閉じたデータとして渡せるので、再利用や意図の明示には向きやすいです。


参考(コア)

バージョン要件は環境の WordPress に合わせて確認してください。