WordPress函数：get_template_part 模块化加载主题模板文件

简介

get_template_part 是 WordPress 主题开发中的核心模板加载函数，它允许开发者将主题文件拆分为模块化的部分，实现代码复用和可维护的模板结构。

语法

get_template_part( string $slug, string $name = null, array $args = array() )

位置： wp-includes/general-template.php

内部调用流程：
1. 调用 locate_template() 查找模板文件
2. 调用 load_template() 加载模板文件
3. 从 WordPress 5.5.0 开始支持第三个参数 $args 传递数据

参数说明：

返回值： 无返回值，直接输出加载的模板内容。

用法

基础用法

加载通用内容模板

在主题的主模板文件（如 index.php、single.php）中加载内容模板：

// 在 single.php 中
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        // 加载 content.php 或 content-{post-format}.php
        get_template_part( 'content', get_post_format() );
    endwhile;
endif;

加载特定页眉/页脚

根据不同页面加载不同的页眉：

// 在主题的 header.php 或特定模板文件中
if ( is_front_page() ) {
    get_template_part( 'template-parts/header', 'home' );
} elseif ( is_single() ) {
    get_template_part( 'template-parts/header', 'single' );
} else {
    get_template_part( 'template-parts/header' );
}

进阶用法

使用参数传递数据（WordPress 5.5+）

从 WordPress 5.5.0 开始，可以通过第三个参数向模板传递变量：

// 在主题模板文件中传递数据
$template_args = array(
    'custom_title' => '自定义标题',
    'show_author'  => true,
    'post_count'   => 5
);

get_template_part( 'template-parts/featured', 'posts', $template_args );

在模板文件中接收数据：

// template-parts/featured-posts.php
// 从 $args 变量中获取传递的参数
if ( isset( $args ) && is_array( $args ) ) {
    $custom_title = $args['custom_title'] ?? '默认标题';
    $show_author  = $args['show_author'] ?? false;
    $post_count   = $args['post_count'] ?? 3;
}

// 使用变量
echo '<h2>' . esc_html( $custom_title ) . '</h2>';

// 查询文章
$query_args = array(
    'posts_per_page' => (int) $post_count,
    'post_status'    => 'publish'
);

$featured_posts = new WP_Query( $query_args );

动态模板加载逻辑

创建复杂的模板选择逻辑：

// 根据多种条件选择模板
function get_custom_template_part( $post_id ) {
    $post_type = get_post_type( $post_id );
    $category  = get_the_category( $post_id );

    // 优先加载特定分类的模板
    if ( ! empty( $category ) ) {
        $category_slug = $category[0]->slug;
        $category_template = "content-{$post_type}-{$category_slug}";

        // 检查模板是否存在
        if ( locate_template( "template-parts/{$category_template}.php" ) ) {
            get_template_part( "template-parts/content", "{$post_type}-{$category_slug}" );
            return;
        }
    }

    // 回退到默认模板
    get_template_part( 'template-parts/content', $post_type );
}

// 在循环中使用
while ( have_posts() ) : the_post();
    get_custom_template_part( get_the_ID() );
endwhile;

创建模板部件库

组织可复用的模板部件：

// 在 functions.php 中创建辅助函数
function theme_render_component( $component_name, $args = array() ) {
    // 安全的组件名称
    $component_name = sanitize_key( $component_name );

    // 设置默认参数
    $defaults = array(
        'class' => '',
        'id'    => '',
        'data'  => array()
    );

    $args = wp_parse_args( $args, $defaults );

    // 加载组件模板
    get_template_part( "template-parts/components/{$component_name}", '', $args );
}

// 在模板中使用
theme_render_component( 'card', array(
    'title'   => get_the_title(),
    'excerpt' => get_the_excerpt(),
    'image'   => get_post_thumbnail_id(),
    'class'   => 'featured-card',
    'data'    => array( 'post-id' => get_the_ID() )
) );

易错点

文件命名和路径错误

错误：

// 错误路径，WordPress 不会自动在子目录中查找
get_template_part( 'inc/content' ); // 期望加载 inc/content.php

原因： get_template_part 不会自动在子目录中递归查找，除非提供完整路径。

正确做法：

// 明确指定路径
get_template_part( 'template-parts/content' ); // 加载 template-parts/content.php

忽略模板层级机制

错误： 假设 get_template_part 会自动回退到父主题的模板。

实际情况： 虽然 locate_template() 会检查父主题，但如果你在子主题中创建了相同路径的文件，父主题的模板不会被加载。

过度使用导致性能问题

错误： 在一个页面中使用几十个 get_template_part 调用，每个都加载小文件。

原因： 每次调用都会执行文件系统检查，频繁调用会影响性能。

未处理不存在的模板

错误： 假设模板文件一定存在，没有错误处理。

get_template_part( 'non-existent-template' );
// 如果文件不存在，不会输出任何内容，也没有错误提示

建议： 使用 locate_template() 预先检查或添加错误处理。

全局变量作用域问题

错误： 在模板部分中无法访问调用文件的局部变量。

// 在主模板中
$custom_data = '重要数据';
get_template_part( 'template-parts/component' );

// 在 component.php 中
echo $custom_data; // 未定义，因为变量作用域不同

解决方案： 使用 $args 参数传递数据，或使用全局变量（不推荐）。

最佳实践

性能优化

批量加载模板部件

减少文件系统操作，合并相关部件：

// 不好的做法：多次调用
get_template_part( 'template-parts/post', 'header' );
get_template_part( 'template-parts/post', 'content' );
get_template_part( 'template-parts/post', 'footer' );

// 好的做法：合并到一个模板
get_template_part( 'template-parts/post', 'full' );

// 在 post-full.php 中包含其他部分
get_template_part( 'template-parts/post', 'header' );
get_template_part( 'template-parts/post', 'content' );
get_template_part( 'template-parts/post', 'footer' );

使用缓存策略

对于动态内容较多的模板，考虑添加缓存：

function get_cached_template_part( $slug, $name = null, $args = array() ) {
    // 创建缓存键
    $cache_key = md5( serialize( array( $slug, $name, $args ) ) );
    $cache_group = 'template_parts';

    // 尝试从缓存获取
    $cached_output = wp_cache_get( $cache_key, $cache_group );

    if ( false !== $cached_output ) {
        echo $cached_output;
        return;
    }

    // 缓存未命中，渲染模板
    ob_start();
    get_template_part( $slug, $name, $args );
    $output = ob_get_clean();

    // 存储到缓存（根据内容设置合适的过期时间）
    wp_cache_set( $cache_key, $output, $cache_group, HOUR_IN_SECONDS );

    echo $output;
}

代码可维护性

统一的模板结构

创建一致的主题模板组织：

theme/
├── template-parts/
│   ├── components/      # 可复用组件
│   │   ├── card.php
│   │   ├── button.php
│   │   └── modal.php
│   ├── content/         # 内容模板
│   │   ├── content.php
│   │   ├── content-single.php
│   │   └── content-page.php
│   ├── layout/          # 布局部分
│   │   ├── header.php
│   │   ├── footer.php
│   │   └── sidebar.php
│   └── loops/           # 循环模板
│       ├── loop-standard.php
│       └── loop-grid.php
└── functions.php

创建模板加载助手

封装常用模板加载逻辑：

// 在 functions.php 中
class Theme_Template_Loader {

    /**
     * 安全加载模板部分
     */
    public static function load( $slug, $name = null, $args = array(), $require_once = false ) {
        // 验证参数
        if ( empty( $slug ) ) {
            _doing_it_wrong( __METHOD__, '模板 slug 不能为空', '1.0.0' );
            return false;
        }

        // 添加错误处理
        add_filter( 'template_include', array( __CLASS__, 'template_error_handler' ) );

        // 加载模板
        get_template_part( $slug, $name, $args );

        // 移除错误处理
        remove_filter( 'template_include', array( __CLASS__, 'template_error_handler' ) );

        return true;
    }

    /**
     * 模板错误处理
     */
    public static function template_error_handler( $template ) {
        // 记录日志或显示用户友好的错误信息
        if ( WP_DEBUG ) {
            error_log( '无法加载模板: ' . $template );
        }

        return $template;
    }

    /**
     * 根据条件加载模板
     */
    public static function load_conditional( $conditions ) {
        foreach ( $conditions as $condition => $template ) {
            if ( call_user_func( $condition ) ) {
                list( $slug, $name ) = array_pad( explode( '-', $template, 2 ), 2, null );
                self::load( $slug, $name );
                return;
            }
        }

        // 默认模板
        self::load( 'template-parts/content' );
    }
}

// 使用示例
Theme_Template_Loader::load_conditional( array(
    'is_front_page' => 'content-home',
    'is_single'     => 'content-single',
    'is_page'       => 'content-page'
) );

安全性增强

验证和清理传入数据

确保传递给模板的参数是安全的：

function safe_get_template_part( $slug, $name = null, $args = array() ) {
    // 清理 slug 和 name
    $slug = sanitize_file_name( $slug );
    $name = $name ? sanitize_file_name( $name ) : null;

    // 清理 args 数组中的值
    $cleaned_args = array();
    foreach ( $args as $key => $value ) {
        $key = sanitize_key( $key );

        // 根据值的类型进行清理
        if ( is_string( $value ) ) {
            $cleaned_args[ $key ] = wp_kses_post( $value );
        } elseif ( is_array( $value ) ) {
            $cleaned_args[ $key ] = array_map( 'wp_kses_post', $value );
        } else {
            $cleaned_args[ $key ] = $value;
        }
    }

    // 添加 nonce 验证（如果需要）
    if ( isset( $cleaned_args['nonce_action'] ) && isset( $cleaned_args['nonce'] ) ) {
        if ( ! wp_verify_nonce( $cleaned_args['nonce'], $cleaned_args['nonce_action'] ) ) {
            wp_die( '安全验证失败' );
        }
    }

    get_template_part( $slug, $name, $cleaned_args );
}

// 在模板中输出时进行转义
// template-parts/component.php
if ( isset( $args['user_input'] ) ) {
    // 根据上下文使用正确的转义函数
    echo '<div class="content">';
    echo wp_kses_post( $args['user_input'] ); // 允许安全的 HTML
    echo '</div>';

    // 对于 URL
    if ( isset( $args['user_url'] ) ) {
        echo '<a href="' . esc_url( $args['user_url'] ) . '">链接</a>';
    }
}

防止目录遍历攻击

确保模板路径安全：

function secure_template_part( $slug, $name = null ) {
    // 防止目录遍历攻击
    $slug = str_replace( array( '../', '..\\' ), '', $slug );
    $name = $name ? str_replace( array( '../', '..\\' ), '', $name ) : null;

    // 限制模板加载到特定目录
    $allowed_dirs = array( 'template-parts', 'components', 'loops' );
    $slug_parts = explode( '/', $slug );

    if ( ! in_array( $slug_parts[0], $allowed_dirs, true ) ) {
        if ( WP_DEBUG ) {
            _doing_it_wrong( __FUNCTION__, '尝试加载未授权的模板目录', '1.0.0' );
        }
        return;
    }

    get_template_part( $slug, $name );
}