步骤详解 - 创建 Helper 配置文件

📋 功能描述

Helper 是物料组件的配置中枢，定义了组件在物料面板的显示信息、右侧属性面板的表单 schema、拖入画布时的默认数据、拖拽行为规则等。它是连接设计器 UI 和组件实例的桥梁。

🧩 模块描述

Helper 对象被 RegisterWidgetHelper.ts 导入并注册到系统，主要提供以下能力：

物料面板配置 - 控制组件在左侧面板的图标、名称、分类
属性面板 Schema - 定义右侧属性面板的表单控件（输入框、选择器等）
默认 Widget 数据 - 拖入画布时生成的初始 schema
拖拽行为 - 控制组件拖入时的栅格占位
选择框配置 - 控制组件是否可选中、复制、删除、隐藏
国际化路径 - 指定需要国际化的属性路径

📁 文件信息

文件路径

packages/form-designer/src/config/widget-helper/<组件名>Helper.ts

操作类型

新建 - 创建 Helper 配置对象

导出方式

默认导出 (export default) Helper 对象

所属层级

页面设计器层 (packages/form-designer)

📊 Helper 接口方法

方法名	返回值	作用说明
`type`	WidgetType	组件唯一类型标识，与 WidgetType 枚举值对应
`buildMaterialConfig()`	MaterialConfig	物料面板显示配置：图标、名称、分类
`buildSettings(params)`	WidgetSettingsConfig[]	右侧属性面板的表单 schema（属性/样式/事件 tab）
`buildWidget(params)`	WidgetSchema	拖入画布时生成的默认 schema（默认值、初始 props）
`dragInfo()`	{ col: number }	拖拽时的栅格跨度（1-24）
`hasSelectBox()`	SelectBoxConfig	是否可选中、可否复制/删除/隐藏等
`collectLanguagePath()`	{ paths: string[][] }	需要国际化的属性路径

💻 完整代码示例

// packages/form-designer/src/config/widget-helper/MyNewComponentHelper.ts

import { WidgetType } from '~@/types/WidgetType'

export default {
  // 1. 组件类型标识
  type: WidgetType.MyNewComponent,

  // 2. 物料面板配置
  buildMaterialConfig() {
    return {
      icon: 'icon-text',          // 图标类名
      name: 'MyNewComponent',     // 组件类型名
      title: '新组件',            // 显示名称（在物料面板中显示）
      category: 'common',         // 分类：common/container/navigation 等
    }
  },

  // 3. 右侧属性面板配置
  buildSettings(params) {
    return [
      {
        key: 'property',
        label: '属性设置',
        type: 'tab',
        children: [
          {
            key: 'content',
            label: '文本内容',
            type: 'input',          // form-create 内置控件类型
            placeholder: '请输入内容',
          },
          {
            key: 'fontSize',
            label: '字体大小',
            type: 'inputNumber',
            min: 12,
            max: 72,
          },
          {
            key: 'color',
            label: '字体颜色',
            type: 'colorPicker',
          },
        ],
      },
    ]
  },

  // 4. 拖入画布时生成的默认数据
  buildWidget(params) {
    return {
      type: this.type,
      props: {
        content: '默认文本',
        fontSize: '14px',
        color: '#333333',
      },
    }
  },

  // 5. 拖拽行为配置
  dragInfo() {
    return {
      col: 12,  // 占 12/24 栅格
    }
  },

  // 6. 选择框配置
  hasSelectBox() {
    return {
      selectable: true,     // 是否可选中
      deletable: true,      // 是否可删除
      copyable: true,       // 是否可复制
      hideable: false,      // 是否可隐藏
    }
  },

  // 7. 国际化路径
  collectLanguagePath() {
    return {
      paths: [
        ['widget', 'MyNewComponent', 'content'],
      ],
    }
  },
}
            

⚠️ 注意事项

type 必须与 WidgetType 枚举值完全一致
buildSettings 中的 type 使用 form-create 内置控件类型
buildWidget 返回的 props 结构需与 Vue 组件的 props 定义匹配
复杂组件可实现 transformSchemaProperties 和 buildSchemaController 方法

➡️ 下一步

完成 Helper 配置后，继续执行：

步骤 4：在 RegisterWidget.ts 中注册组件实例
步骤 5：在 RegisterWidgetHelper.ts 中注册 Helper
步骤 6：在 Material.ts 中注册物料面板分组