使用get_template_part加载PHP片段时如何添加可开关调试div包裹及识别信息

核心通过WordPress原生钩子实现，无需修改原有get_template_part调用代码，所有需求均可覆盖。

1. 全局配置（开关+目录样式映射） #

将以下代码放在当前主题的functions.php文件开头，可直接控制功能开关和自定义样式：

// 全局调试开关：true 开启调试包裹，false 关闭所有调试逻辑
define('WP_PARTIAL_DEBUG', true);

// 不同目录partial对应样式配置，可按需求自行修改
$GLOBALS['partial_debug_styles'] = [
    'partials'      => 'border: 1px solid #2563eb; background: rgba(37, 99, 235, 0.05); margin: 4px 0; padding: 8px;',
    'template-parts'=> 'border: 1px solid #16a34a; background: rgba(22, 163, 74, 0.05); margin: 4px 0; padding: 8px;',
    'components'    => 'border: 1px solid #f59e0b; background: rgba(245, 158, 11, 0.05); margin: 4px 0; padding: 8px;',
    // 可继续新增其他目录的样式规则
];

2. 核心功能实现代码 #

接在上面的配置代码后添加即可：

if (WP_PARTIAL_DEBUG) {
    // 存储当前加载的partial标识信息
    add_filter('get_template_part_args', function($args, $slug, $name) {
        $args['_partial_slug'] = $slug;
        $args['_partial_name'] = $name;
        return $args;
    }, 10, 3);

    // 渲染partial时注入包裹逻辑
    add_filter('get_template_part_html', function($html, $slug, $name, $args) {
        // 拼接partial相对路径
        $partial_rel_path = $slug . ($name ? "-{$name}" : '') . '.php';
        // 获取本地文件绝对路径
        $partial_full_path = get_theme_file_path($partial_rel_path);
        // 转换为file协议本地文件链接
        $partial_file_link = 'file://' . str_replace('\\', '/', $partial_full_path);

        // 匹配目录对应样式，无匹配则使用默认样式
        $current_style = 'border: 1px solid #9333ea; background: rgba(147, 51, 234, 0.05); margin: 4px 0; padding: 8px;';
        foreach ($GLOBALS['partial_debug_styles'] as $dir => $style) {
            // PHP版本低于8.0时，将str_starts_with替换为strpos($slug, $dir) === 0即可兼容
            if (str_starts_with($slug, $dir)) {
                $current_style = $style;
                break;
            }
        }

        // 拼接带调试信息的包裹结构
        $wrapped_html = <<<HTML
<div style="{$current_style}">
    <div style="font-size: 12px; font-weight: 600; font-family: monospace; margin-bottom: 4px;">
        片段路径：{$partial_rel_path} | <a href="{$partial_file_link}" target="_blank">打开本地文件</a>
    </div>
    {$html}
</div>
HTML;
        return $wrapped_html;
    }, 10, 4);
}

3. 功能说明 #

• 全局开关：仅需修改WP_PARTIAL_DEBUG常量值即可一键启停所有调试逻辑，生产环境设为false无任何额外性能消耗
• 目录自定义样式：在$partial_debug_styles数组新增目录和对应样式规则即可，匹配优先级按数组顺序从上到下
• 片段名称展示：每个包裹顶部都会显示partial的相对路径，可直接识别片段来源
• 本地文件链接：点击「打开本地文件」可直接唤起本地编辑器打开对应PHP文件，部分浏览器需手动配置允许file协议链接跳转

内容的提问来源于stack exchange，提问作者Rad