locate_template() の使い方｜説明・引数・注意点

説明

基本構文

locate_template( string|string[] $template_names, bool $load = false, bool $load_once = true, array $args = array() ): string

引数

• $template_names：テンプレートファイル名（複数可）
• $load：見つかったら読み込むか
• $load_once：require_once を使うか
• $args：引数

戻り値

見つかったファイルのパス。なければ空文字。

使い方（サンプル）

$path = locate_template( 'template-parts/card.php' );

注意点

• 親子テーマの両方から探します。

実務での使いどころ

• 子テーマ・親テーマの順に、テンプレートのファイルを探して、パスを取得するとき。
• 複数の、候補（優先順）から、最初に見つかるファイルを、使うとき。

よくあるミスと対処

• 見つからないとき、空文字が返る。確認せずに、使う。
• $load の既定は false（パスを返すだけ）。読み込むときは、true を指定する。
• 候補を、配列で、優先順に並べていない。

NG例

$file = locate_template( 'template-parts/card.php' );
require $file; // 見つからないと、空文字で、エラーになる

OK例

$file = locate_template( array( 'template-parts/card-news.php', 'template-parts/card.php' ) );
if ( $file ) {
	load_template( $file, false );
}

使い分け早見表

関連項目

get_template_part()、get_theme_file_path()、load_template()

公式リファレンス：locate_template() | Function | WordPress Developer Resources