发布于 由admin

详解 WordPress `get_template_part()` 函数的源码：如何加载模板文件，并支持子主题。

好家伙，看来今天这场讲座要火力全开了！大家坐稳扶好，咱们这就扒开 WordPress get_template_part() 函数的底裤，看看它到底是怎么工作的。

开场白：模板的奥秘

各位观众老爷们大家好！今天咱们不聊风花雪月，专攻技术硬核。WordPress 模板系统，那可是主题开发的心脏。而 get_template_part() 函数，就是这颗心脏里的重要瓣膜，控制着模板文件的加载和组织。掌握它，就等于掌握了主题开发的半壁江山。

get_template_part()：你的模板零件组装大师

首先，咱们得认识一下今天的主角。get_template_part() 函数的作用，简单来说，就是加载并包含一个模板文件。它接收两个参数（严格来说可以接收更多，但核心是两个）：

  • $slug (string): 模板文件的 slug（前缀）。
  • $name (string, optional): 模板文件的 name（后缀），可选。

举个例子：

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

这段代码的意思是：加载 content-single.php 文件。如果找不到这个文件，它会尝试加载 content.php 文件。

源码解剖：get_template_part() 的运行机制

现在，咱们深入源码，看看 get_template_part() 到底是怎么运作的。以下是简化后的源码，去掉了不必要的注释和错误处理，方便大家理解：

function get_template_part( $slug, $name = null, $args = array() ) {
    /**
     * Fires before the specified template part is loaded.
     *
     * @since 2.0.0
     *
     * @param string      $slug The slug name for the generic template.
     * @param string|null $name The name of the specialized template.
     */
    do_action( "get_template_part_{$slug}", $slug, $name );

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

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

    /**
     * Filters the list of template filenames to search for when calling get_template_part().
     *
     * @since 2.7.0
     *
     * @param string[]    $templates   A list of template filenames to search for.
     * @param string      $slug        The slug name for the generic template.
     * @param string|null $name        The name of the specialized template.
     */
    $templates = apply_filters( 'get_template_part', $templates, $slug, $name );

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

别怕，咱们一步一步来分析：

  1. Hook 启动：do_action()

    do_action( "get_template_part_{$slug}", $slug, $name );

    这行代码触发了一个 action hook。它允许你在加载模板文件之前执行一些自定义代码。例如，你可以根据用户角色或其他条件来加载不同的模板文件。这个action的名字是动态的，由 get_template_part_ 加上 $slug 组成。比如，如果 $slug 是 'content'，那么 hook 的名字就是 'get_template_part_content'。

  2. 构建模板文件名数组：$templates

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

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

    这段代码构建了一个包含模板文件名的数组。它首先尝试构建一个带有 $name 后缀的文件名（例如 content-single.php），然后添加一个不带后缀的文件名（例如 content.php）。

  3. Filter 登场：apply_filters()

    $templates = apply_filters( 'get_template_part', $templates, $slug, $name );

    这行代码应用了一个 filter hook。它允许你修改 $templates 数组，从而改变模板文件的查找顺序或添加自定义的模板文件。

  4. 定位模板文件：locate_template()

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

    这行代码是核心。它使用 $templates 数组中的文件名来查找模板文件。locate_template() 函数会遍历主题目录（包括父主题和子主题），找到第一个匹配的文件，然后将其包含进来。true 表示找到文件后立即加载，false 表示不返回文件的路径，而直接加载。$args 是传递给模板的参数数组。

locate_template()：主题目录寻宝游戏

locate_template() 函数负责在主题目录中查找模板文件。它的源码比较复杂，咱们只关注关键部分：

function locate_template( $template_names, $load = false, $require_once = true, $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;
        } elseif ( file_exists( TEMPLATEPATH . '/' . $template_name ) ) {
            $located = TEMPLATEPATH . '/' . $template_name;
            break;
        }
    }

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

    return $located;
}

这段代码的逻辑如下：

  1. 遍历文件名数组：foreach

    它遍历 $template_names 数组，逐个查找模板文件。

  2. 优先查找子主题：STYLESHEETPATH

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

    它首先在子主题目录中查找模板文件。STYLESHEETPATH 常量指向当前主题的样式表目录，通常是子主题目录。

  3. 查找父主题：TEMPLATEPATH

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

    如果在子主题中找不到模板文件，它会在父主题目录中查找。TEMPLATEPATH 常量指向父主题目录。

  4. 加载模板文件：load_template()

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

    如果找到了模板文件，并且 $load 参数为 true，它会使用 load_template() 函数加载模板文件。

load_template()：最终执行者

load_template() 函数负责包含模板文件，并将 $args 数组中的变量传递给模板。它的源码也很简单：

function load_template( $_template_file, $require_once = true, $args = array() ) {
    global $posts, $post, $wp_did_template_redirect, $wp_query, $wp_rewrite, $wpdb, $wp_locale, $wp, $l10n;

    if ( is_array( $wp_query->query_vars ) ) {
        extract( $wp_query->query_vars, EXTR_SKIP );
    }

    if ( isset( $s ) ) {
        $search = $s;
    }

    if ( is_array( $args ) ) {
        extract( $args, EXTR_SKIP );
    }

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

这段代码的逻辑如下：

  1. 提取全局变量：global

    它声明了一些全局变量，使它们在模板文件中可用。

  2. 提取查询变量：extract( $wp_query->query_vars, EXTR_SKIP )

    它将 $wp_query->query_vars 数组中的变量提取出来，使它们在模板文件中可用。例如，paged 变量表示当前页码。 EXTR_SKIP 表示如果变量名与已存在的变量名冲突，则跳过。

  3. 提取搜索变量：$search = $s

    如果存在 $s 变量，它会将其赋值给 $search 变量。

  4. 提取参数变量：extract( $args, EXTR_SKIP )

    它将 $args 数组中的变量提取出来，使它们在模板文件中可用。EXTR_SKIP 表示如果变量名与已存在的变量名冲突，则跳过。

  5. 包含模板文件：require_once() 或 require()

    它使用 require_once() 或 require() 函数包含模板文件。require_once() 函数只会包含一次模板文件，而 require() 函数每次都会包含模板文件。

子主题支持：STYLESHEETPATH 和 TEMPLATEPATH 的功劳

get_template_part() 函数之所以能够支持子主题，关键在于 locate_template() 函数中使用了 STYLESHEETPATH 和 TEMPLATEPATH 常量。

  • STYLESHEETPATH 指向子主题目录。
  • TEMPLATEPATH 指向父主题目录。

locate_template() 函数首先在子主题目录中查找模板文件，如果找不到，才会在父主题目录中查找。这样，子主题就可以覆盖父主题的模板文件，实现自定义的效果。

使用场景：get_template_part() 的妙用

get_template_part() 函数在主题开发中用途广泛。以下是一些常见的使用场景：

  • 组织模板文件： 将模板文件分割成更小的模块，提高代码的可读性和可维护性。例如，可以将文章内容、评论表单、侧边栏等分别放在不同的模板文件中，然后使用 get_template_part() 函数将它们组合在一起。

  • 复用模板代码： 在不同的页面中使用相同的模板代码，减少代码的冗余。例如，可以在文章列表页和文章详情页中使用相同的文章摘要模板。

  • 创建灵活的布局： 根据不同的条件加载不同的模板文件，实现灵活的布局。例如，可以根据文章类型加载不同的文章内容模板。

  • 方便子主题覆盖： 允许子主题覆盖父主题的模板文件，实现自定义的效果。

代码示例：get_template_part() 的实战

假设我们有一个主题，需要显示文章的内容。我们可以将文章内容分割成两个模板文件：

  • content.php：包含文章的标题、作者、日期等信息。
  • content-single.php：包含文章的完整内容。

在 index.php 文件中，我们可以使用 get_template_part() 函数加载这两个模板文件：

<?php
if ( have_posts() ) {
    while ( have_posts() ) {
        the_post();
        if ( is_singular() ) {
            get_template_part( 'content', 'single' );
        } else {
            get_template_part( 'content' );
        }
    }
}
?>

这段代码的逻辑如下：

  • 如果当前页面是文章详情页（is_singular() 返回 true），则加载 content-single.php 文件。
  • 否则，加载 content.php 文件。

如果子主题需要修改文章的标题显示方式，只需要在子主题中创建一个 content.php 文件，并修改其中的代码即可。

$args 参数：模板文件的数据传递桥梁

get_template_part() 函数的第三个参数 $args，是一个数组，允许你向加载的模板传递数据。这使得模板更加灵活，可以根据传递的数据动态渲染内容。

例如，假设 content.php 文件需要显示文章的类别信息。我们可以将文章类别信息存储在 $args 数组中，然后传递给 content.php 文件：

<?php
$args = array(
    'categories' => get_the_category(),
);
get_template_part( 'content', null, $args );
?>

在 content.php 文件中，我们可以使用 extract() 函数提取 $args 数组中的变量：

<?php
extract( $args );
if ( ! empty( $categories ) ) {
    echo '<p>Categories: ';
    foreach ( $categories as $category ) {
        echo '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '">' . esc_html( $category->name ) . '</a> ';
    }
    echo '</p>';
}
?>

这段代码会显示文章的类别信息。

总结：get_template_part() 的精髓

get_template_part() 函数是 WordPress 主题开发中一个非常重要的函数。它允许你：

  • 组织模板文件，提高代码的可读性和可维护性。
  • 复用模板代码，减少代码的冗余。
  • 创建灵活的布局，根据不同的条件加载不同的模板文件。
  • 方便子主题覆盖，实现自定义的效果。
  • 通过 $args 参数传递数据，让模板更加灵活。

掌握 get_template_part() 函数，就等于掌握了 WordPress 主题开发的半壁江山。希望今天的讲座能够帮助大家更好地理解和使用这个函数。

彩蛋：一些小技巧

  • 使用 filter hook： 使用 get_template_part filter hook 可以修改模板文件的查找顺序或添加自定义的模板文件。这可以让你更加灵活地控制模板文件的加载。
  • 命名规范： 遵循 WordPress 的命名规范，可以提高代码的可读性和可维护性。例如，模板文件名应该以 - 分隔单词，并以 .php 结尾。
  • 性能优化： 避免过度使用 get_template_part() 函数，因为它会增加 HTTP 请求的数量，影响网站的性能。尽量将常用的模板代码合并到一个文件中。

好了，今天的讲座就到这里。希望大家能够学有所获，并在实际开发中灵活运用 get_template_part() 函数。如果还有什么问题，欢迎随时提问！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注