容器与视图组件

2026年7月8日大约 5 分钟

容器与视图组件

用来组织与复用其它组件、承载多视图切换与弹层。容器的子组件放在节点的 widgets 里，坐标相对容器左上角。

分组面板 `group-panel`

最常用的容器：把一组组件框在一起统一定位 / 加背景边框 / 整体缩放。默认 [400, 300]。

参数：children-no-events（子组件穿透）、child-state-follow（状态跟随）、child-select-exclusive（选中互斥）、show-scrollbar + scrollbar-*（滚动条）；内容自适应缩放 panel-content-fit（contain/cover/stretch，见画布系统）。子组件放 widgets: []。

数据循环容器 `data-repeater`

按数据行批量复制一个模板单元（类比 v-for），做卡片墙 / 设备栅格等。默认 [900, 240]。

关键结构：模板不放 widgets，而放在节点顶层的 unitTemplate（一个 group-panel，与 options 平级）；运行期按数据行派生 N 份（派生实例不持久化）。

{
  "type": "data-repeater", "uid": "w_rep",
  "options": {
    "container-layout": "fluid", "flex-direction": "row",
    "unit-size": [330,170], "fluid-gap-value": 18, "overflow": "scroll-y",
    "item-fields": [["conn","tbl","名称"]],
    "row-key-field": [["conn","tbl","名称"]]
  },
  "unitTemplate": {
    "type": "group-panel", "uid": "w_rep__unit",
    "options": { "size":[330,170], "background": true },
    "widgets": [
      { "type":"basic-text", "uid":"tpl_name",
        "options": { "position":[22,18], "size":[286,32], "value-field": [["conn","tbl","名称"]] } }
    ]
  }
}

绑定：item-fields（≥1，决定行数）+ row-key-field（0~1，行稳定标识，刷新时复用单元、保留交互态）。

行作用域（核心）：模板内子组件用普通字段绑定即可——只要绑定的表落在 item-fields 所在表内，取数会自动落到「当前行」，无须为每行单独配置。

项级事件：整项点击在 data-repeater 自身配 itemClicked（payload = 本行整行数据，{:字段} 可取）；项内子组件事件在模板子组件上配（自指动作 element 必须留空 []）。

推荐「静态画布内嵌流式」：外层用 static 绝对定位，流式只放在 data-repeater 内部，卡片用固定 unit-size + overflow: scroll-y。

组合组件 `component-instance`

把「多组件 + 数据 + 交互」整组沉淀成母版，在大屏上以实例复用（有身份的引用，可批量同步、可传 props）。区别于分组面板的「快照图章」。

母版子树放节点顶层的 master.node；实例不放 widgets。
props 传入参数（标题 / 数值字段等，键 = master.propsSchema[].key）；overrides 按母版原 uid 打样式补丁。
母版 version+1 后，过期实例可「同步最新 / 保留本地 overrides」，或「解除关联」展开为普通分组面板。

{ "type": "component-instance", "uid": "inst_kpi", "masterId": "master_kpi", "masterVersion": 1,
  "options": { "position": [300,380], "size": [460,320] },
  "props": { "title": "在线用户数", "valueField": [["conn_kpi","tbl_kpi","在线用户"]] } }

画面组件 `window-instance`

在页面内嵌入另一个画面（画面复用）。适合把公共头部 / 侧栏 / 子看板做成独立画面再多处引用。默认尺寸 [400, 300]。

参数：window（选择要嵌入的画面 / 窗口）、content-fit（内容缩放 stretch / contain / cover / none）、show-window-bg（显示被嵌画面的背景）。

视图容器 `layout-section`

多视图、一次一显（对照 ArcGIS ExB Section）。每个视图 = 一个 group-panel 子面板（放 widgets，面板 name 即视图名），运行时只显示激活视图。默认 [640, 400]。

{ "type": "layout-section", "uid": "sec_main", "options": {
    "sections": "经营总览,实时趋势,告警明细",   // 视图标题（=子面板 name）
    "default-active": 0, "transition": "slide-h",
    "arrows-visible": true, "dots-visible": true, "auto-play": false },
  "widgets": [ /* 每个视图一个 group-panel，position:[0,0]、size=容器尺寸 */ ] }

参数：sections（视图列表）、default-active、transition（none/fade/slide-h/slide-v）+ transition-duration、lazy-render、arrows-*（内置翻页箭头）、dots-*（指示点）、auto-play + play-interval/play-loop/hover-pause。

交互：触发器 viewChanged（{index,label}）、itemClicked；动作 openView（指定序号）/ nextView / prevView。

视图导航 `nav-views`

链接一个视图容器，点击导航切视图（双向同步高亮）。放在视图容器之外，用 link-section 关联。默认 [360, 44]。

参数：link-section（element，types=layout-section，必配）、nav-style（tabs/symbol/arrows/slider）、tab-variant（default/underline/pill）、views-mode（auto / custom + views-subset）、三态文字与背景色等。

{ "type": "nav-views", "uid": "nav_tabs", "options": {
  "link-section": [{ "targetPath": ["screen_main","sec_main"], "refType": "element" }],
  "nav-style": "tabs", "tab-variant": "underline" } }

页面内弹层（跟随版面的轻弹窗），由 switchPopup 动作开关。子组件放 widgets。需要全局模态 / 启动页 / 跨页面复用时，改用窗口系统。默认尺寸 [400, 300]。

参数：popup-bg（弹窗背景）、show-mask + background-mask-color（遮罩）、close-outside（点遮罩关闭）、auto-close + close-time（定时自动关，可 close-show-countdown 显示倒计时）、show-scroll（内容滚动）、close-btn-*（关闭按钮显隐 / 颜色 / 大小 / 偏移）。

{ "type": "group-popup", "uid": "pop_tip", "options": {
  "position": [560, 300], "size": [420, 280], "show-mask": true, "close-outside": true },
  "widgets": [ /* 弹窗内容组件 */ ] }
// 由某组件交互动作 switchPopup 打开：action.name = "switchPopup"，目标指向 pop_tip

选项卡 `group-tabs`

多标签页容器，每个标签对应一个子面板（放 widgets，按标签顺序对应）。适合把同一区域的多组内容分页承载。默认尺寸 [400, 300]。

参数：tab-items（标签列表，逗号 / 换行分隔）、orientation（horizontal / vertical）、bar-position（Tab 条 start / end）、default-active、tab-type（tag 标签 / mark 标示）、auto-switch + switch-interval（自动轮播）、tab-color / tab-active-color / tab-bg / tab-active-bg / tab-radius（三态样式）、show-indicator + indicator-color（激活指示条）。

数据绑定：tab-field（string, 0~1）——用字段值生成标签。

按钮组菜单 `group-buttons`

一组联动按钮（如筛选切换、时间粒度切换），点击派发交互，常配合联动 / 切换状态。默认尺寸 [480, 48]。

参数：menu-items（选项，逗号分隔）、default-type（first / last / fixed / index / none）、allow-unselected（可取消选中）、orientation + auto-layout / rows / cols / gap（排布）、text-color / item-bg / selected-text-color / selected-bg / hover-*（三态样式）。

数据绑定：menu-field（string, 0~1）——用字段值生成按钮项。

延伸阅读：组件手册总览 · 画布系统（容器内部布局：静态 / 流式）· 窗口系统（工程级浮层）· 事件交互。