能否仅通过自定义插件覆盖WordPress区块主题模板及模板部件？

一、利用block_template_part过滤器覆盖模板部件 #

区块主题的模板部件（比如首页内容块、头部/尾部组件）是通过block_template_part函数加载的，这个专属过滤器可以直接替换目标部件的加载路径。

示例代码：

add_filter( 'block_template_part', 'my_plugin_swap_template_part', 10, 3 );
function my_plugin_swap_template_part( $template_part, $slug, $area ) {
    // 替换首页的"home-content"模板部件
    if ( 'home-content' === $slug && 'content' === $area && is_front_page() ) {
        $plugin_part_path = plugin_dir_path( __FILE__ ) . 'template-parts/home-content.php';
        if ( file_exists( $plugin_part_path ) ) {
            $template_part = $plugin_part_path;
        }
    }
    return $template_part;
}

按需修改slug、area判断条件，就能精准替换主题里的任意模板部件。

二、用theme_file_path拦截主题文件加载 #

如果要替换完整的块模板（比如首页的front-page.html），可以用这个钩子拦截主题文件的加载路径，直接指向插件内的对应文件。

示例代码：

add_filter( 'theme_file_path', 'my_plugin_replace_theme_template', 10, 2 );
function my_plugin_replace_theme_template( $path, $file ) {
    // 替换首页模板
    if ( 'templates/front-page.html' === $file && is_front_page() ) {
        $plugin_template = plugin_dir_path( __FILE__ ) . 'templates/front-page.html';
        if ( file_exists( $plugin_template ) ) {
            $path = $plugin_template;
        }
    }
    // 额外示例：替换头部模板部件
    if ( 'template-parts/header.html' === $file ) {
        $plugin_header = plugin_dir_path( __FILE__ ) . 'template-parts/header.html';
        if ( file_exists( $plugin_header ) ) {
            $path = $plugin_header;
        }
    }
    return $path;
}

这个钩子对区块主题的HTML模板、传统PHP模板都有效，只要填对主题文件的相对路径即可。

三、通过block_templates过滤器添加/替换可选模板 #

如果想让用户在后台编辑页面时，能选择插件提供的模板，可以用这个钩子修改模板列表。

示例代码：

add_filter( 'block_templates', 'my_plugin_add_custom_template', 10, 2 );
function my_plugin_add_custom_template( $templates, $theme ) {
    // 可选：只针对目标主题生效
    if ( get_stylesheet() !== 'your-block-theme-slug' ) {
        return $templates;
    }

    // 定义插件自定义首页模板
    $custom_template = array(
        'slug'        => 'plugin-front-page',
        'title'       => '插件自定义首页',
        'content'     => file_get_contents( plugin_dir_path( __FILE__ ) . 'templates/plugin-front-page.html' ),
        'post_type'   => array( 'page' ),
        'is_custom'   => true,
    );

    // 替换原有的首页模板
    foreach ( $templates as $key => $template ) {
        if ( $template['slug'] === 'front-page' ) {
            $templates[$key] = $custom_template;
            break;
        }
    }

    // 也可以选择添加新模板（不替换原有）：$templates[] = $custom_template;
    return $templates;
}

设置完成后，用户在页面属性的「模板」下拉框里就能看到插件提供的选项。

为什么之前的钩子无效？ #

page_template和theme_page_templates是针对传统PHP主题设计的钩子，区块主题采用的是块模板（HTML文件）和模板部件机制，这些钩子不会触发，所以必须用上述专门适配区块主题的钩子。

内容的提问来源于stack exchange，提问作者Jorge Ferrari Ce