核心函数：`get_template_part`和`locate_template`的模板加载策略

WordPress 模板加载策略：get_template_part 与 locate_template

大家好！今天我们来深入探讨 WordPress 模板系统中两个至关重要的函数：get_template_part 和 locate_template。理解它们的工作原理对于构建灵活、可维护的 WordPress 主题至关重要。我们将从基础概念入手，逐步分析它们的内部机制，并通过示例代码演示如何在实际开发中应用它们。

1. 模板层级结构：WordPress 的寻路逻辑

在深入了解 get_template_part 和 locate_template 之前，我们需要先了解 WordPress 的模板层级结构。WordPress 使用一套预定义的模板文件名，并按照一定的优先级顺序查找相应的模板文件来渲染页面。这种层级结构允许开发者根据不同的页面类型（例如，首页、文章页面、分类页面）创建不同的模板，从而实现高度定制化的网站外观。

简单来说，WordPress会依据请求的页面类型，按照一套预设的规则，优先寻找特定的模板文件。如果找不到，它会退回到更通用的模板，直到找到一个匹配的模板或者到达默认模板。

举个例子，假设用户请求一个名为 “my-post” 的文章页面。WordPress 会按照以下顺序查找模板文件：

1. single-my-post.php
2. single.php
3. index.php

如果 single-my-post.php 存在，则使用它来渲染页面。如果不存在，则查找 single.php，以此类推。如果以上模板文件都不存在，则最终使用 index.php。

理解模板层级结构是理解 locate_template 和 get_template_part 的前提。这两个函数都是为了在这个层级结构中寻找合适的模板文件而设计的。

2. locate_template：定位模板文件的精确制导

locate_template 函数的作用是根据给定的模板文件名，在主题目录下查找对应的模板文件，并返回其完整的文件路径。如果找到了匹配的模板文件，则返回其路径；否则，返回一个空字符串。

函数签名：

<?php
/**
 * Retrieve the name of the highest priority template file that exists.
 *
 * Searches in the stylesheet directory prior to the template directory so that themes
 * which inherit from a parent theme can just define new versions of the files.
 *
 * @since 2.7.0
 *
 * @param string|string[] $template_names Template file(s) to search for, in order of priority.
 * @param bool            $load            Optional. Whether to load the template if it's found. Default false.
 * @param bool            $require_once  Optional. Whether to require_once or require. Has no effect if $load is false. Default true.
 * @param string          $args            Optional. Additional arguments passed to the located template.
 * @return string The template filename if one is located.
 */
function locate_template( $template_names, $load = false, $require_once = true, $args = '' ) {
    // ... 函数实现 ...
}
?>

参数解释：

• $template_names (string|array): 需要查找的模板文件名，可以是单个字符串或字符串数组。如果是数组，则按照数组中的顺序查找，直到找到一个匹配的模板文件。
• $load (bool): 可选参数，指定是否立即加载找到的模板文件。默认为 false，表示只返回模板文件的路径，不加载它。
• $require_once (bool): 可选参数，仅当 $load 为 true 时有效。指定使用 require_once 或 require 加载模板文件。默认为 true，表示使用 require_once。
• $args (string): 可选参数。传递给模板文件的额外参数。

工作流程：

1. 构建查找路径： locate_template 首先会构建一个包含主题目录和子主题目录的查找路径数组。它会优先查找子主题目录，然后再查找父主题目录，这允许子主题覆盖父主题的模板文件。

2. 循环查找模板文件： 遍历 $template_names 数组，依次查找指定的模板文件。对于每个模板文件名，它会在查找路径数组中的每个目录下查找是否存在该文件。

3. 返回模板路径或加载模板： 如果找到匹配的模板文件，则返回其完整的文件路径。如果 $load 参数为 true，则会使用 require_once 或 require 加载该模板文件，并返回 true。如果没有找到任何匹配的模板文件，则返回一个空字符串。

示例代码：

<?php
// 查找名为 'my-template.php' 的模板文件
$template_path = locate_template( 'my-template.php' );

if ( $template_path ) {
    echo '找到模板文件：' . $template_path;
} else {
    echo '未找到模板文件：my-template.php';
}

// 查找名为 'my-template.php' 或 'default-template.php' 的模板文件，并加载它
$template_path = locate_template( array( 'my-template.php', 'default-template.php' ), true );

if ( $template_path ) {
    // 模板文件已被加载
} else {
    echo '未找到任何模板文件：my-template.php 或 default-template.php';
}
?>

注意事项：

• locate_template 函数只会查找主题目录下的模板文件。它不会查找插件目录下的模板文件。
• locate_template 函数返回的是模板文件的完整文件路径，包括主题目录的路径。
• 如果 $load 参数为 true，则 locate_template 函数会立即加载找到的模板文件，并将模板文件的内容包含到当前脚本中。

3. get_template_part：模板片段的灵活组合

get_template_part 函数的作用是加载一个模板片段（template part），并将其包含到当前模板中。模板片段通常是主题中可重用的代码块，例如，页眉、页脚、侧边栏等。

函数签名：

<?php
/**
 * Load a template part into a template.
 *
 * Makes it easy for themes to reuse sections of code and not repeat themselves.
 *
 * Includes the named template part for a theme or if a name is specified then a
 * specialised part will be included. If the theme contains no specialised parts
 * then the default template part will be used.
 *
 * List of templates used:
 * get_template_part( 'slug' )
 *   -> slug.php
 * get_template_part( 'slug', 'name' )
 *   -> slug-name.php
 *   -> slug.php
 *
 * @since 3.0.0
 *
 * @param string $slug The slug name for the generic template.
 * @param string|null $name The name of the specialised template.
 * @param array $args Array of arguments to pass into the template part.
 */
function get_template_part( $slug, $name = null, $args = array() ) {
    /**
     * 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 Template slug.
     * @param string|null $name Template name.
     * @param array       $args Array of arguments to pass into the template part.
     */
    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 3.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 Array of arguments to pass into the template part.
     */
    $templates = apply_filters( "get_template_part_{$slug}", $templates, $slug, $name, $args );

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

参数解释：

• $slug (string): 模板片段的 slug 名称。Slug 通常用于标识模板片段的用途，例如，’header’、’footer’、’sidebar’ 等。
• $name (string|null): 可选参数，模板片段的名称。如果指定了名称，则 WordPress 会尝试加载一个更具体的模板文件，例如，header-home.php。
• $args (array): 可选参数，传递给模板片段的参数数组。这些参数可以在模板片段中使用。

工作流程：

1. 构建模板文件名： get_template_part 首先会根据 $slug 和 $name 参数构建一个或多个模板文件名。它会优先查找带有名称的模板文件，然后再查找通用的模板文件。例如，如果 $slug 为 ‘header’，$name 为 ‘home’，则会查找 header-home.php 和 header.php。

2. 使用 locate_template 查找模板文件： get_template_part 使用 locate_template 函数在主题目录下查找构建的模板文件。

3. 加载模板文件： 如果 locate_template 找到了匹配的模板文件，则 get_template_part 会加载该模板文件，并将其包含到当前模板中。同时会将 $args 参数传递给模板文件。

示例代码：

<?php
// 加载名为 'header.php' 的模板片段
get_template_part( 'header' );

// 加载名为 'header-home.php' 或 'header.php' 的模板片段
get_template_part( 'header', 'home' );

// 加载名为 'sidebar.php' 的模板片段，并传递一个参数
$args = array(
    'widget_area' => 'sidebar-1'
);
get_template_part( 'sidebar', null, $args );
?>

在 sidebar.php 中，你可以通过 $args 变量访问传递的参数：

<?php
if ( isset( $args['widget_area'] ) ) {
    dynamic_sidebar( $args['widget_area'] );
} else {
    dynamic_sidebar( 'sidebar-1' ); // 默认侧边栏
}
?>

注意事项：

• get_template_part 函数只能加载主题目录下的模板片段。它不会加载插件目录下的模板片段。
• get_template_part 函数会自动将模板片段的内容包含到当前模板中。你不需要手动使用 require_once 或 require 加载模板文件。
• get_template_part的第三个参数$args会在模板文件中以变量$args的形式存在，可以直接调用$args['参数名']

4. get_template_part 的高级用法：动态 Slug 和 Name

get_template_part 的强大之处在于其 $slug 和 $name 参数的灵活性。你可以使用变量来动态地指定要加载的模板片段，从而实现更高级的模板组合。

例如，你可以根据当前文章的分类加载不同的页眉模板：

<?php
$categories = get_the_category();
if ( ! empty( $categories ) ) {
    $first_category = $categories[0]->slug;
    get_template_part( 'header', $first_category );
} else {
    get_template_part( 'header' );
}
?>

这段代码会首先获取当前文章的分类。如果文章有分类，则使用第一个分类的 slug 作为 $name 参数加载页眉模板，例如，header-category-slug.php。如果文章没有分类，则加载通用的 header.php 模板。

你还可以使用 apply_filters 钩子来修改 get_template_part 的行为。例如，你可以使用 get_template_part_{$slug} 钩子来修改要查找的模板文件名：

<?php
add_filter( 'get_template_part_header', 'my_custom_header_template', 10, 3 );

function my_custom_header_template( $templates, $slug, $name, $args ) {
    if ( is_page( 'contact' ) ) {
        $templates = array( 'header-contact.php' );
    }
    return $templates;
}
?>

这段代码会在加载 header 模板片段之前，检查当前页面是否为 “contact” 页面。如果是，则将要查找的模板文件名修改为 header-contact.php。

5. locate_template 和 get_template_part 的对比

特性	locate_template	get_template_part
主要功能	查找模板文件并返回其路径	加载模板片段并将其包含到当前模板中
返回值	模板文件的完整路径 (如果找到) 或空字符串 (如果未找到)	无返回值 (void)
是否加载模板文件	可选 (通过 $load 参数控制)	自动加载找到的模板文件
应用场景	需要手动加载模板文件或需要在加载之前进行一些处理时	加载可重用的模板片段，例如，页眉、页脚、侧边栏等
参数传递	可选的 $args 参数，传递给模板文件。	可选的 $args 参数，传递给模板文件。
查找路径	优先查找子主题目录，然后再查找父主题目录	优先查找子主题目录，然后再查找父主题目录
钩子	无直接钩子，但可以使用 template_include 钩子修改模板加载流程	get_template_part_{$slug} 钩子，允许修改要查找的模板文件名

6. 实战案例：构建一个灵活的侧边栏系统

我们可以使用 get_template_part 和 locate_template 构建一个灵活的侧边栏系统，允许根据不同的页面类型加载不同的侧边栏。

1. 创建侧边栏模板文件：

   • sidebar.php：默认侧边栏模板。
   • sidebar-home.php：首页侧边栏模板。
   • sidebar-archive.php：存档页面侧边栏模板。
   • sidebar-single.php：文章页面侧边栏模板。

2. 在主题的模板文件中使用 get_template_part 加载侧边栏：

   <?php
   if ( is_home() ) {
       get_template_part( 'sidebar', 'home' );
   } elseif ( is_archive() ) {
       get_template_part( 'sidebar', 'archive' );
   } elseif ( is_single() ) {
       get_template_part( 'sidebar', 'single' );
   } else {
       get_template_part( 'sidebar' );
   }
   ?>

这段代码会根据当前页面类型加载不同的侧边栏模板。如果当前页面是首页，则加载 sidebar-home.php。如果当前页面是存档页面，则加载 sidebar-archive.php。如果当前页面是文章页面，则加载 sidebar-single.php。否则，加载默认的 sidebar.php。

3. 使用 locate_template 自定义侧边栏加载逻辑：

   你可以使用 locate_template 函数来更精细地控制侧边栏的加载逻辑。例如，你可以根据文章的自定义字段加载不同的侧边栏：

   <?php
   $sidebar_template = get_post_meta( get_the_ID(), 'sidebar_template', true );
   
   if ( $sidebar_template ) {
       $template_path = locate_template( 'sidebar-' . $sidebar_template . '.php' );
       if ( $template_path ) {
           include( $template_path );
       } else {
           get_template_part( 'sidebar' ); // 加载默认侧边栏
       }
   } else {
       get_template_part( 'sidebar' ); // 加载默认侧边栏
   }
   ?>

   这段代码会首先获取文章的自定义字段 ‘sidebar_template’ 的值。如果该值存在，则使用 locate_template 函数查找对应的侧边栏模板文件。如果找到匹配的模板文件，则使用 include 函数加载该模板文件。否则，加载默认的 sidebar.php 模板。

7. 总结：灵活运用，构建可维护的主题

get_template_part 和 locate_template 是 WordPress 模板系统中强大的工具，理解它们的工作原理对于构建灵活、可维护的主题至关重要。locate_template 专注于查找模板文件，而 get_template_part 则更进一步，将找到的模板片段加载到当前模板中。通过灵活运用这两个函数，我们可以构建高度定制化的 WordPress 网站，并提高代码的重用性和可维护性。