组合组件 component-instance

把「多组件 + 数据 + 交互」沉淀成母版，以实例复用（有身份的引用）。

• 类型串：component-instance　默认尺寸：[400, 300]　分类：容器

实时预览

下面渲染的是真实组件（与编辑器 / 运行时同源）。修改右侧「样式参数」，左侧预览实时更新；点击底部「全页面查看」可放大。

属性

下表为本组件特有的属性；position / size / opacity / background / border / 联动选中 / 筛选等通用参数见组件手册总览。

本组件无特有属性（仅通用参数）。

数据绑定

无组件特有数据绑定字段（纯样式 / 布局 / 装饰）。

事件

触发器

触发器在预览 / 播放态生效（编辑态点击 = 选中组件）。写在本组件 options.interactions 的 groups[].trigger 里。

触发器	名称	触发时机	payload（供动作公式 {:字段} 取值）
click	点击	点击本组件时触发	无
mouseEnter	鼠标移入	指针移入组件时触发	无
mouseLeave	鼠标移出	指针移出组件时触发	无
appear	入场	组件出现时触发（配合进场动画）	无
disappear	离场	组件消失时触发（配合退场动画）	无
receiveBehaviorEvent	接收行为事件	收到 sendBehaviorEvent 动作或宿主 ctx.emit 投递的事件时触发（按 eventName 匹配）	发送方携带的 data

动作

触发器命中后执行的动作。本组件既可发起动作（配在自己的交互里），也可作为其它组件动作的目标。

动作	名称	说明
changeOption	修改设置	把本组件（或其它组件）的某个属性改为静态值 / 公式动态值
switchState	切换状态	切到多状态里的某个状态（state:"" 回默认态）
appear / disappear	进 / 退场动画	对目标 opacity 做 0↔100 插值的显隐动画

完整动作清单（switchScreen / switchWindow / openUrl / sendBehaviorEvent / transfer / executeScript / requestApi 等）与持久化写法见事件交互。

示例

{
  "type": "component-instance",
  "uid": "w_component_instance",
  "options": {
    "position": [40, 40],
    "size": [400, 300]
  }
}

持久化写法：实例节点结构（手写 JSON 必读）

组合组件的关键字段写在节点顶层（与 options 平级，不在 options 里）：masterId 引用母版、props 传输入参数、overrides 打局部补丁、master 自带母版快照（离线 / 导出 / SDK 渲染依赖它；编辑器发布时由组件库母版回灌）。源码契约见 web/packages/core/src/template/componentMaster.ts：

{
  "type": "component-instance", "uid": "inst_kpi_1",
  "options": { "position": [40, 40], "size": [420, 180] },
  "masterId": "master_kpi",              // 引用哪个母版
  "masterVersion": 1,                    // 记录的母版版本（低于库母版 version 时编辑器提示可更新）
  "props": { "title": "在线用户数" },     // 输入参数：键 = propsSchema[].key
  "overrides": {                         // 局部覆盖：键 = 母版原始子节点 uid → option 补丁
    "m_value": { "text-font": { "size": 60, "color": "#ffd666", "bold": true } }
  },
  "master": {                            // 母版快照（离线渲染用）
    "masterId": "master_kpi", "name": "KPI 卡片", "version": 1,
    "propsSchema": [
      { "key": "title", "label": "标题", "type": "string",
        "target": { "uid": "m_title", "path": ["text"] }, "default": "指标" }
    ],
    "eventsSchema": [
      { "key": "card-clicked", "label": "卡片被点击", "sourceUid": "m_root" }
    ],
    "node": {
      "type": "group-panel", "uid": "m_root",
      "options": { "position": [0, 0], "size": [420, 180], "background": true, "background-color": "rgba(16,32,58,0.8)" },
      "widgets": [
        { "type": "basic-text", "uid": "m_title", "options": { "position": [28, 22], "size": [300, 28], "text": "指标" } },
        { "type": "basic-text", "uid": "m_value", "options": { "position": [28, 62], "size": [320, 70], "text": "1,286" } }
      ]
    }
  }
}

• props 输入：键 = 母版 propsSchema[].key；渲染时按 target: { uid, path } 写进母版内目标子节点的 option 路径（实例未传时用 default）。
• overrides 局部覆盖：键 = 母版原始子节点 uid，值 = option 补丁（顶层键整体替换），在 props 之后应用——同一母版的不同实例可以各改各的字号 / 配色。
• eventsSchema 输出事件：把内部子组件（sourceUid）的行为事件向外暴露为组件事件；外部组件用 receiveBehaviorEvent 触发器（事件名填 key）接收，实现「组件内部按钮点击 → 外部页面响应」。
• uid 派生：渲染时内部子组件 uid 为 实例uid::母版子uid（确定性、多实例天然隔离，组内交互引用自动改写）。

延伸阅读：组件手册总览 · 数据系统 · 事件交互。