EP04. "elementor-theme-builder-location 自定义主题位置注册"

首页 › AI 工具 › Claude · Skills · Elementor Skills · EP04

约 13 分钟· #EP04#Claude#Elementor Skills

Theme Builder 里能指定模板显示位置的只有 Header、Footer、Archive、Single 这四个内建位置，但自己的主题想在"内容前面加一段"或者留一个自定义侧栏插槽怎么办？——elementor-theme-builder-location 帮你注册一个新的位置，让它出现在 Theme Builder 的显示条件选择器里
这是 mekko-digital/elementor-skills 开源 skill 包的其中一个，Pro-only（Theme Builder 是 Elementor Pro 功能）
核心是两件事：注册位置（挂 hook + 定义参数），以及主题本身要真的触发那个 hook，两者缺一不可
前置知识：先看过 Overview 系列「Claude Code 是什么与新手上手」「进阶功能：Skills、Plugins 与 Routines」两篇；也建议知道 Elementor Pro Theme Builder 的显示条件（Display Conditions）怎么用

重点内容

这个 Skill 是做什么的

elementor-theme-builder-location 是脚手架型 skill，专门处理"给 Theme Builder 新增一个可指定模板的位置"这件事。它跟同一个包里其他偏"造内容"的 skill（elementor-widget-create、elementor-form-action）不一样——这个 skill 管的是"网站结构上的一个插槽"，不是控件或表单动作。

适合用在：

主题需要一个自定义的钩子位置（比如内容前的通栏、专属侧栏、循环后的区块），让客户能在 Theme Builder 后台指定要显示哪个模板
要覆盖内建核心位置的默认参数（比如把 header 改成允许 multiple）

不适合用在：

四个核心位置（header/footer/archive/single）本来就已经注册好，不要重复注册
single-post、single-page、search-results、error-404 这些其实是文档/条件的"类型"，不是"位置"——对它们调用 register_core_location() 会直接 wp_die()；但 search-results 本身作为一个全新位置去 register_location() 是合法的，不算重复
单纯排查一个已注册的位置为什么模板没显示出来——那是 elementor-debug-render 的工作

参考代码位置

Pro-only，源码：elementor-pro/modules/theme-builder/classes/locations-manager.php。四个核心位置的注册逻辑在 set_core_locations()（第 585 行起）。

实操示例：注册一个新位置

// ✅ GOOD：挂在 elementor/theme/register_locations 这个 hook 上
// 每次请求触发一次，见 register_locations() 第 139-155 行
add_action( 'elementor/theme/register_locations', function( $manager ) {
    $manager->register_location( 'before_content', [
        'label'           => __( 'Before Content', 'td' ),
        'multiple'        => false,                       // 允许同一个位置放多个模板吗？
        'public'          => true,                         // 要不要出现在 UI 的显示条件选择器？
        'edit_in_content' => true,                         // 在预览里能不能内联编辑？
        'hook'            => 'my_theme/before_content',    // 主题实际会触发的 action hook
        'remove_hooks'    => [],                            // 模板渲染后，从同一个 hook 上移除的回调名列表
    ] );
} );

参数默认值（locations-manager.php 第 532-552 行）：multiple=false、public=true、edit_in_content=true、hook='elementor/theme/' . $location（不传就用这个规则自动生成）。要覆盖核心位置的参数，用 register_core_location( $name, $args )，会合并进已存在的核心条目，不是重新注册一个新的。

触发输出

光注册位置不会自己出现内容——主题（或插件）要在对应的位置真正 do_action() 那个 hook，Location Manager 会以 priority 5 挂上去并执行渲染：

// ✅ GOOD：主题模板文件里实际触发这个 hook
do_action( 'my_theme/before_content' );

remove_hooks 参数指定的回调，会在某个模板成功渲染这个位置之后，从同一个 hook 上被移除——典型用法是"一旦 Elementor 接管了这个位置，就把主题原本挂在这里的默认输出去掉"，避免重复显示。

位置注册好之后

public=true 的位置会出现在 Theme Builder 的 Display Conditions 选择器里，逻辑在 elementor-pro/modules/theme-builder/classes/conditions-manager.php。模板通过这套显示条件绑定到你的位置——这跟 MCP 工具里 create-theme-template / set-template-conditions 走的是同一套逻辑面。

怎么安装

这个 skill 是 mekko-digital/elementor-skills 这个开源仓库打包的 8 个技能之一，用 Claude Code 的插件市场机制安装，装一次全部到位：

Claude Code（推荐：走插件市场）：

claude plugin marketplace add mekko-digital/elementor-skills
claude plugin install elementor-skills@elementor-skills-marketplace

Claude Code（手动方式）： 把 skills/elementor-theme-builder-location 这个文件夹复制到 ~/.claude/skills/（所有项目都能用）或专案底下的 ./.claude/skills/（只想在这个项目用）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传 skills/elementor-theme-builder-location 这个文件夹（打包成 zip，内含 SKILL.md）——插件市场机制是 Claude Code 专属的，Desktop 端目前只能手动上传单个 skill。

常见错误

❌ 注册了位置，但忘记在主题模板文件里真正 do_action() 那个 hook——Theme Builder 后台看得到这个位置、也能指定模板，但页面上什么都不会显示
❌ 对 single-post/single-page/search-results/error-404 调用 register_core_location()——这些是文档/条件类型不是位置，会直接触发 wp_die()
❌ 在 elementor/theme/register_locations 触发之前（太早的 hook）尝试注册——这个 hook 是在 template_redirect 阶段触发的（第 34 行），一定要挂在 init 或更晚的时机，Manager 还没准备好会注册失败
❌ 侧栏、内容前这类不在 the_content 里面的位置，edit_in_content 还设成 true——会导致内联编辑功能出错，这类位置应该设 false
📌 multiple 参数决定同一个位置能不能同时渲染好几个模板（循环项目、重复插槽这类场景才需要开），默认是 false 单模板
💡 位置注册好、真正接上真实站点之后，用同一个 skill 包里的 elementor-deploy-verify 断言 get_locations_manager()->get_locations() 里确实有这个位置，再交给别人用

Sources

官方文档：

elementor-skills（GitHub 仓库）— https://github.com/Mekko-Digital/elementor-skills
elementor-theme-builder-location SKILL.md — https://github.com/Mekko-Digital/elementor-skills/blob/main/skills/elementor-theme-builder-location/SKILL.md