load_template()
云策文档标注
概述
load_template() 函数用于在 WordPress 环境中加载模板文件，确保全局变量和查询变量可用。它支持可选参数控制加载方式和传递额外参数。
关键要点
- 函数加载模板文件并设置全局变量，如 $wp_query、$post 等，以提供 WordPress 环境。
- 参数包括 $_template_file（必需，模板文件路径）、$load_once（可选，是否使用 require_once，默认 true）和 $args（可选，传递给模板的额外参数数组）。
- 使用 extract() 从 $wp_query->query_vars 提取变量到模板作用域，但受 EXTR_SKIP 保护以防止覆盖。
- 提供钩子 wp_before_load_template 和 wp_after_load_template，允许在模板加载前后执行操作。
- 常用于与 locate_template() 结合，实现主题或子主题模板覆盖机制。
代码示例
// 示例：加载模板并允许主题覆盖
if ( $overridden_template = locate_template( 'some-template.php' ) ) {
load_template( $overridden_template );
} else {
load_template( dirname( __FILE__ ) . '/templates/some-template.php' );
}注意事项
- $args 参数中的额外参数不会自动提取为模板中的变量名，而是作为 $args 数组在模板中可用。
- 使用 set_query_var() 可以将自定义变量添加到查询变量中，使其在模板中可访问。
- 函数自 WordPress 1.5.0 引入，5.5.0 版本添加了 $args 参数。
原文内容
Requires the template file with WordPress environment.
Description
The globals are set up for the template file to ensure that the WordPress environment is available from within the function. The query variables are also available.
Parameters
$_template_filestringrequired-
Path to template file.
$load_oncebooloptional-
Whether to require_once or require.
Default:
true $argsarrayoptional-
Additional arguments passed to the template.
Default:
array()
Source
function load_template( $_template_file, $load_once = true, $args = array() ) {
global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
if ( is_array( $wp_query->query_vars ) ) {
/*
* This use of extract() cannot be removed. There are many possible ways that
* templates could depend on variables that it creates existing, and no way to
* detect and deprecate it.
*
* Passing the EXTR_SKIP flag is the safest option, ensuring globals and
* function variables cannot be overwritten.
*/
// phpcs:ignore WordPress.PHP.DontExtract.extract_extract
extract( $wp_query->query_vars, EXTR_SKIP );
}
if ( isset( $s ) ) {
$s = esc_attr( $s );
}
/**
* Fires before a template file is loaded.
*
* @since 6.1.0
*
* @param string $_template_file The full path to the template file.
* @param bool $load_once Whether to require_once or require.
* @param array $args Additional arguments passed to the template.
*/
do_action( 'wp_before_load_template', $_template_file, $load_once, $args );
if ( $load_once ) {
require_once $_template_file;
} else {
require $_template_file;
}
/**
* Fires after a template file is loaded.
*
* @since 6.1.0
*
* @param string $_template_file The full path to the template file.
* @param bool $load_once Whether to require_once or require.
* @param array $args Additional arguments passed to the template.
*/
do_action( 'wp_after_load_template', $_template_file, $load_once, $args );
}
Hooks
- do_action( ‘wp_after_load_template’, string $_template_file, bool $load_once, array $args )
-
Fires after a template file is loaded.
- do_action( ‘wp_before_load_template’, string $_template_file, bool $load_once, array $args )
-
Fires before a template file is loaded.
Skip to note 4 content
Codex
Loading a template in a plugin, but allowing theme and child theme to override template
if ( $overridden_template = locate_template( 'some-template.php' ) ) { /* * locate_template() returns path to file. * if either the child theme or the parent theme have overridden the template. */ load_template( $overridden_template ); } else { /* * If neither the child nor parent theme have overridden the template, * we load the template from the 'templates' sub-directory of the directory this file is in. */ load_template( dirname( __FILE__ ) . '/templates/some-template.php' ); }Skip to note 5 content
webbuilder03
Send variable with load_template()
you can send additional variable with load_template() . load_template() extracts all of the WP_Query query variables, into the scope of the loaded template.
use set_query_var() to make your variable available to the template part.
$template = locate_template('template.php'); if( $template ){ set_query_var('my_variable ', 'Hello Template File' ); load_template( $template ); }In template.php file you can access this variable like this
//Output will be "Hello Template File" echo $my_variable;Skip to note 6 content
strarsis
Note that the arguments set in `$args` are not simply made available as variables of the same name (as the key) in the template. Instead they are available in the `$args` variable in the template.
public function renderShortcode(array $args): string { $result = $this->loadNews(); $template = locate_template('news.php'); if (!$template) { $template = __DIR__ . '/templates/news.php'; } ob_start(); load_template($template, true, [ 'result' => $result, ]); return ob_end_clean(); }The above will not work since we have the $result in the $args variable. I remove this entry since I do not understand how I can make a line break in the code…