EP03. "elementor-dynamic-tag 动态标签注册"

• 想让用户在任何控件的动态标签选择器里，绑定一个自己写的数据来源（比如某个 ACF 字段、自定义文章类型的 meta），Elementor 本身不知道这个数据从哪来——elementor-dynamic-tag 帮你把动态标签注册到位
• 这是 mekko-digital/elementor-skills 开源 skill 包的其中一个，覆盖免费版 Tag / Data_Tag 两种基类，以及 Pro 版的授权门槛写法
• 核心判断点只有一个：你的标签输出的是"渲染好的字符串"还是"结构化数据"，两者对应不同的基类，选错了控件用不了
• 前置知识：先看过 Overview 系列「Claude Code 是什么与新手上手」「进阶功能：Skills、Plugins 与 Routines」两篇；也建议知道 Elementor 后台动态标签选择器长什么样

重点内容

这个 Skill 是做什么的

elementor-dynamic-tag 是脚手架型 skill，按你要输出的数据类型（纯文字 vs 图片/链接/颜色这类结构化值），生成对应基类的动态标签骨架，并挂到正确的注册 hook 上。

适合用在：

• 要新增一个动态标签，让编辑器里任何控件都能通过"动态内容"图标绑定使用
• 数据来源是 ACF 字段、自定义文章类型 meta，或者其他非 Elementor 原生的数据
• 要做 Pro 风格、带授权门槛的动态标签

不适合用在：

• 不确定动态标签这个功能本身是免费版还是 Pro 版才有——先查 elementor-feature-lookup
• 要新增的是 widget 控件本身，不是数据绑定标签——那是 elementor-widget-create 的工作
• 排查一个已注册的动态标签为什么值不生效——那是 elementor-debug-render 的工作

两种基类，按输出形状选

Pro 另外提供两个授权门槛版本：ElementorPro\Modules\DynamicTags\Tags\Base\Tag（继承免费版 Tag）和对应的 Data_Tag，两者都用 License_Meta_Trait——只有标签要绑在 Pro 授权功能后面才需要这层。

必须覆写的方法（以免费版 Tag 为例）

来源：elementor-free/elementor/core/dynamic-tags/base-tag.php

• get_name() — 存进 __dynamic__ 映射表的 slug
• get_title() / get_group() / get_categories() — categories 数组要用 \Elementor\Modules\DynamicTags\Module::*_CATEGORY 常量（TEXT、URL、COLOR、IMAGE、GALLERY、MEDIA、POST_META、NUMBER、KEY_VALUE_ARRAY 等）
• render()（Tag 用）— echo 一个字符串
• get_value( array $options = [] )（Data_Tag 用）— 回传符合该分类形状的值（例如 IMAGE 分类要回传 [ 'id' => ..., 'url' => ... ]）
• protected function register_controls() — 定义动态标签弹出面板里的设置项

实操示例：注册标签与分组

// ✅ GOOD：先注册一个分组（可选）
add_action( 'elementor/dynamic_tags/register', function( $dynamic_tags ) {
    $dynamic_tags->register_group( 'my-group', [ 'title' => __( 'My Group', 'td' ) ] );
} );

// ✅ GOOD：注册标签，挂在 elementor/dynamic_tags/register 这个 hook
// 这个 hook 取代了已废弃的 elementor/dynamic_tags/register_tags
// （见 core/dynamic-tags/manager.php:280-302）
add_action( 'elementor/dynamic_tags/register', function( $dynamic_tags ) {
    require_once __DIR__ . '/tags/my-tag.php';
    $dynamic_tags->register( new \My_Plugin\Tags\My_Tag() );
} );

4.0 Atomic 架构的差异

Atomic widget 用的是另一条动态标签管线（modules/atomic-widgets/dynamic-tags/）。经典标签仍然能用，但会经过 Dynamic_Tags_Converter 自动适配；要专门给 atomic widget 写新标签，得看 dynamic-prop-type.php 和 dynamic-tags-schemas.php 这两个文件。

Pro 标签分组一览

Pro 内建的标签分组有 AUTHOR、POST、COMMENTS、SITE、ARCHIVE、MEDIA、ACTION、WOOCOMMERCE（elementor-pro/modules/dynamic-tags/module.php:17-31）。ACF / Pods / Toolset 相关组件是条件注册的——只有对应插件存在，且 Pro 授权功能可用时才会出现。

怎么安装

这个 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-dynamic-tag 这个文件夹复制到 ~/.claude/skills/（所有项目都能用）或专案底下的 ./.claude/skills/（只想在这个项目用）。

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

常见错误

• ❌ IMAGE / URL / COLOR / GALLERY 这类要结构化值的分类，却继承了 Tag 用 render() 输出 HTML 字符串——控件收到的形状不对，标签在对应控件上根本选不出来
• ❌ 元数据驱动（meta-driven）的标签，本该用 Data_Tag + POST_META 分类，却直接在 Tag::render() 里 echo 这个 meta 值——数据形状跟消费方期待的不一致
• ❌ 忘记 get_categories() 决定了这个标签会出现在哪些控件的动态选择器里——TEXT 分类的标签不会出现在媒体控件上，选错分类等于标签"消失了"
• 📌 用了已废弃的 elementor/dynamic_tags/register_tags hook——要改用现在的 elementor/dynamic_tags/register
• 💡 不确定动态标签这个功能算免费版还是 Pro 版，先查 elementor-feature-lookup，不要凭印象猜
• 💡 标签注册到 elementor/dynamic_tags/register 之后，就能在控件上设置，也能被 MCP 工具（list-dynamic-tags / set-dynamic-tag）识别到；要在真实站点上安装并断言 dynamic_tags->get_tag_info('<name>') 存在，用同一个 skill 包里的 elementor-deploy-verify

Sources

官方文档：

1. elementor-skills（GitHub 仓库）— https://github.com/Mekko-Digital/elementor-skills
2. elementor-dynamic-tag SKILL.md — https://github.com/Mekko-Digital/elementor-skills/blob/main/skills/elementor-dynamic-tag/SKILL.md