分析 WordPress `get_template_part()` 函数的源码：如何加载模板文件，并支持子主题。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，晚上好！我是你们的老朋友，今天咱们来聊聊 WordPress 模板引擎里一个非常关键的函数 get_template_part()。这货就像个辛勤的快递小哥，专门负责把模板文件送到指定的地方，而且还特别懂事，知道怎么处理子主题的优先级问题。

咱们今天就深入剖析一下 get_template_part() 的源码，看看它是怎么工作的，以及为什么它能如此优雅地支持子主题。准备好了吗？发车！

1. get_template_part() 的基本用法

先来回顾一下 get_template_part() 的基本用法，这能帮助我们更好地理解源码。

<?php
/**
 * 加载一个模板部件
 *
 * @param string $slug    模板部件的 slug 名称
 * @param string $name    模板部件的 name 名称 (可选)
 */
get_template_part( string $slug, string|null $name = null ) : void
?>

比如，你想加载一个名为 content-single.php 的模板，你可以这样写：

<?php get_template_part( 'content', 'single' ); ?>

这行代码会尝试加载 content-single.php 文件。如果 $name 为空，那么就只加载 content.php 文件。

2. 源码剖析：一步一步追踪 get_template_part()

好了，现在让我们撸起袖子，深入 wp-includes/template.php 文件，找到 get_template_part() 函数的真身。

function get_template_part( string $slug, string|null $name = null, array $args = array() ) : void {
    /**
     * Fires before the specified template part file is loaded.
     *
     * The dynamic portion of the hook name, `$slug`, refers to the slug
     * name for the generic template part.
     *
     * @since 3.0.0
     *
     * @param string      $slug Name of the generic template part.
     * @param string|null $name Name of the specific variation template part.
     * @param array       $args Additional arguments passed to the template.
     */
    do_action( "get_template_part_{$slug}", $slug, $name, $args );

    $templates = array();
    $name      = (string) $name;
    if ( '' !== $name ) {
        $templates[] = "{$slug}-{$name}.php";
    }

    $templates[] = "{$slug}.php";

    /**
     * Filters the list of template filenames to search for when calling get_template_part().
     *
     * The dynamic portion of the hook name, `$slug`, refers to the slug
     * name for the generic template part.
     *
     * @since 4.0.0
     *
     * @param string[]    $templates List of template filenames.
     * @param string      $slug      Slug of the template.
     * @param string|null $name      Name of the template.
     * @param array       $args      Additional arguments passed to the template.
     */
    $templates = apply_filters( "get_template_part_{$slug}", $templates, $slug, $name, $args );

    locate_template( $templates, true, false, $args );
}

代码虽然不多，但信息量很大，我们一点一点分析：

Action Hook ( do_action ): 在加载模板之前，会触发一个 action hook: get_template_part_{$slug}。这个hook允许开发者在模板加载之前执行一些自定义操作。$slug 是传递给 get_template_part() 的第一个参数，也就是模板的 slug 名称。
模板文件名构建: 根据传入的 $slug 和 $name 参数，构建一个模板文件名数组 $templates。如果 $name 存在，就先构建一个包含 $slug 和 $name 的文件名（例如：content-single.php），然后构建一个只包含 $slug 的文件名（例如：content.php）。
Filter Hook ( apply_filters ): 允许开发者通过 get_template_part_{$slug} filter hook 修改 $templates 数组。这提供了一个非常灵活的方式，可以自定义模板文件的加载顺序和规则。
locate_template() 函数: 调用 locate_template() 函数来查找并加载模板文件。这是整个流程的核心，我们稍后会详细分析它。

3. locate_template() 函数：模板查找的灵魂

locate_template() 函数负责在主题目录及其父主题目录中查找指定的模板文件。它的源码如下：

function locate_template( $template_names, $load = false, $require_once = true, array $args = array() ) {
    $located = false;
    foreach ( (array) $template_names as $template_name ) {
        if ( ! $template_name ) {
            continue;
        }

        if ( file_exists( STYLESHEETPATH . '/' . $template_name ) ) {
            $located = STYLESHEETPATH . '/' . $template_name;
            break;
        }

        if ( file_exists( TEMPLATEPATH . '/' . $template_name ) ) {
            $located = TEMPLATEPATH . '/' . $template_name;
            break;
        }
    }

    if ( $load && '' !== $located ) {
        load_template( $located, $require_once, $args );
    }

    return $located;
}

让我们拆解一下：

遍历模板文件名: 循环遍历传入的 $template_names 数组，这个数组就是 get_template_part() 函数构建的模板文件名列表。
查找子主题目录: 首先，检查子主题目录（STYLESHEETPATH）中是否存在对应的模板文件。如果存在，则将文件路径赋值给 $located 变量，并跳出循环。 STYLESHEETPATH 通常指向当前主题（如果是子主题，则指向子主题目录）。
查找父主题目录: 如果子主题目录中没有找到，则检查父主题目录（TEMPLATEPATH）中是否存在对应的模板文件。如果存在，则将文件路径赋值给 $located 变量，并跳出循环。 TEMPLATEPATH 通常指向父主题目录。
加载模板: 如果 $load 参数为 true 且 $located 变量不为空，则调用 load_template() 函数加载模板文件。
返回值: 返回找到的模板文件的路径（如果找到），否则返回 false。

4. load_template() 函数：真正的模板加载器

load_template() 函数负责加载模板文件并将其包含到当前上下文中。

function load_template( $template_file, $require_once = true, array $args = array() ) {
    global $posts, $post, $wp_did_template, $wp_query, $wp, $comment, $comments, $wp_locale, $wp_customize;

    /**
     * Fires before the specified template is loaded.
     *
     * @since 1.5.0
     *
     * @param string $template_file The path to the template file.
     * @param array  $args          Additional arguments passed to the template.
     */
    do_action( 'template_redirect', $template_file, $args );

    if ( isset( $args ) && is_array( $args ) ) {
        extract( $args );
    }

    $wp_did_template = true;

    if ( $require_once ) {
        require_once $template_file;
    } else {
        require $template_file;
    }
}

核心逻辑：

提取参数: 如果 $args 参数存在且是一个数组，则使用 extract() 函数将数组中的键值对提取为变量。这意味着你可以在 get_template_part() 中传递一些参数，并在模板文件中直接使用这些参数。
加载模板文件: 使用 require_once 或 require 语句加载模板文件。 require_once 确保模板文件只被加载一次，避免重复加载导致的问题。

5. 子主题支持的奥秘

现在，我们来揭开 get_template_part() 支持子主题的奥秘。关键在于 locate_template() 函数的查找顺序：

子主题目录 ( STYLESHEETPATH )
父主题目录 ( TEMPLATEPATH )

这意味着，如果子主题中存在与父主题同名的模板文件，那么 WordPress 会优先加载子主题中的模板文件。这允许子主题覆盖父主题的模板，从而实现自定义主题外观和功能的目的。

举个栗子

假设你的父主题有一个 content.php 文件，你想在子主题中修改它的内容。你只需要在子主题的目录中创建一个名为 content.php 的文件，并修改其内容。当 WordPress 调用 get_template_part( 'content' ) 时，它会首先在子主题目录中找到 content.php 文件，并加载它，而不是加载父主题中的 content.php 文件。

6. 总结

get_template_part() 函数的工作流程可以概括为以下几个步骤：

构建模板文件名: 根据传入的 $slug 和 $name 参数，构建一个模板文件名数组。
查找模板文件: 使用 locate_template() 函数在子主题目录和父主题目录中查找模板文件。
加载模板文件: 如果找到模板文件，则使用 load_template() 函数加载它。

以下表格总结了各个函数的作用：

函数名	作用
`get_template_part()`	构建模板文件名数组，调用 `locate_template()` 函数查找模板文件，如果找到则调用 `load_template()` 函数加载模板文件。它是开发者最常使用的函数，用于加载模板部件。
`locate_template()`	在子主题目录和父主题目录中查找模板文件。它的查找顺序决定了子主题可以覆盖父主题的模板。
`load_template()`	真正地加载模板文件。它使用 `require_once` 或 `require` 语句将模板文件包含到当前上下文中。同时，它还负责提取传递给模板的参数，使其可以在模板文件中直接使用。

7. 进阶用法和技巧

传递参数: get_template_part() 函数的第三个参数 $args 允许你向模板传递参数。例如：
```
<?php get_template_part( 'template-parts/post/content', get_post_format(), array( 'post_id' => get_the_ID() ) ); ?>
```
然后在 template-parts/post/content-*.php 模板中，你可以使用 $post_id 变量。
使用 Filter Hook: 利用 get_template_part_{$slug} filter hook，可以自定义模板文件的加载规则。例如，你可以根据用户的角色加载不同的模板文件。
避免硬编码: 尽量避免在模板文件中硬编码路径。使用 get_template_directory_uri() 和 get_stylesheet_directory_uri() 函数可以获取主题和子主题的目录 URI。

8. 常见问题与解答

Q: 为什么我的子主题无法覆盖父主题的模板？

A: 请确保你的子主题目录结构和文件名与父主题完全一致。检查文件名是否正确，目录结构是否正确，以及是否存在拼写错误。
Q: 如何调试 get_template_part() 函数？

A: 你可以使用 var_dump() 或 error_log() 函数来输出 $templates 数组和 $located 变量的值，以便了解模板文件的查找过程。
Q: get_template_part() 和 include 有什么区别？

A: get_template_part() 函数专门用于加载模板部件，它具有子主题支持和模板查找功能。include 语句则直接包含指定的文件，不具备这些功能。

9. 总结的总结

get_template_part() 函数是 WordPress 模板引擎中一个非常重要的组成部分。它简化了模板部件的加载，并提供了强大的子主题支持和自定义能力。理解它的工作原理，可以帮助你更好地开发 WordPress 主题和插件。

好了，今天的讲座就到这里。希望大家有所收获！下次再见！

发表回复 取消回复

发表回复取消回复