属性面板暴露机制

组件如何把自己的字段暴露给设计器属性面板,让最终用户在面板里改值。

---

1. 5 个平台扩展字段

组件源码 JS 部分 = Vue Options + 5 个平台扩展字段:

字段	用途
name	{ value?: string; CN?: string } — 中英文名
method	对外暴露方法(被 runtime.call 调)
attribute	属性字典 Record<string, string>(key → 说明)— 属性面板表单项源
custom	自定义字段(平台扩展,含 dataInput: true 数据绑定目标)
style	样式字典

源:@hy-bricks/core/parseSource.ts(acorn 静态解析 export default)

---

2. attribute vs custom

// attribute — 简单字段,字典 { key: '说明' }
attribute: {
  text: '按钮文本',
  variant: '样式 primary/default',
  disabled: '是否禁用',
}

// custom — 复杂字段,带元数据
custom: {
  seriesData: {
    label: '系列数据',
    dataInput: true,        // ★ 标记可被 binding 灌入
    value: [],              // 初始值
  },
}

简单字段用 attribute,复杂字段(需绑数据 / 自定义编辑器)用 custom。

---

3. 普通组件范例:MyButton

JS:

export default {
  name: { value: 'MyButton', CN: '我的按钮' },
  attribute: {
    text: '按钮文本',
    variant: '样式 primary/default/dashed',
    disabled: '是否禁用',
  },
  data() {
    return { text: '点击', variant: 'default', disabled: false }
  },
  methods: {
    onClick() {
      this.$emit('click')
    },
  },
}

HTML:

<button :disabled="disabled" :class="variant" @click="onClick">
  {{ text }}
</button>

宿主属性面板拿到 ComponentMeta.attribute:

const meta = parseComponentSource(jsSource).meta
console.log(meta.attribute)
// { text: '按钮文本', variant: '样式 primary/default/dashed', disabled: '是否禁用' }

按字段类型推断渲染表单(shadcn-vue Input / Switch / Select)。

---

4. 数据绑定字段(custom.dataInput)

custom: {
  chartData: {
    label: '图表数据',
    dataInput: true,
    value: [],
  },
}

用户在属性面板看到 chartData(数据源) 选项 → 选已注册 dataSource → 写 PageDocument.bindings:

{
  id: 'b1',
  source: { kind: 'dataSource', sourceId: 'sales-2024' },
  target: { kind: 'instanceDataInput', instanceId: '...', key: 'chartData' },
}

运行时 SDK wire binding → fetch → setDataInput('chartData', data) → 组件 $watch 触发。

---

5. 完整数据流

组件源码 (JS)
  ↓ parseComponentSource
ComponentMeta { attribute, customDecl, ... }
  ↓ host 拼属性面板
属性面板渲染表单(Input / Select / 数据源绑定按钮 / ...)
  ↓ 用户改值
PageInstance.props[<key>] = newValue
  ↓ Vue reactivity
组件实例字段更新
  ↓ 组件 mounted / $watch 监听
触发组件内 setOption / refresh / ...

---

6. 属性面板 UI 在哪

SDK 不提供完整属性面板 UI,只给契约(ComponentMeta)+ binding 协议。

属性面板渲染完全在宿主侧,由各宿主应用自行实现。

UI 库建议:组件设计器 + 在线 IDE 一律用 shadcn-vue + Tailwind,保持视觉一致。

---

7. 自定义编辑器(复杂场景)

简单字段用默认表单组件;复杂字段(echarts series / 颜色 / 富文本)需自定义 editor:

custom: {
  options: {
    label: 'ECharts Option',
    type: 'json-object',
    editor: 'echarts-option',     // host 约定:用哪个 editor 组件
    value: {},
  },
}

custom 是 Record<string, any> 完全开放,host 自己约定额外元数据(editor / schema / placeholder ...)。

当前平台没有官方 attribute.editor 协议,host 自己约定。

---

8. 相关

• /recipes/echarts — echarts 集成示例
• /api/canvas-types — PageBinding / BindingSource / BindingTarget 字段表