Elementor NestedTabs 模块深度解析基于 Nested Elements 基础设施构建可嵌套标签页组件【免费下载链接】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本文以 Elementor 仓库中的modules/nested-tabs模块及其官方指南 docs/modules/nested-tabs/index.md 为核心完整拆解一套“元素嵌套元素”Nested Elements机制下的标签页组件是如何落地的从 PHP 侧的模块与 Widget 注册、编辑器侧的元素类型注册与自定义 View到前端 Handler 的标签切换逻辑、CSS 变量样式体系与局部数据绑定渲染。读完后你将掌握在 Elementor 中扩展一个支持容器嵌套、局部重渲染的复合组件所需的完整链路。一、模块定位NestedTabs 是 Nested Elements 基础设施的“活例子”在理解 NestedTabs 之前需要先厘清它与底层模块NestedElements的关系。按指南的表述Nested Elements 是所有嵌套元素的基础模块包含创建嵌套元素所需的基础设施而NestedTabs只是基于这套基础设施实现“嵌套标签页”的具体模块。换句话说传统 Elementor Widget 内部只能放 Repeater 文本/HTML 内容无法放入真正的可编辑元素NestedElements 提供了“父元素内嵌子元素Container”的 Model 支持后NestedTabs 才能把每个 Tab 的内容做成独立的 Container。这也是该指南存在的原因——它用 NestedTabs 作为完整示例手把手演示如何编写一个 Nested 模块。指南给出的模块文件结构如下对应仓库modules/nested-tabs/目录tabs-v2即 modules/nested-tabs/ ├── assets/ │ ├── js/ │ │ ├── editor/ # 编辑器脚本 │ │ │ ├── index.js # 编辑器首个加载文件负责加载模块 │ │ │ ├── module.js # 注册 widget 到 elementsManager需等待 NestedElements 就绪 │ │ │ ├── nested-tabs.js # 编辑器侧的 widget 定义 │ │ │ └── views/ # 自定义 ViewReact/Backbone 视图 │ │ └── frontend/ │ │ └── handlers/ │ │ └── nested-tabs.js # 前端交互 Handler │ └── scss/ │ └── frontend.scss # 全部前端样式CSS 变量体系 ├── widgets/ │ └── nested-tabs.php # 后端 Widget 注册 └── module.php # 模块入口控制实验开关、注册编辑器脚本三条主流程指南 “The flow” 部分Backendmodule.php 通过get_widgets()注册 Widget由widgets/nested-tabs.php实现并负责向编辑器注入脚本Editorassets/js/editor/index.js→module.js→ 通过elementor.elementsManager.registerElementType()注册 widget 及其自定义 ViewFrontend加载 Handler nested-tabs.js 与样式 frontend.scss。从源码结构看模块的激活条件由 module.php 中的is_active()决定public static function is_active() { return Plugin::$instance-experiments-is_feature_active( container ); }即NestedTabs 仅在 Flexbox 容器container实验启用时生效这印证了指南“Attention needed”一节中的结论该 Widget 只配合 Container 工作。二、后端模块注册module.php 的正确打开方式指南首先示范了“如何注册一个模块”。嵌套模块的核心前提是声明对基础模块的依赖use Elementor\Modules\NestedElements\Module as NestedElementsModule; public static function get_experimental_data() { return [ name nested-tabs, title esc_html__( Nested Tab, elementor ), description esc_html__( Nested Tabs, elementor ), release_status Experiments_Manager::RELEASE_STATUS_ALPHA, default Experiments_Manager::STATE_INACTIVE, dependencies [ NestedElementsModule::class ], // 声明依赖 NestedElements ]; }指南强调两点依赖声明是必须的——因为嵌套元素需要不同的Model才能承载子元素向编辑器 enqueue 脚本也是必须的——嵌套 widget 依赖嵌套基础设施的编辑器组件。当前仓库中 module.php 的完整实现如下可以对照理解上述要点的落地形态class Module extends \Elementor\Core\Base\Module { public function get_name() { return nested-tabs; } public function __construct() { parent::__construct(); // 前端样式注册编译产物为 widget-nested-tabs.min.css add_action( elementor/frontend/after_register_styles, [ $this, register_styles ] ); // 编辑器脚本依赖 nested-elements 脚本先行加载 add_action( elementor/editor/before_enqueue_scripts, function () { wp_enqueue_script( $this-get_name(), $this-get_js_assets_url( $this-get_name() ), [ nested-elements, ], ELEMENTOR_VERSION, true ); } ); } public function register_styles() { $direction_suffix is_rtl() ? -rtl : ; $has_custom_breakpoints Plugin::$instance-breakpoints-has_custom_breakpoints(); wp_register_style( widget-nested-tabs, $this-get_frontend_file_url( widget-nested-tabs{$direction_suffix}.min.css, $has_custom_breakpoints ), [ elementor-frontend ], $has_custom_breakpoints ? null : ELEMENTOR_VERSION ); } }几个值得注意的实现细节编辑器脚本依赖数组中显式列出nested-elements保证基础模块的编辑器组件先于本模块加载——这是指南中“wait for NestedElements module to be loaded first”的工程化体现样式产物按 RTL/LTR 与自定义断点区分register_styles()的注释说明构建时/modules/nested-tabs/assets/scss/frontend.scss会被编译为/assets/css/widget-nested-tabs.min.cssWidget 的自动注册由基类完成core/base/module.php 中get_widgets()返回的类名会按命名空间拼接\Widgets\前缀后自动require并注册因此模块里只需protected function get_widgets() { return [ NestedTabs ]; // 自动定位到 widgets/nested-tabs.php }三、Widget 注册widgets/nested-tabs.php 与四个关键抽象方法Widget 侧的实现文件是 widgets/nested-tabs.php其类声明为use Elementor\Modules\NestedElements\Base\Widget_Nested_Base; class NestedTabs extends Widget_Nested_Base { ... }指南指出继承Widget_Nested_Base后有几个必须关注的方法作用与 NestedTabs 中的取值如下方法作用NestedTabs 的取值get_default_children_elements()Widget 创建时内置的初始子元素当前为 3 个默认 ContainerTab #1~Tab #3get_default_repeater_title_setting_key()前端用于$e.run( document/elements/settings )更新子项标题的 setting keytab_titleget_default_children_title()新增子元素时的标题模板%d为序号占位Tab #%dget_default_children_placeholder_selector()子元素插入位置的 CSS 选择器返回null表示追加到元素末尾.e-n-tabs-contentget_html_wrapper_class()Widget 外层包装类名elementor-widget-n-tabs当前仓库中的实现注意默认子元素由指南示例的 2 个 Tab 扩展为 3 个protected function tab_content_container( int $index ) { return [ elType container, settings [ _title sprintf( __( Tab #%d, elementor ), $index ), content_width full, ], ]; } protected function get_default_children_elements() { return [ $this-tab_content_container( 1 ), $this-tab_content_container( 2 ), $this-tab_content_container( 3 ), ]; } protected function get_default_repeater_title_setting_key() { return tab_title; } protected function get_default_children_title() { return esc_html__( Tab #%d, elementor ); } protected function get_default_children_placeholder_selector() { return .e-n-tabs-content; }渲染结构与 ARIA 语义render()widgets/nested-tabs.php#L1165-L1215输出的 DOM 结构是前后端协作的契约外层.e-n-tabs携带data-widget-number用于前端 Handler 定位同一 Widget 实例标题区.e-n-tabs-headingroletablist内每个 Tab 是一个button带roletab、aria-selected、aria-controls、data-tab-index等属性内容区.e-n-tabs-content内通过print_child()打印子 Container并给容器包装器加上roletabpanel、ide-n-tab-content-{widgetNumber}{index}、data-tab-index及首项的e-active类。print_child()widgets/nested-tabs.php#L1130-L1152借助elementor/frontend/container/should_render过滤器在打印子容器时动态注入上述 ARIA 属性保证标题与内容区一一对应。编辑器预览模板方面get_initial_config()声明了改进版 Repeater 支持protected function get_initial_config(): array { return array_merge( parent::get_initial_config(), [ support_improved_repeaters true, target_container [ .e-n-tabs-heading ], node button, ] ); }这意味着编辑器内 Repeater 行Tab 标题按钮的增删改会由框架接管局部更新而不是整件 Widget 重渲染——这一点的性能意义见第七节。控件与样式设置register_controls()注册了两组内容内容区tabs采用Control_Nested_Repeater控件而非普通 Repeater字段包括tab_title支持动态标签、tab_icon/tab_icon_active、element_id另有方向tabs_direction、对齐tabs_justify_horizontal/tabs_justify_vertical、标题间距/内边距、水平滚动horizontal_scroll以及断点选择breakpoint_selector控制 Tab 在哪个断点切换为竖向手风琴布局等控件。样式区几乎全部通过 CSS 变量输出如--n-tabs-title-color、--n-tabs-heading-justify-content选择器则区分正常/悬停/激活三态以及触摸设备[data-touch-modefalse|true]。四、编辑器侧注册链路index.js → module.js → nested-tabs.js第一步等待基础模块就绪编辑器入口 assets/js/editor/index.js 是“第一个被加载的文件”其职责是等待 NestedElements 编辑器组件就绪后再动态加载本模块elementorCommon.elements.$window.on( elementor/nested-element-type-loaded, async () { new ( await import( ../editor/module ) ).default(); } );指南中展示的更早版本监听elementor/init-components事件并await elementor.modules.nestedElements本质相同本模块的加载必须排在 NestedElements 之后否则registerElementType时依赖的嵌套 Model 尚不存在。第二步注册元素类型assets/js/editor/module.js 只做一件事import NestedTabs from ./nested-tabs; export default class Module { constructor() { elementor.elementsManager.registerElementType( new NestedTabs() ); } }指南解释了为什么要把元素注册进elementsManager这样才能自定义View、EmptyView或Model如果只需要最小嵌套能力一个getModel()返回嵌套 Model 的类即可// 最小要求让 Model 支持嵌套元素 export class YourWidgetName extends elementor.modules.elements.Widget { getModel() { // 包含嵌套元素支持的基础 Model return $e.components.get( nested-elements/nested-repeater ).exports.NestedModelBase; } }当前仓库的 nested-tabs.js 则采用基类 自定义 View 的形式import View from ./views/view; export class NestedTabs extends elementor.modules.elements.types.NestedElementBase { getType() { return nested-tabs; // 与后端 get_name() 保持一致 } getView() { return View; } } export default NestedTabs;指南还给出了一个更完整的注册范例供需要自定义 Empty View / Model 的场景参考import View from ./views/view; // 处理点击的自定义 View import EmptyView from ./views/empty; // 处理空状态的自定义 Empty ViewReact 组件 export class NestedTabs extends elementor.modules.elements.types.Base { getType() { return nested-tabs; // 后端注册时的 widget 类型名 } getView() { // 自定义 View 应继承 $e.components.get( nested-elements/nested-repeater ).exports.NestedViewBase return View; } getEmptyView() { // 自定义空状态视图应为 React 组件 return EmptyView; } getModel() { // 应继承 NestedRepeaterModel此场景无需自定义 Model返回默认 return $e.components.get( nested-elements/nested-repeater ).exports.NestedModelBase; } }五、自定义 Viewview.js 与可选的 React 空状态视图编辑器 View把子 Container“挂”成 Tab 面板当前仓库的 views/view.js 继承嵌套视图基类负责在编辑器画布中把子元素包装为 Tab 内容export default class View extends $e.components.get( nested-elements ).exports.NestedView { filter( child, index ) { child.attributes.dataIndex index 1; return true; } onAddChild( childView ) { const widgetNumber childView._parent.$el.find( .e-n-tabs )[ 0 ]?.dataset.widgetNumber, index childView.model.attributes.dataIndex, tabId childView._parent.$el.find( .e-n-tab-title[data-tab-index${ index }] )?.attr( id ); childView.$el.attr( { id: e-n-tab-content- widgetNumber index, role: tabpanel, aria-labelledby: tabId, data-tab-index: index, style: --n-tabs-title-order: index ;, } ); // 首次加载时把第一个 Tab 置为激活 const isInitialLoad elementor.previewView.isBuffering; if ( isInitialLoad 1 index ) { childView.$el.addClass( e-active ); } } }逻辑与后端print_child()注入的属性一一对应e-n-tab-content-{n}{i}、aria-labelledby、data-tab-index保证编辑器 DOM 与前端 DOM 的结构契约一致。指南同时说明如果没有自定义逻辑直接使用默认的NestedViewBase即可View 属于可选增强。可选进阶视图Empty View 与预设选择指南详细描述了三个可选的 React 视图对应文档树中的views/目录用于优化“向 Tab 容器添加内容”的交互。说明当前仓库views/目录中仅保留 view.js以下empty.js/add-section-area.js/select-preset.js为指南中的进阶视图示例可作为扩展嵌套组件空状态交互的参考实现。Empty ViewReact 组件Widget 为空时渲染决定显示“添加区”还是“预设选择”import { useState } from react; import AddSectionArea from ./add-section-area; import SelectPreset from ./select-preset; export default function Empty( props ) { const [ isRenderPresets, setIsRenderPresets ] useState( false ); props { ...props, setIsRenderPresets }; return isRenderPresets ? SelectPreset {...props} / : AddSectionArea {...props} /; } Empty.propTypes { container: PropTypes.object.isRequired, };AddSectionArea可拖拽的添加区通过 jQueryhtml5Droppable使容器接受拖入的 Widgetimport { useEffect, useRef } from react; export default function AddSectionArea( props ) { const addAreaElementRef useRef(), containerHelper elementor.helpers.container, args { importOptions: { target: props.container } }; useEffect( () { if ( props.container.view.isDisconnected() ) { return; } const $addAreaElementRef jQuery( addAreaElementRef.current ), defaultDroppableOptions props.container.view.getDroppableOptions(); defaultDroppableOptions.placeholder false; defaultDroppableOptions.items .elementor-add-section-inner; defaultDroppableOptions.hasDraggingOnChildClass elementor-dragging-on-child; $addAreaElementRef.html5Droppable( defaultDroppableOptions ); return () { $addAreaElementRef.html5Droppable( destroy ); }; }, [] ); return ( div classNameelementor-add-section onClick{() containerHelper.openEditMode( props.container )} ref{addAreaElementRef} div classNameelementor-add-section-inner div classNamee-view elementor-add-new-section button typebutton classNameelementor-add-section-area-button elementor-add-section-button aria-label{__( Add new container, elementor )} onClick{() props.setIsRenderPresets( true )} i classNameeicon-plus aria-hiddentrue / /button div classNameelementor-add-section-drag-title {__( Drag widgets here., elementor )} /div /div /div /div ); }SelectPreset点击“”后列出子容器的结构预设通过elementor.helpers.container.createContainerFromPreset()按预设创建容器export default function SelectPreset( props ) { const containerHelper elementor.helpers.container, onPresetSelected ( preset, container ) { containerHelper.createContainerFromPreset( preset, container, { createWrapper: false, } ); }; return ( button typebutton classNameelementor-add-section-close aria-label{ __( Close, elementor ) } onClick{() props.setIsRenderPresets( false )} i classNameeicon-close aria-hiddentrue/ /button div classNamee-view e-con-select-preset div classNamee-con-select-preset__title{__( Select your Structure, elementor )}/div div classNamee-con-select-preset__list { elementor.presetsFactory.getContainerPresets().map( ( preset ) ( button typebutton classNamee-con-preset >export default class YourCustomHandler extends elementorModules.frontend.handlers.BaseNestedTabs { // 在此创建自定义 Handler }而当前仓库的 nested-tabs.js 是一套完整实现值得逐块拆解基于data-widget-number的选择器体系getDefaultSettings()handlers/nested-tabs.js#L49-L78利用 Widget 渲染时输出的data-widget-number构造精确选择器避免多实例互相干扰selectors: { widgetContainer: [data-widget-number${ widgetNumber }], tabTitle: [aria-controls*e-n-tab-content-${ widgetNumber }], tabTitleText: [data-tab-title-id*e-n-tab-title-${ widgetNumber }] .e-n-tab-title-text, tabContent: [data-widget-number${ widgetNumber }] .e-n-tabs-content .e-con, headingContainer: [data-widget-number${ widgetNumber }] .e-n-tabs-heading, activeTabContentContainers: [id*e-n-tab-content-${ widgetNumber }].e-active, }, classes: { active: e-active }, dataAttributes: { tabIndex: data-tab-index }, ariaAttributes: { titleStateAttribute: aria-selected, activeTitleSelector: [aria-selectedtrue], },这些选择器直接依赖第三节所述的渲染契约标题的aria-controls指向e-n-tab-content-{n}{i}内容的data-tab-index与标题一致——前后端共享同一套命名规则是嵌套组件能稳定工作的关键。激活/切换逻辑activateDefaultTab()初始化时读取编辑设置activeItemIndex默认 1用无动画的show/hide切换以避免跳转随后给容器加e-activated类activateTab( tabIndex )设置标题的aria-selected/tabindex给内容加e-active并show()动画完成回调中触发elementor/nested-tabs/activate事件供 Swiper 重初始化、Motion FX 与背景视频重算监听changeActiveTab( tabIndex, fromUser )统一入口。特别地编辑器中用户点击 Tab 标题时并不直接切换 UI而是调用$e.run( document/repeater/select )让编辑器的 Repeater 选择机制接管——这是“编辑器行为与前端行为解耦”的典型做法changeActiveTab( tabIndex, fromUser false ) { if ( fromUser this.isEdit this.isElementInTheCurrentDocument() ) { return window.top.$e.run( document/repeater/select, { container: elementor.getContainer( this.$element.attr( data-id ) ), index: parseInt( tabIndex ), } ); } // ... 去激活旧 Tab、激活新 Tab手风琴模式走 activateMobileTab }移动端手风琴与触摸模式指南“Known issues”一节指出NestedTabs 为了与旧版 Tabs 视觉一致而子内容在 Nested Elements 机制下是独立的 Container需要手动对齐 DOM 结构。指南展示的早期方案是在onInit()中为每个.e-container手工注入一个e-collapse移动标题当前仓库的演进而来的做法是data-touch-mode属性 手风琴检测setTouchMode()handlers/nested-tabs.js#L383-L400在移动端设备或触摸设备上给容器设置data-touch-modetrue样式选择器据此切换悬停效果isAccordionVersion()通过检测.e-n-tabs-heading的display是否变为contents判断当前是否处于竖向手风琴布局activateMobileTab()带 10ms 延时注释说明是为兼容 Apple 设备上“先关后开”的动画时序并在编辑器中把激活标题滚动到视口中心。子元素重排后的索引同步由于 Tab 标题是 Repeater 行、Tab 内容是独立 Container两者序号必须严格一致。updateIndexValues()handlers/nested-tabs.js#L427-L452在elementor/nested-container/atomic-repeater事件触发后遍历所有标题与内容重写id、aria-controls、data-tab-index、--n-tabs-title-order及data-binding-index保证增删 Tab 后 DOM 引用依然正确。此外还有两个实用细节reInitSwipers()在切换到新 Tab 时重新初始化其中的 Swiper修复隐藏容器内初始化导致的 autoplay 异常bindEvents()中订阅了elementor/nested-elements/activate-by-keyboard事件以支持键盘导航懒加载nested-title-keyboard-handler模块。七、样式体系CSS 变量 全局样式的默认值补偿frontend.scss 是全部前端视觉的来源其核心策略是几乎所有外观都通过--n-tabs-*CSS 变量表达Widget 控件只负责改变量取值。文件开头的变量默认值frontend.scss#L46-L95即组件的“设计令牌”.elementor-widget-n-tabs { --n-tabs-color-accent-fallback: #61CE70; --n-tabs-direction: column; --n-tabs-heading-direction: row; --n-tabs-heading-justify-content: center; --n-tabs-title-color: var(--e-global-color-secondary, var(--n-tabs-color-secondary-fallback)); --n-tabs-title-background-color-hover: var(--e-global-color-accent, var(--n-tabs-color-accent-fallback)); --n-tabs-title-font-size: 1rem; --n-tabs-title-transition: 0.3s; // ... 共 40 个变量 }值得注意的是默认值中已经引用了--e-global-color-accent等全局 Kit 变量并带 fallback——这正是指南“Default global values should be set in widget CSS”这一已知问题的直接体现嵌套元素机制依赖 CSS 变量而编辑器/后端的机制对此支持有限因此需要在 Widget 自身 CSS 中手工接入全局颜色/字体变量例如指南给出的补偿写法--n-tabs-title-color: var(--e-global-color-primary); --n-tabs-title-active-color: var(--e-global-color-accent); --n-tabs-title-typography-font-family: var(--e-global-typography-primary-font-family); --n-tabs-title-typography-font-size: initial; --n-tabs-title-typography-font-weight: var(--e-global-typography-primary-font-weight);配合 module.php 中register_styles()的 RTL/断点产物分发机制构成了完整的样式链路。八、局部数据渲染Partial Render只更新变化的 DOM指南最后介绍的一个关键性能特性是partial render局部数据渲染。问题背景是默认渲染机制每次都会重新渲染全部子内容对 NestedTabs 而言仅修改某个tab_title就会触发整个子层级重渲染性能损耗明显。新嵌套基础设施允许在已知 DOM 结构的前提下通过data-binding属性声明“只更新这个节点”Repeater 项的绑定声明element >element >view.addRenderAttribute( tab-title-text, { class: [ e-n-tab-title-text ], data-binding-type: repeater-item, data-binding-repeater-name: tabs, data-binding-setting: [ tab_title, element_id ], data-binding-index: tabCount, data-binding-config: JSON.stringify({ element_id: { attr: id, selector: button, editType: attribute }, tab_title: { editType: text }, }), }, null, true );即修改tab_title只更新该span的文本修改element_id只更新标题button的id属性其余 DOM 与子 Container 完全不受影响。九、已知约束与设计权衡小结结合指南“Attention needed / Known issues”一节与当前源码可以归纳出 NestedTabs 模块的三个核心约束与对策仅配合 Container 工作is_active()与show_in_panel()都依赖container实验module.php、widgets/nested-tabs.php#L53-L55因为子元素必须是 Container移动端布局需手工对齐子内容是独立 Container 后无法再像旧版 Tabs 那样硬编码任意内部结构早期靠onInit()注入e-collapse标题解决当前演进为data-touch-mode 手风琴检测setTouchMode/isAccordionVersion全局样式值需手工桥接嵌套机制使用 CSS 变量而编辑器/后端机制支持有限默认值包括全局 Kit 变量引用与 fallback必须在frontend.scss的 Widget CSS 中显式声明。十、关键文件速查关注点文件官方指南本文核心依据docs/modules/nested-tabs/index.md基础嵌套元素模块文档docs/modules/nested-elements/index.md模块入口激活条件/脚本/样式注册modules/nested-tabs/module.php模块自动注册 Widget 机制core/base/module.php后端 Widget抽象方法/控件/渲染/数据绑定modules/nested-tabs/widgets/nested-tabs.php编辑器入口 / 注册 / 元素类型index.js、module.js、nested-tabs.js编辑器自定义 Viewmodules/nested-tabs/assets/js/editor/views/view.js前端 Handlermodules/nested-tabs/assets/js/frontend/handlers/nested-tabs.js前端样式CSS 变量体系modules/nested-tabs/assets/scss/frontend.scss这套“PHP 注册 编辑器元素类型 前端 Handler CSS 变量 局部数据绑定”的组合是 Elementor 中扩展任何嵌套类组件如嵌套 Accordion 等 NestedElements 家族成员可复用的标准范式。【免费下载链接】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），仅供参考
Elementor NestedTabs 模块深度解析：基于 Nested Elements 基础设施构建可嵌套标签页组件
Elementor NestedTabs 模块深度解析基于 Nested Elements 基础设施构建可嵌套标签页组件【免费下载链接】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本文以 Elementor 仓库中的modules/nested-tabs模块及其官方指南 docs/modules/nested-tabs/index.md 为核心完整拆解一套“元素嵌套元素”Nested Elements机制下的标签页组件是如何落地的从 PHP 侧的模块与 Widget 注册、编辑器侧的元素类型注册与自定义 View到前端 Handler 的标签切换逻辑、CSS 变量样式体系与局部数据绑定渲染。读完后你将掌握在 Elementor 中扩展一个支持容器嵌套、局部重渲染的复合组件所需的完整链路。一、模块定位NestedTabs 是 Nested Elements 基础设施的“活例子”在理解 NestedTabs 之前需要先厘清它与底层模块NestedElements的关系。按指南的表述Nested Elements 是所有嵌套元素的基础模块包含创建嵌套元素所需的基础设施而NestedTabs只是基于这套基础设施实现“嵌套标签页”的具体模块。换句话说传统 Elementor Widget 内部只能放 Repeater 文本/HTML 内容无法放入真正的可编辑元素NestedElements 提供了“父元素内嵌子元素Container”的 Model 支持后NestedTabs 才能把每个 Tab 的内容做成独立的 Container。这也是该指南存在的原因——它用 NestedTabs 作为完整示例手把手演示如何编写一个 Nested 模块。指南给出的模块文件结构如下对应仓库modules/nested-tabs/目录tabs-v2即 modules/nested-tabs/ ├── assets/ │ ├── js/ │ │ ├── editor/ # 编辑器脚本 │ │ │ ├── index.js # 编辑器首个加载文件负责加载模块 │ │ │ ├── module.js # 注册 widget 到 elementsManager需等待 NestedElements 就绪 │ │ │ ├── nested-tabs.js # 编辑器侧的 widget 定义 │ │ │ └── views/ # 自定义 ViewReact/Backbone 视图 │ │ └── frontend/ │ │ └── handlers/ │ │ └── nested-tabs.js # 前端交互 Handler │ └── scss/ │ └── frontend.scss # 全部前端样式CSS 变量体系 ├── widgets/ │ └── nested-tabs.php # 后端 Widget 注册 └── module.php # 模块入口控制实验开关、注册编辑器脚本三条主流程指南 “The flow” 部分Backendmodule.php 通过get_widgets()注册 Widget由widgets/nested-tabs.php实现并负责向编辑器注入脚本Editorassets/js/editor/index.js→module.js→ 通过elementor.elementsManager.registerElementType()注册 widget 及其自定义 ViewFrontend加载 Handler nested-tabs.js 与样式 frontend.scss。从源码结构看模块的激活条件由 module.php 中的is_active()决定public static function is_active() { return Plugin::$instance-experiments-is_feature_active( container ); }即NestedTabs 仅在 Flexbox 容器container实验启用时生效这印证了指南“Attention needed”一节中的结论该 Widget 只配合 Container 工作。二、后端模块注册module.php 的正确打开方式指南首先示范了“如何注册一个模块”。嵌套模块的核心前提是声明对基础模块的依赖use Elementor\Modules\NestedElements\Module as NestedElementsModule; public static function get_experimental_data() { return [ name nested-tabs, title esc_html__( Nested Tab, elementor ), description esc_html__( Nested Tabs, elementor ), release_status Experiments_Manager::RELEASE_STATUS_ALPHA, default Experiments_Manager::STATE_INACTIVE, dependencies [ NestedElementsModule::class ], // 声明依赖 NestedElements ]; }指南强调两点依赖声明是必须的——因为嵌套元素需要不同的Model才能承载子元素向编辑器 enqueue 脚本也是必须的——嵌套 widget 依赖嵌套基础设施的编辑器组件。当前仓库中 module.php 的完整实现如下可以对照理解上述要点的落地形态class Module extends \Elementor\Core\Base\Module { public function get_name() { return nested-tabs; } public function __construct() { parent::__construct(); // 前端样式注册编译产物为 widget-nested-tabs.min.css add_action( elementor/frontend/after_register_styles, [ $this, register_styles ] ); // 编辑器脚本依赖 nested-elements 脚本先行加载 add_action( elementor/editor/before_enqueue_scripts, function () { wp_enqueue_script( $this-get_name(), $this-get_js_assets_url( $this-get_name() ), [ nested-elements, ], ELEMENTOR_VERSION, true ); } ); } public function register_styles() { $direction_suffix is_rtl() ? -rtl : ; $has_custom_breakpoints Plugin::$instance-breakpoints-has_custom_breakpoints(); wp_register_style( widget-nested-tabs, $this-get_frontend_file_url( widget-nested-tabs{$direction_suffix}.min.css, $has_custom_breakpoints ), [ elementor-frontend ], $has_custom_breakpoints ? null : ELEMENTOR_VERSION ); } }几个值得注意的实现细节编辑器脚本依赖数组中显式列出nested-elements保证基础模块的编辑器组件先于本模块加载——这是指南中“wait for NestedElements module to be loaded first”的工程化体现样式产物按 RTL/LTR 与自定义断点区分register_styles()的注释说明构建时/modules/nested-tabs/assets/scss/frontend.scss会被编译为/assets/css/widget-nested-tabs.min.cssWidget 的自动注册由基类完成core/base/module.php 中get_widgets()返回的类名会按命名空间拼接\Widgets\前缀后自动require并注册因此模块里只需protected function get_widgets() { return [ NestedTabs ]; // 自动定位到 widgets/nested-tabs.php }三、Widget 注册widgets/nested-tabs.php 与四个关键抽象方法Widget 侧的实现文件是 widgets/nested-tabs.php其类声明为use Elementor\Modules\NestedElements\Base\Widget_Nested_Base; class NestedTabs extends Widget_Nested_Base { ... }指南指出继承Widget_Nested_Base后有几个必须关注的方法作用与 NestedTabs 中的取值如下方法作用NestedTabs 的取值get_default_children_elements()Widget 创建时内置的初始子元素当前为 3 个默认 ContainerTab #1~Tab #3get_default_repeater_title_setting_key()前端用于$e.run( document/elements/settings )更新子项标题的 setting keytab_titleget_default_children_title()新增子元素时的标题模板%d为序号占位Tab #%dget_default_children_placeholder_selector()子元素插入位置的 CSS 选择器返回null表示追加到元素末尾.e-n-tabs-contentget_html_wrapper_class()Widget 外层包装类名elementor-widget-n-tabs当前仓库中的实现注意默认子元素由指南示例的 2 个 Tab 扩展为 3 个protected function tab_content_container( int $index ) { return [ elType container, settings [ _title sprintf( __( Tab #%d, elementor ), $index ), content_width full, ], ]; } protected function get_default_children_elements() { return [ $this-tab_content_container( 1 ), $this-tab_content_container( 2 ), $this-tab_content_container( 3 ), ]; } protected function get_default_repeater_title_setting_key() { return tab_title; } protected function get_default_children_title() { return esc_html__( Tab #%d, elementor ); } protected function get_default_children_placeholder_selector() { return .e-n-tabs-content; }渲染结构与 ARIA 语义render()widgets/nested-tabs.php#L1165-L1215输出的 DOM 结构是前后端协作的契约外层.e-n-tabs携带data-widget-number用于前端 Handler 定位同一 Widget 实例标题区.e-n-tabs-headingroletablist内每个 Tab 是一个button带roletab、aria-selected、aria-controls、data-tab-index等属性内容区.e-n-tabs-content内通过print_child()打印子 Container并给容器包装器加上roletabpanel、ide-n-tab-content-{widgetNumber}{index}、data-tab-index及首项的e-active类。print_child()widgets/nested-tabs.php#L1130-L1152借助elementor/frontend/container/should_render过滤器在打印子容器时动态注入上述 ARIA 属性保证标题与内容区一一对应。编辑器预览模板方面get_initial_config()声明了改进版 Repeater 支持protected function get_initial_config(): array { return array_merge( parent::get_initial_config(), [ support_improved_repeaters true, target_container [ .e-n-tabs-heading ], node button, ] ); }这意味着编辑器内 Repeater 行Tab 标题按钮的增删改会由框架接管局部更新而不是整件 Widget 重渲染——这一点的性能意义见第七节。控件与样式设置register_controls()注册了两组内容内容区tabs采用Control_Nested_Repeater控件而非普通 Repeater字段包括tab_title支持动态标签、tab_icon/tab_icon_active、element_id另有方向tabs_direction、对齐tabs_justify_horizontal/tabs_justify_vertical、标题间距/内边距、水平滚动horizontal_scroll以及断点选择breakpoint_selector控制 Tab 在哪个断点切换为竖向手风琴布局等控件。样式区几乎全部通过 CSS 变量输出如--n-tabs-title-color、--n-tabs-heading-justify-content选择器则区分正常/悬停/激活三态以及触摸设备[data-touch-modefalse|true]。四、编辑器侧注册链路index.js → module.js → nested-tabs.js第一步等待基础模块就绪编辑器入口 assets/js/editor/index.js 是“第一个被加载的文件”其职责是等待 NestedElements 编辑器组件就绪后再动态加载本模块elementorCommon.elements.$window.on( elementor/nested-element-type-loaded, async () { new ( await import( ../editor/module ) ).default(); } );指南中展示的更早版本监听elementor/init-components事件并await elementor.modules.nestedElements本质相同本模块的加载必须排在 NestedElements 之后否则registerElementType时依赖的嵌套 Model 尚不存在。第二步注册元素类型assets/js/editor/module.js 只做一件事import NestedTabs from ./nested-tabs; export default class Module { constructor() { elementor.elementsManager.registerElementType( new NestedTabs() ); } }指南解释了为什么要把元素注册进elementsManager这样才能自定义View、EmptyView或Model如果只需要最小嵌套能力一个getModel()返回嵌套 Model 的类即可// 最小要求让 Model 支持嵌套元素 export class YourWidgetName extends elementor.modules.elements.Widget { getModel() { // 包含嵌套元素支持的基础 Model return $e.components.get( nested-elements/nested-repeater ).exports.NestedModelBase; } }当前仓库的 nested-tabs.js 则采用基类 自定义 View 的形式import View from ./views/view; export class NestedTabs extends elementor.modules.elements.types.NestedElementBase { getType() { return nested-tabs; // 与后端 get_name() 保持一致 } getView() { return View; } } export default NestedTabs;指南还给出了一个更完整的注册范例供需要自定义 Empty View / Model 的场景参考import View from ./views/view; // 处理点击的自定义 View import EmptyView from ./views/empty; // 处理空状态的自定义 Empty ViewReact 组件 export class NestedTabs extends elementor.modules.elements.types.Base { getType() { return nested-tabs; // 后端注册时的 widget 类型名 } getView() { // 自定义 View 应继承 $e.components.get( nested-elements/nested-repeater ).exports.NestedViewBase return View; } getEmptyView() { // 自定义空状态视图应为 React 组件 return EmptyView; } getModel() { // 应继承 NestedRepeaterModel此场景无需自定义 Model返回默认 return $e.components.get( nested-elements/nested-repeater ).exports.NestedModelBase; } }五、自定义 Viewview.js 与可选的 React 空状态视图编辑器 View把子 Container“挂”成 Tab 面板当前仓库的 views/view.js 继承嵌套视图基类负责在编辑器画布中把子元素包装为 Tab 内容export default class View extends $e.components.get( nested-elements ).exports.NestedView { filter( child, index ) { child.attributes.dataIndex index 1; return true; } onAddChild( childView ) { const widgetNumber childView._parent.$el.find( .e-n-tabs )[ 0 ]?.dataset.widgetNumber, index childView.model.attributes.dataIndex, tabId childView._parent.$el.find( .e-n-tab-title[data-tab-index${ index }] )?.attr( id ); childView.$el.attr( { id: e-n-tab-content- widgetNumber index, role: tabpanel, aria-labelledby: tabId, data-tab-index: index, style: --n-tabs-title-order: index ;, } ); // 首次加载时把第一个 Tab 置为激活 const isInitialLoad elementor.previewView.isBuffering; if ( isInitialLoad 1 index ) { childView.$el.addClass( e-active ); } } }逻辑与后端print_child()注入的属性一一对应e-n-tab-content-{n}{i}、aria-labelledby、data-tab-index保证编辑器 DOM 与前端 DOM 的结构契约一致。指南同时说明如果没有自定义逻辑直接使用默认的NestedViewBase即可View 属于可选增强。可选进阶视图Empty View 与预设选择指南详细描述了三个可选的 React 视图对应文档树中的views/目录用于优化“向 Tab 容器添加内容”的交互。说明当前仓库views/目录中仅保留 view.js以下empty.js/add-section-area.js/select-preset.js为指南中的进阶视图示例可作为扩展嵌套组件空状态交互的参考实现。Empty ViewReact 组件Widget 为空时渲染决定显示“添加区”还是“预设选择”import { useState } from react; import AddSectionArea from ./add-section-area; import SelectPreset from ./select-preset; export default function Empty( props ) { const [ isRenderPresets, setIsRenderPresets ] useState( false ); props { ...props, setIsRenderPresets }; return isRenderPresets ? SelectPreset {...props} / : AddSectionArea {...props} /; } Empty.propTypes { container: PropTypes.object.isRequired, };AddSectionArea可拖拽的添加区通过 jQueryhtml5Droppable使容器接受拖入的 Widgetimport { useEffect, useRef } from react; export default function AddSectionArea( props ) { const addAreaElementRef useRef(), containerHelper elementor.helpers.container, args { importOptions: { target: props.container } }; useEffect( () { if ( props.container.view.isDisconnected() ) { return; } const $addAreaElementRef jQuery( addAreaElementRef.current ), defaultDroppableOptions props.container.view.getDroppableOptions(); defaultDroppableOptions.placeholder false; defaultDroppableOptions.items .elementor-add-section-inner; defaultDroppableOptions.hasDraggingOnChildClass elementor-dragging-on-child; $addAreaElementRef.html5Droppable( defaultDroppableOptions ); return () { $addAreaElementRef.html5Droppable( destroy ); }; }, [] ); return ( div classNameelementor-add-section onClick{() containerHelper.openEditMode( props.container )} ref{addAreaElementRef} div classNameelementor-add-section-inner div classNamee-view elementor-add-new-section button typebutton classNameelementor-add-section-area-button elementor-add-section-button aria-label{__( Add new container, elementor )} onClick{() props.setIsRenderPresets( true )} i classNameeicon-plus aria-hiddentrue / /button div classNameelementor-add-section-drag-title {__( Drag widgets here., elementor )} /div /div /div /div ); }SelectPreset点击“”后列出子容器的结构预设通过elementor.helpers.container.createContainerFromPreset()按预设创建容器export default function SelectPreset( props ) { const containerHelper elementor.helpers.container, onPresetSelected ( preset, container ) { containerHelper.createContainerFromPreset( preset, container, { createWrapper: false, } ); }; return ( button typebutton classNameelementor-add-section-close aria-label{ __( Close, elementor ) } onClick{() props.setIsRenderPresets( false )} i classNameeicon-close aria-hiddentrue/ /button div classNamee-view e-con-select-preset div classNamee-con-select-preset__title{__( Select your Structure, elementor )}/div div classNamee-con-select-preset__list { elementor.presetsFactory.getContainerPresets().map( ( preset ) ( button typebutton classNamee-con-preset >export default class YourCustomHandler extends elementorModules.frontend.handlers.BaseNestedTabs { // 在此创建自定义 Handler }而当前仓库的 nested-tabs.js 是一套完整实现值得逐块拆解基于data-widget-number的选择器体系getDefaultSettings()handlers/nested-tabs.js#L49-L78利用 Widget 渲染时输出的data-widget-number构造精确选择器避免多实例互相干扰selectors: { widgetContainer: [data-widget-number${ widgetNumber }], tabTitle: [aria-controls*e-n-tab-content-${ widgetNumber }], tabTitleText: [data-tab-title-id*e-n-tab-title-${ widgetNumber }] .e-n-tab-title-text, tabContent: [data-widget-number${ widgetNumber }] .e-n-tabs-content .e-con, headingContainer: [data-widget-number${ widgetNumber }] .e-n-tabs-heading, activeTabContentContainers: [id*e-n-tab-content-${ widgetNumber }].e-active, }, classes: { active: e-active }, dataAttributes: { tabIndex: data-tab-index }, ariaAttributes: { titleStateAttribute: aria-selected, activeTitleSelector: [aria-selectedtrue], },这些选择器直接依赖第三节所述的渲染契约标题的aria-controls指向e-n-tab-content-{n}{i}内容的data-tab-index与标题一致——前后端共享同一套命名规则是嵌套组件能稳定工作的关键。激活/切换逻辑activateDefaultTab()初始化时读取编辑设置activeItemIndex默认 1用无动画的show/hide切换以避免跳转随后给容器加e-activated类activateTab( tabIndex )设置标题的aria-selected/tabindex给内容加e-active并show()动画完成回调中触发elementor/nested-tabs/activate事件供 Swiper 重初始化、Motion FX 与背景视频重算监听changeActiveTab( tabIndex, fromUser )统一入口。特别地编辑器中用户点击 Tab 标题时并不直接切换 UI而是调用$e.run( document/repeater/select )让编辑器的 Repeater 选择机制接管——这是“编辑器行为与前端行为解耦”的典型做法changeActiveTab( tabIndex, fromUser false ) { if ( fromUser this.isEdit this.isElementInTheCurrentDocument() ) { return window.top.$e.run( document/repeater/select, { container: elementor.getContainer( this.$element.attr( data-id ) ), index: parseInt( tabIndex ), } ); } // ... 去激活旧 Tab、激活新 Tab手风琴模式走 activateMobileTab }移动端手风琴与触摸模式指南“Known issues”一节指出NestedTabs 为了与旧版 Tabs 视觉一致而子内容在 Nested Elements 机制下是独立的 Container需要手动对齐 DOM 结构。指南展示的早期方案是在onInit()中为每个.e-container手工注入一个e-collapse移动标题当前仓库的演进而来的做法是data-touch-mode属性 手风琴检测setTouchMode()handlers/nested-tabs.js#L383-L400在移动端设备或触摸设备上给容器设置data-touch-modetrue样式选择器据此切换悬停效果isAccordionVersion()通过检测.e-n-tabs-heading的display是否变为contents判断当前是否处于竖向手风琴布局activateMobileTab()带 10ms 延时注释说明是为兼容 Apple 设备上“先关后开”的动画时序并在编辑器中把激活标题滚动到视口中心。子元素重排后的索引同步由于 Tab 标题是 Repeater 行、Tab 内容是独立 Container两者序号必须严格一致。updateIndexValues()handlers/nested-tabs.js#L427-L452在elementor/nested-container/atomic-repeater事件触发后遍历所有标题与内容重写id、aria-controls、data-tab-index、--n-tabs-title-order及data-binding-index保证增删 Tab 后 DOM 引用依然正确。此外还有两个实用细节reInitSwipers()在切换到新 Tab 时重新初始化其中的 Swiper修复隐藏容器内初始化导致的 autoplay 异常bindEvents()中订阅了elementor/nested-elements/activate-by-keyboard事件以支持键盘导航懒加载nested-title-keyboard-handler模块。七、样式体系CSS 变量 全局样式的默认值补偿frontend.scss 是全部前端视觉的来源其核心策略是几乎所有外观都通过--n-tabs-*CSS 变量表达Widget 控件只负责改变量取值。文件开头的变量默认值frontend.scss#L46-L95即组件的“设计令牌”.elementor-widget-n-tabs { --n-tabs-color-accent-fallback: #61CE70; --n-tabs-direction: column; --n-tabs-heading-direction: row; --n-tabs-heading-justify-content: center; --n-tabs-title-color: var(--e-global-color-secondary, var(--n-tabs-color-secondary-fallback)); --n-tabs-title-background-color-hover: var(--e-global-color-accent, var(--n-tabs-color-accent-fallback)); --n-tabs-title-font-size: 1rem; --n-tabs-title-transition: 0.3s; // ... 共 40 个变量 }值得注意的是默认值中已经引用了--e-global-color-accent等全局 Kit 变量并带 fallback——这正是指南“Default global values should be set in widget CSS”这一已知问题的直接体现嵌套元素机制依赖 CSS 变量而编辑器/后端的机制对此支持有限因此需要在 Widget 自身 CSS 中手工接入全局颜色/字体变量例如指南给出的补偿写法--n-tabs-title-color: var(--e-global-color-primary); --n-tabs-title-active-color: var(--e-global-color-accent); --n-tabs-title-typography-font-family: var(--e-global-typography-primary-font-family); --n-tabs-title-typography-font-size: initial; --n-tabs-title-typography-font-weight: var(--e-global-typography-primary-font-weight);配合 module.php 中register_styles()的 RTL/断点产物分发机制构成了完整的样式链路。八、局部数据渲染Partial Render只更新变化的 DOM指南最后介绍的一个关键性能特性是partial render局部数据渲染。问题背景是默认渲染机制每次都会重新渲染全部子内容对 NestedTabs 而言仅修改某个tab_title就会触发整个子层级重渲染性能损耗明显。新嵌套基础设施允许在已知 DOM 结构的前提下通过data-binding属性声明“只更新这个节点”Repeater 项的绑定声明element >element >view.addRenderAttribute( tab-title-text, { class: [ e-n-tab-title-text ], data-binding-type: repeater-item, data-binding-repeater-name: tabs, data-binding-setting: [ tab_title, element_id ], data-binding-index: tabCount, data-binding-config: JSON.stringify({ element_id: { attr: id, selector: button, editType: attribute }, tab_title: { editType: text }, }), }, null, true );即修改tab_title只更新该span的文本修改element_id只更新标题button的id属性其余 DOM 与子 Container 完全不受影响。九、已知约束与设计权衡小结结合指南“Attention needed / Known issues”一节与当前源码可以归纳出 NestedTabs 模块的三个核心约束与对策仅配合 Container 工作is_active()与show_in_panel()都依赖container实验module.php、widgets/nested-tabs.php#L53-L55因为子元素必须是 Container移动端布局需手工对齐子内容是独立 Container 后无法再像旧版 Tabs 那样硬编码任意内部结构早期靠onInit()注入e-collapse标题解决当前演进为data-touch-mode 手风琴检测setTouchMode/isAccordionVersion全局样式值需手工桥接嵌套机制使用 CSS 变量而编辑器/后端机制支持有限默认值包括全局 Kit 变量引用与 fallback必须在frontend.scss的 Widget CSS 中显式声明。十、关键文件速查关注点文件官方指南本文核心依据docs/modules/nested-tabs/index.md基础嵌套元素模块文档docs/modules/nested-elements/index.md模块入口激活条件/脚本/样式注册modules/nested-tabs/module.php模块自动注册 Widget 机制core/base/module.php后端 Widget抽象方法/控件/渲染/数据绑定modules/nested-tabs/widgets/nested-tabs.php编辑器入口 / 注册 / 元素类型index.js、module.js、nested-tabs.js编辑器自定义 Viewmodules/nested-tabs/assets/js/editor/views/view.js前端 Handlermodules/nested-tabs/assets/js/frontend/handlers/nested-tabs.js前端样式CSS 变量体系modules/nested-tabs/assets/scss/frontend.scss这套“PHP 注册 编辑器元素类型 前端 Handler CSS 变量 局部数据绑定”的组合是 Elementor 中扩展任何嵌套类组件如嵌套 Accordion 等 NestedElements 家族成员可复用的标准范式。【免费下载链接】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），仅供参考
