自定义组件配置项开发规范-多端低代码开发平台魔笔-阿里云

本文介绍了魔笔组件的配置项开发规范，您可参照该规范开发自定义组件库。

概述

魔笔在应用搭建页面右侧的配置面板中针对每个组件提供了不同的配置项，配置项描述了组件在搭建平台中的行为、属性和样式。您可通过不同配置项的组合，使用组件多样化的行为和样式快速搭建出满足您需求的页面。

开发规范

在开发自定义组件时，配置文件是每个配置项键值对的对象集合，您可参考并遵循以下配置项开发规范进行开发：

一、基础信息

配置项键名	类型	说明	示例
`type`	`string`	组件的唯一标识符	`'Button'`, `'Alert'`, `'Image'`
`title`	`string`	组件在物料面板中显示的标题名称	`'按钮'`, `'警告框'`, `'图片'`
`description`	`string`	组件的详细描述，用于说明组件的用途和功能	`'警告框组件用于用户界面中显示重要信息或警告的魔笔基础组件'`

二、显示控制

配置项键名	类型	说明	示例
`category`	`string`	组件在左侧物料面板中所属的分类目录	`表单类组件` `自定义组件库`
`icon`	`string`	组件在物料面板中显示的图标	`https://img.alicdn.com/imgextra/i1/O1CN01xmukZf1PQwITgylzc_!!6000000001836-55-tps-1024-1024.svg`
`hideInMaterial`	`true`	设置为 `true` 时，组件不在物料面板中展示	`true`, `false`
`hideInWidgetEditMode`	`boolean`	设置为 `true` 时，禁止在 widget 编辑模式下显示	`true`, `false`
`hideInLayoutEditMode`	`boolean`	设置为 `true` 时，禁止在 layout 编辑模式下显示	`true`, `false`

三、容器属性

配置项键名	类型	说明	示例
`isContainer`	`boolean`	标识组件是否为容器组件（可以包含子组件）	`true`（容器组件） `false`（非容器组件）
`isDefaultFlexContainer`	`boolean`	作为容器时，是否默认为弹性布局	`true`, `false`
`defaultFlexContainerProps`	`IFlexProps`	作为弹性容器时的默认排列属性	`{ flexDirection: 'row', alignItems: 'center', gap: 8 }`
`isMultipleContainer`	`boolean`	是否包含多视图容器	`true`, `false`

四、编辑行为

配置项键名	类型	说明	示例
`cantMoveOrResize`	`true`	设置后，组件禁止移动或改变大小	`true`
`cantDelete`	`true`	设置后，组件禁止删除（适用于系统级框架组件）	`true`
`cantCopy`	`true`	设置后，组件禁止复制	`true`
`freezeId`	`true`	设置后，组件的 ID 不能被修改	`true`

五、网格布局配置

配置项键名	类型	说明	示例
`gridConfig`	`object`	网格布局配置对象，所有组件都需要定义	见下方子属性
`gridConfig.dragRect`	`{ w: number; h: number }`	搭建时拖拽组件在网格中展示的大小（网格单位）	`{ w: 6, h: 4 }` `{ w: 18, h: 5 }`
`gridConfig.initHeight`	`(dragHeight: number) => {}`	初始化高度的计算函数，参数 `dragHeight` 是拖拽时的展示高度	`(dragHeight) => ({ type: 'fixed', value: dragHeight })` `() => ({ type: 'auto' })`
`gridConfig.supportHeightType`	`Array<'fixed' \| 'auto' \| 'limit' \| 'custom'>`	支持设置的高度类型	`['fixed', 'auto']` `['auto']` `['fixed']`
`gridConfig.changeHeightWhenFixed`	`boolean`	在高度为 fixed 时，是否可以改变高度，不填写时默认为 `true`	`true`, `false`
`gridConfig.fixedMinHeight`	`number`	在高度为 fixed 时可设置的最小高度（网格单位）	`3`, `5`, `10`
`gridConfig.overflow`	`'hidden' \| 'visible' \| 'auto'`	指定外部包裹区域的溢出行为，默认为 `hidden`	`'visible'`, `'hidden'`, `'auto'`

高度类型说明：

高度类型	数据结构	说明
`fixed`	`{ type: 'fixed', value: number }`	固定高度
`auto`	`{ type: 'auto' }`	自适应高度
`limit`	`{ type: 'limit', min: number, max: number }`	自适应高度，但有最小和最大高度限制
`custom`	`{ type: 'custom', value: React.CSSProperties['height'] }`	自定义高度

六、弹性布局配置

配置项键名	类型	说明	示例
`flexConfig`	`object`	弹性布局配置对象	见下方子属性
`flexConfig.flexDirection`	`'column' \| 'row' \| 'column-reverse' \| 'row-reverse'`	子元素排列方向	`'row'`, `'column'`
`flexConfig.alignItems`	`'stretch' \| 'flex-start' \| 'flex-end' \| 'center'`	子元素交叉轴对齐方式	`'center'`, `'flex-start'`
`flexConfig.justifyContent`	`'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-evenly'`	子元素主轴排列方式	`'center'`, `'space-between'`
`flexConfig.gap`	`number`	子元素间距（像素）	`8`, `16`, `24`
`flexConfig.flexWrap`	`'nowrap' \| 'wrap' \| 'wrap-reverse'`	子元素换行方式	`'nowrap'`, `'wrap'`
`flexConfig.alignContent`	`'stretch' \| 'flex-start' \| 'center' \| 'flex-end' \| 'space-between' \| 'space-around'`	子元素支持换行时交叉轴的对齐方式	`'flex-start'`, `'space-between'`
`flexConfig.overflow`	`'hidden' \| 'visible' \| 'auto'`	指定外部包裹区域的溢出行为，默认为 `hidden`	`'visible'`, `'auto'`
`flexConfig.flexShrink`	`'0' \| '1'`	子元素的 flex-shrink 属性	`'0'`, `'1'`
`flexConfig.alignSelf`	`'auto' \| 'stretch' \| 'flex-start' \| 'flex-end' \| 'center'`	子元素的 align-self 属性	`'auto'`, `'center'`
`flexConfig.mainSize`	`string`	自身弹性尺寸设置（主轴方向）	`'30px'`, `'100%'`, `'auto'`
`flexConfig.crossSize`	`string`	自身弹性尺寸设置（交叉轴方向）	`'80px'`, `'50%'`, `'auto'`

七、尺寸配置

配置项键名	类型	说明	示例
`defaultSizeAsFlexItem`	`{ w: string; h: string }`	非容器组件作为弹性容器子项时的默认尺寸	`{ h: '32px' }` `{ w: '100px', h: '40px' }`

八、布局类型

配置项键名	类型	说明	示例
`defaultLayoutType`	`'flex' \| 'grid'`	默认布局类型	`'flex'`, `'grid'`
`supportLayoutType`	`('flex' \| 'grid')[]`	支持的布局类型	`['flex', 'grid']`, `['flex']`

九、属性面板配置

配置项键名	类型	说明	示例
`inspectorConfig`	`ControlGroup[]`	定义组件在右侧属性面板中的配置项	见下方详细说明

inspectorConfig 结构

inspectorConfig: [
  {
    title: '分组标题',  // 如 '内容'、'交互'、'样式'
    items: [/* 配置项列表 */]
  }
]

配置项通用字段

字段名	类型	说明	示例
`type`	`'control' \| 'addOn' \| 'designToken' \| 'customCSS'`	配置项类型	`'control'`
`title`	`string`	配置项显示标题	`'按钮文字'`, `'是否可关闭'`
`name`	`string`	属性在 props 中的键名	`'text'`, `'disabled'`, `'type'`
`valueType`	`'string' \| 'number' \| 'boolean' \| 'object' \| 'array'`	值类型	`'string'`, `'boolean'`
`defaultValue`	`any`	默认值	`'按钮'`, `false`, `'info'`
`required`	`boolean`	是否必填	`true`, `false`
`isExpression`	`boolean`	是否支持表达式	`true`, `false`

control 控件配置

字段名	类型	说明	示例
`control.type`	`string`	控件类型（见下方常用控件类型表）	`'Input'`, `'Select'`, `'Switch'`
`control.display`	`'inline' \| 'block' \| 'none'`	显示方式	`'inline'`, `'block'`
`control.props`	`object`	控件的额外属性	`{ options: [...] }`
`control.enableCodeEdit`	`boolean`	是否启用代码编辑	`true`, `false`

常用控件类型

控件类型	说明	适用数据类型	示例配置
`Input`	文本输入框	`string`	`control: { type: 'Input' }`
`Code`	代码编辑器	`string`	`control: { type: 'Code', props: { addonAfter: 'px' } }`
`Select`	下拉选择	`string`	`control: { type: 'Select', props: { options: [{label: '选项1', value: 'v1'}] } }`
`Radio`	单选按钮组	`string`	`control: { type: 'Radio', props: { options: [...] } }`
`Switch`	开关	`boolean`	`control: { type: 'Switch', display: 'inline' }`
`Color`	颜色选择器	`string`	`control: { type: 'Color' }`
`Icon`	图标选择器	`object`	`control: { type: 'Icon', enableCodeEdit: true }`
`Event`	事件配置	`array`	`control: { type: 'Event', props: { options: [{label: '点击', value: 'click'}] } }`

其他配置项字段

字段名	类型	说明	示例
`tip`	`{ desc: string; doc?: { docKey: string; text: string } }`	提示信息	`{ desc: '控制组件是否禁用' }`
`condition`	`(context: { props: any }) => boolean`	显示条件函数，返回值为true时显示该配置项，为false时不显示该配置项	`({ props }) => props.closable === true`

特殊配置项类型

类型	说明	示例
`addOn`	附加配置分组	`{ type: 'addOn', title: '扩展配置', items: [...] }`
`designToken`	antd Token 配置	`{ type: 'designToken', title: '主题变量', componentType: 'Button' }`
`customCSS`	自定义 CSS 样式	`{ type: 'customCSS', title: '自定义 CSS 样式', items: [...] }`

十、暴露配置

配置项键名	类型	说明	示例
`exposeConfig`	`ExposeConfig`	定义组件对外暴露的属性、方法和事件，用于组件间交互（必填）	见下方子属性
`exposeConfig.getter`	`Array<{ name: string; label: string; type: string }>`	可读取的属性列表	`[{ name: 'text', label: '按钮文本', type: 'string' }]`
`exposeConfig.setter`	`Array<{ name: string; label: string; type: string; excludeSetter?: string[] }>`	可设置的属性列表	`[{ name: 'disabled', label: '是否禁用', type: 'boolean' }]`
`exposeConfig.method`	`Array<{ type: string; label: string; execute: (ref) => void }>`	可调用的方法列表	`[{ type: 'click', label: '点击', execute: (ref) => ref.current.click() }]`

示例

const ButtomExample = {
  type: 'Button',
  title: '按钮',
  description: '按钮组件是标记了一个（或封装一组）操作命令的魔笔基础组件',
  category: "按钮类组件",
  commonIndex: 3,
  isContainer: false,
  
  flexConfig: {
    mainSize: '30px',
    crossSize: '80px',
  },
  
  gridConfig: {
    dragRect: {
      w: 6,
      h: 4,
    },
    initHeight: (dragHeight) => ({ type: 'fixed', value: dragHeight }),
    supportHeightType: ['fixed'],
    fixedMinHeight: 3,
  },
  
  defaultSizeAsFlexItem: {
    h: '32px',
  },
  
  aiDefaultSizeAsFlexItemWhenParentIsColumn: {
    w: '100%',
  },
  
  inspectorConfig: [
    {
      title: '内容',
      items: [
        {
          agent: ['ui', 'logic'],
          type: 'control',
          title: '按钮文字',
          name: 'text',
          defaultValue: '按钮',
          valueType: 'string',
          required: false,
          isExpression: true,
          control: {
            type: 'Code',
          },
        },
      ],
    },
    {
      title: '交互',
      items: [
        {
          agent: ['logic'],
          type: 'control',
          title: '禁用',
          name: 'disabled',
          tip: {
            desc: '控制组件是否禁用。禁用的组件展示为灰色，提示用户该组件不可用。',
          },
          defaultValue: false,
          valueType: 'boolean',
          required: false,
          isExpression: true,
          control: {
            type: 'Switch',
            display: 'inline',
            enableCodeEdit: true,
          },
        },
        {
          agent: ['logic'],
          type: 'control',
          title: '事件',
          name: 'events',
          control: {
            type: 'Event',
            props: {
              options: [
                { label: '点击', value: 'click' },
              ],
            },
            display: 'block',
          },
          valueType: 'array',
          required: false,
        },
      ],
    },
  ],
  
  exposeConfig: {
    getter: [
      {
        type: 'string',
        label: '按钮文本',
        name: 'text',
      },
      {
        type: 'boolean',
        label: '是否禁用当前按钮',
        name: 'disabled',
      },
    ],
    setter: [
      {
        type: 'string',
        label: '按钮文本',
        name: 'text',
      },
      {
        type: 'boolean',
        label: '是否禁用当前按钮',
        name: 'disabled',
      },
    ],
    method: [
      {
        type: 'click',
        label: '点击',
        execute: (ref) => {
          ref.current.click();
        },
      },
    ],
  },
};

export default ButtomExample;