UX1 自定义组件属性面板与联动

基本结构

optionSchema.ts 输出两组扁平列表：

viewList 通过 parentId 组成树：

Root
├── basic-tab
│   └── 基础配置 Collapse / Block / 输入项
├── event-tab
│   └── EventAction
└── style-tab
    └── 样式配置 Collapse / Block / 输入项

除根节点外，每个节点都应有正确的 parentId。推荐沿用 basic-tab、event-tab、style-tab，便于不同组件保持一致体验。

配置绑定规则

节点 id 以 : 开头时，属性控件的值会写入对应路径；不带 : 的 id 只作为结构节点或联动锚点。本节只约定组件自己的业务配置路径：普通配置使用 :config.*，样式配置使用 :configCss.*。

业务配置路径应与组件实际读取的类型和路径对应。只有需要新实例初始值时，才在 data.json 的 config 或 configCss 中提供默认值；平台级字段及其它特殊路径以当前模板契约为准。

最小 schema

export default {
  viewList: [
    {
      id: 'root',
      uxComponentInfo: { name: 'Root', importType: 'custom' },
    },
    {
      id: 'basic-tab',
      parentId: 'root',
      uxComponentInfo: { name: 'TabPanel', importType: 'custom' },
      config: {},
    },
    {
      id: 'base-collapse',
      parentId: 'basic-tab',
      uxComponentInfo: { name: 'Collapse', importType: 'custom' },
      config: { label: '基础' },
    },
    {
      id: ':config.title',
      parentId: 'base-collapse',
      uxComponentInfo: { name: 'Language', importType: 'custom' },
      config: { label: '标题', placeholder: '请输入标题' },
    },
  ],
  logicList: [],
};

常用属性控件怎么选

控件名称和可用参数可能随目标项目版本变化，例如当前辅助工具包使用 Language，旧培训材料使用 LanguageInput。Agent 应以目标版本中的实际注册名为准，不能只按旧示例猜测。

一个控件写多个配置

当一个属性控件需要一次输出多个字段时可使用 composeMap，例如同时更新默认值类型、固定值和表达式。映射格式以当前属性控件和辅助工具包示例为准；Edit 或 Use 再从相应业务配置路径读取结果。

logicList 联动

联动项通过 parentId 指定作用目标，通过 configObserves 指定观察项。设计时注意：

• 观察路径必须存在，避免两个联动规则互相写回形成循环。

• 显隐只影响属性面板显示，不能替代运行态的安全兜底。

• checkParent 匹配到非法父级时会删除当前组件并提示用户；提示文案应说明不合法原因或允许放置的位置。

• 向子代同步前应限定匹配条件，避免修改无关组件。

自定义属性控件

现有控件不能表达业务配置时，可在组件内部新增属性控件：

1. 使用 PanelComponentBaseProps<Config> 定义输入配置和 onChange。

2. 在 option.tsx 通过 registerComponent 注册。

3. 在 optionSchema.ts 用注册名称引用。

4. 使用业务自己的命名空间，不占用平台保留命名空间。

5. 覆盖初始值、更新、清空、表达式值和残缺配置等场景。

自定义属性控件只服务当前组件时，放在组件内部最容易维护；多个组件共用时，再评估是否沉淀到业务物料工程。

完成检查

• 面板层级和三个 Tab 正确，所有非根节点都有有效 parentId。

• :config.*、:configCss.* 与组件读取路径一致；需要默认值的字段已在 data.json 对应位置配置。

• 事件面板只展示已声明事件，联动不会循环或误改其它组件。

• 新拖入和已有实例、单实例和多实例、空配置和残缺配置都能正常打开。

• 自定义属性控件已注册，使用业务命名空间，并通过本地和真实页面验证。