Elementor 动态标签实战为 v4 原子组件Atomic Widgets从第三方插件接入动态数据源【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor动态标签Dynamic Tags让 Elementor 的组件属性在渲染时从 WordPress 数据文章标题、作者、特色图片等动态解析而非使用静态值。对于 v4 原子组件体系第三方插件只需注册一个沿用 Elementor 2.x 时代接口的传统legacy v3Tag类v4 桥接层bridge便会自动完成编辑器控件转换、属性 schema 扩展与渲染期解析——本文以 Elementor 官方技能文档 add-dynamic-tag/SKILL.md 为主线完整讲解注册流程、可转换控件清单、自动映射机制与验证方式读完即可在自己的插件中独立交付一个能被原子组件绑定、被 MCP 发现的动态标签。一、架构定位v3 注册表 v4 桥接插件只负责前者整个动态标签体系分两层见 动态标签概览层模块位置职责传统注册表modules/dynamic-tags/ 与 core/dynamic-tags/插件继承Tag/Data_Tag并在elementor/dynamic_tags/register钩子注册原子桥接层modules/atomic-widgets/dynamic-tags/把注册表适配为$$type: dynamic的 PropValue向属性 schema 注入dynamic联合类型渲染时经 transformer 管线解析关键结论技能文档的 Scope 声明完整交付物可以从第三方插件完成不需要修改 Elementor 核心。桥接内部类仅作为参考不可编辑Dynamic_Prop_Types_Mapping— 按类别自动注入 dynamic 联合Dynamic_Tags_Converter— 传统控件到原子 prop type 的转换Dynamic_Transformer— 渲染期解析ImportExport\Dynamic_Transformer— 导入导出期补全group字段唯一前提实验开关e_atomic_elementsAtomic Widgets处于激活状态。该实验会门控 atomic-widgets 模块及其全部依赖模块全局类、变量、组件、交互当前源码中其发布状态为 beta配置方法见 实验说明。一个可直接运行的参考插件位于 examples/example-plugin/其中 site-name-tag.php 演示了带 group、控件与 render 的完整标签。二、核心清单8 步完成一个原子可用的动态标签第 1 步注册 legacy v3 标签唯一强制的插件侧入口add_action( elementor/dynamic_tags/register, function ( $manager ) { $manager-register( new \MyPlugin\Tags\Store_Hours() ); } );从源码看该 action 由 core/dynamic-tags/manager.php 触发旧钩子elementor/dynamic_tags/register_tags自 3.5.0 起已弃用核心自身的 modules/dynamic-tags/module.php 也挂接同一钩子注册内置标签——插件注册的标签会与内置标签进入同一个注册表。第 2 步编写 Tag 类继承\Elementor\Core\DynamicTags\Tag需实现方法作用get_name()唯一标签 id如post-title后续作为 PropValue 的value.nameget_title()人类可读标题get_group()编辑器分组键get_categories()类别常量如\Elementor\Modules\DynamicTags\Module::TEXT_CATEGORYregister_controls()标签设置控件。当标签在原子编辑器中有 per-tag 设置时此方法是必需的render()渲染输出类别常量定义在 modules/dynamic-tags/module.phpTEXT_CATEGORYtext、URL_CATEGORYurl、IMAGE_CATEGORYimage、MEDIA_CATEGORY、POST_META_CATEGORY、GALLERY_CATEGORY、NUMBER_CATEGORY、COLOR_CATEGORY、DATETIME_CATEGORY、SVG_CATEGORY。控件type书写建议优先使用纯字符串text、select与\Elementor\Controls_Manager::TEXT等常量等价见 includes/managers/controls.php。可转换控件convertible controls共 9 种text、textarea、select、number、switcher、choose、query、date_time、media。这一清单在桥接层有两处对应实现dynamic-tags-editor-config.php 的convert_control_to_atomic()定义了控件类型到原子控件的映射表dynamic-tags-converter.php 的convert_control_to_prop_type()定义控件到 settings prop type 的映射例如choose→ 带enum的String_Prop_Typeswitcher→Boolean_Prop_Typemedia→ 带isDynamic标记的Image_Prop_Typequery→Query_Prop_Type。不在映射表内的控件default分支返回null会导致整个标签被原子编辑器排除——除非按第 5 步强制转换。此外从源码看 dynamic-tags-editor-config.php 要求每个控件必须同时具备name、section、label、default四个字段缺失即抛出异常并中止转换。第 3 步可选的自定义 group\Elementor\Plugin::$instance-dynamic_tags-register_group( my-plugin, [ title My Plugin ] );第 4 步Core 自动映射插件零工作对于标准标签例如TEXT_CATEGORY绑定到普通字符串 prop核心侧的Dynamic_Prop_Types_Mapping内部挂接了elementor/atomic-widgets/props-schema与elementor/atomic-widgets/styles/schema两个过滤器注册点在 dynamic-tags-module.php——插件不需要注册这些钩子。插件唯一需要动手的是非标准自定义 prop 类型见第 6 步。第 5 步不可转换控件 —— 强制转换而非整体排除覆写get_editor_config()注入force_convert_to_atomic truepublic function get_editor_config() { return array_merge( parent::get_editor_config(), [ force_convert_to_atomic true, ] ); }其源码行为在 dynamic-tags-editor-config.php未设置该标志时任一控件转换失败返回null或抛异常就使整个标签返回null被丢弃设置后不支持的控件被静默跳过continue标签整体仍进入原子编辑器。第 6 步自定义 prop 类型 —— 手动加入 Dynamic_Prop_Type 联合核心限制不存在公开的 category→schema 自动映射过滤器。自定义/非标准 prop 类型需要自己把Dynamic_Prop_Type加进联合类型$shape[to] Union_Prop_Type::make() -add_prop_type( String_Array_Prop_Type::make()-required() ) -add_prop_type( Dynamic_Prop_Type::make()-categories( [ \Elementor\Modules\DynamicTags\Module::TEXT_CATEGORY, ] ) ) -required();用-allowed_tag_names( [ … ] )收窄允许的标签名用-meta( Dynamic_Prop_Type::ignore() )让某 prop 类型退出动态绑定ignore()返回[ dynamic, false ]元组映射器在 dynamic-prop-types-mapping.php 中据此跳过。第 7 步动态 select 选项过滤器两个过滤器用于给原子编辑器里的 select 控件注入动态选项签名均为( $options, $control, $tag )返回 3 个参数elementor/atomic/dynamic-tags/select_control_options— 使用扁平options的 select 控件elementor/atomic/dynamic-tags/select_control_groups— 使用groups而非扁平options的 select 控件。add_filter( elementor/atomic/dynamic-tags/select_control_options, function ( $options, $control, $tag ) { if ( store-hours ( $tag[name] ?? ) ) { $options[custom:key] Custom label; } return $options; }, 10, 3 );在源码中dynamic-tags-editor-config.php 与 #L255分组控件会先把各组选项拍平后应用select_control_options过滤器做增删再按原分组重新切分最后应用select_control_groups过滤器——即两个过滤器对分组控件都会被触发。第 8 步验证标签可在编辑器atomicDynamicTags设置与 MCP/RESTlist-dynamic-tags中查到详见下文第四节的发现机制绑定保存为$$type: dynamic含name、group、settings渲染与导入导出核心已在 transformer 钩子上注册Dynamic_Transformer与ImportExport\Dynamic_Transformerdynamic-tags-module.php 挂接settings/transformers/register、styles/transformers/register、import/transformers/register、export/transformers/register——插件不需要注册这些只需注册 legacyTag与如需要手动 prop 联合。三、完整可运行示例Store_Hours 标签以下示例综合了官方示例 examples/add-dynamic-tag.md 与技能文档展示了注册、group、控件、强制转换与 select 过滤的完整形态?php use Elementor\Core\DynamicTags\Tag; use Elementor\Modules\DynamicTags\Module as DynamicTagsModule; add_action( elementor/dynamic_tags/register, function ( $manager ) { \Elementor\Plugin::$instance-dynamic_tags-register_group( my-plugin, [ title My Plugin, ] ); $manager-register( new \MyPlugin\Tags\Store_Hours() ); } ); class Store_Hours extends Tag { public function get_name() { return store-hours; } public function get_title() { return esc_html__( Store Hours, my-plugin ); } public function get_group() { return my-plugin; } public function get_categories() { return [ DynamicTagsModule::TEXT_CATEGORY ]; } protected function register_controls() { $this-add_control( field, [ type select, label Field, section content, default hours, options [ hours Hours, phone Phone, ], ] ); } public function render() { echo esc_html( $this-get_settings( field ) ); } }注意控件必须落在可转换类型集合内text、textarea、select、number、switcher、choose、query、date_time、media且每个控件都带上name、section、label、default。若你的标签含其他类型控件如url之外的自定义控件叠加第二节的force_convert_to_atomic覆写即可。保存后的绑定 JSON 形态绑定持久化到原子元素 JSON 中的结构group由解析器在落库前注入{ $$type: dynamic, value: { name: store-hours, group: my-plugin, settings: { field: hours } } }各字段的校验规则可直接在 dynamic-prop-type.php 中确认validate_value()要求namestring、groupstring、settingsarray三者齐备且标签类别与 prop 类型的categories约束存在交集settings还会按该标签的 props schema 做校验。渲染时Dynamic_Transformerdynamic-transformer.php只使用name与settings先经Render_Props_Resolver解析 settings再调用get_tag_data_content()产出最终内容——也就是说桥接层没有替代传统注册表每次原子绑定最终仍由Plugin::$instance-dynamic_tags渲染。动态绑定既可以是整个 prop 的根级值如title: { $$type: dynamic, value: { name: post-title, settings: {} } }也可以是嵌套对象内的单个字段如 image 的src详见 binding-propvalues.md。四、核心自动映射机制解析类别交集如何决定可绑定性Dynamic_Prop_Types_Mappingdynamic-prop-types-mapping.php是桥接层的核心其工作流程对传入 schema 中每个 prop type联合类型则展开成员判断其是否为Transformable_Prop_Type且未通过Dynamic_Prop_Type::ignore()元数据退出按 prop 类型映射到标签类别get_related_categories()Prop 类型映射类别Number_Prop_TypenumberSvg_Src_Prop_TypesvgImage_Src_Prop_TypeimageUrl_Prop_TypeurlEscaped_Html_Prop_Type/Html_V3_Prop_TypetextColor_Prop_TypecolorString_Prop_Type无 enumtext通过Dynamic_Tags_Module::instance()-get_dynamic_tag_names_by_categories( $categories )dynamic-tags-module.php取出类别有交集的已注册标签名生成Dynamic_Prop_Type::make()-categories( … )-allowed_tag_names( … )注入 schema。两个注入点组件 propselementor/atomic-widgets/props-schema样式 schema仅颜色字段elementor/atomic-widgets/styles/schema优先级 8。从 dynamic-prop-type.php 的to_json_schema()还能看到该类型面向 LLM/Agent 的 JSON Schemavalue.name在有allowed_tag_names时会被收窄为enum且 schema 描述明确指向elementor://dynamic-tags资源——这与第三节的“作者侧形态”一致作者人或 Agent只提交namesettingsgroup由三处解析器在持久化前从注册表注入编辑器内dynamicTagLLMResolver、PHP MCPDynamic_Tag_Llm_Resolver、导入导出ImportExport\Dynamic_Transformer。五、验证通过编辑器与 list-dynamic-tags 发现你的标签发现机制discovery.md提供三个读取通道通道标识WordPress Abilityelementor/list-dynamic-tagsMCP 工具名list-dynamic-tags编辑器内资源 URIelementor://dynamic-tags数据统一来自Dynamic_Tags_Editor_Config::get_tags()——即已做原子转换、控件可转换的标签集合。MCP 代理调用方式为POST /wp-json/elementor/v1/mcp-proxybody{ tool: list-dynamic-tags, input: {} }对应能力类 List_Dynamic_Tags_Ability 要求edit_posts权限。响应中每条含name用作value.name、label、categories、settings每个设置键的扁平 LLM schema不含group字段——绑定时也不要发送groupsettings 中的fallback键在 LLM schema 中被省略。编辑器侧dynamic-tags-module.php 在elementor/editor/localize_settings过滤器中把转换后的标签写入atomicDynamicTagstagsgroups。因此你的标签若在上述两处都不可见排查顺序应为注册钩子是否触发 →get_categories()是否非空 → 控件是否全部落在可转换集合或已设force_convert_to_atomic。六、外部插件交付路径小结项归属Tag子类 elementor/dynamic_tags/register插件负责register_group()可选分组插件负责标准 prop 类型的 dynamic 联合注入核心自动Dynamic_Prop_Types_Mapping自定义/非标准 prop 类型的 dynamic 联合插件在自己 prop type 中手动加Dynamic_Prop_Type无公开 category→schema 过滤器select 动态选项过滤器插件可选挂接渲染/导入导出 transformer核心已注册插件不碰延伸阅读均为仓库内文档动态标签扩展指南 — 公开 API 与钩子完整清单原子组件 Transformers 基础 —Dynamic_Transformer所在的 transformer 注册体系MCP 组合工作流 — Agent 场景下动态绑定的组合方式create-atomic-widget 技能 — 定义可接受动态绑定的 props【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考