AcroDynamicForm ( Acro 动态表单 )

基于 Arco Design Vue 封装的动态表单组件

注意

• 依赖于 @arco-design/web-vue 组件库
• 该组件仅支持 Vue 3

演示

基础用法

组件插槽&表单项插槽

操作按钮区域插槽

渲染自定义组件

预设

完整示例

账号登录

验证码登录

API

Props

参数名	描述	类型	默认值
fields	字段配置列表	DynamicFormField[]	-
model	表单数据	Record<string, any>	-
actionButtonArea	操作按钮区域配置	ActionButtonAreaOptions | boolean	true
submitButton	提交按钮配置	SubmitButtonOptions | boolean	true
resetButton	重置按钮配置	ResetButtonOptions | boolean	true

Methods

validate; // 校验全部表单数据
validateField; // 校验部分表单数据
resetFields; // 重置表单数据
clearValidate; // 清除校验状态
setFields; // 设置表单项的值和状态
scrollToField; // 滚动到指定表单项

reset; // 重置表单数据, 是 `resetFields` 方法的别名
init; // 初始化表单数据

Events

事件名	描述	回调参数
submit	点击了提交按钮的事件	model: Record<string, any>
reset	点击了重置按钮的事件	-

Slots

名称	描述
actionButtonArea	操作按钮区域插槽, 可使用该插槽代替操作按钮区域的渲染
actionButtonPrepend	操作按钮前置插槽, 可插入内容到提交按钮前面
actionButtonAppend	操作按钮后置插槽, 可插入内容到重置按钮后面

对外导出工具方法

import { defineAcroDynamicFormField, defineAcroDynamicFormFields, defineAcroDynamicFormPreset } from '@mixte/snippets/acro-dynamic-form';

defineAcroDynamicFormField; // 定义单个字段配置
defineAcroDynamicFormFields; // 定义字段配置列表
defineAcroDynamicFormPreset; // 定义预设

类型定义

字段配置

/** 字段配置 */
type AcroDynamicFormField = AcroDynamicFormComponentField | AcroDynamicFormFieldBase;

/** 字段通用配置 */
interface AcroDynamicFormFieldBase {
  /** 字段名 */
  field: string;
  /** 标签 */
  label?: string;
  /** 默认值 */
  defaultValue?: any;
  /** 校验规则 */
  rules?: FieldRule | FieldRule[];
  /**
   * 触发校验的事件
   * @default ['change', 'blur']
   */
  validateTrigger?: FormItemInstance['validateTrigger'];
  /** 传递给 FormItem 组件的参数 */
  formItemProps?: Omit<FormItemInstance['$props'], 'field' | 'label' | 'rules' | 'validateTrigger'>;
  /** 传递给 FormItem 组件的插槽 */
  formItemSlots?: {
    /** 标签 */
    label?: () => VNodeChild;
    /** 帮助信息 */
    help?: () => VNodeChild;
    /** 额外内容 */
    extra?: () => VNodeChild;
    /** 其他插槽 ( 预留 ) */
    [key: string]: ((...args: any[]) => VNodeChild) | undefined;
  };
  /** 字段类型 */
  type?: string;
  /** 传递给组件的参数 */
  componentProps?: Record<string, any>;
  /** 传递给组件的插槽 */
  componentSlots?: Record<string, (...args: any[]) => VNodeChild>;
  /** 组件渲染函数或插槽名称 */
  render?: ((options: RenderOptions) => VNodeChild) | string;
  /** 预设 */
  preset?: symbol | symbol[];
}

/** 组件字段配置 */
type AcroDynamicFormComponentField = {
  [T in AcroDynamicFormFieldType]: Omit<AcroDynamicFormFieldBase, 'type' | 'componentProps'> & {
    /** 字段类型 */
    type: T;
    /** 传递给组件的参数 */
    componentProps?: Omit<AcroDynamicFormFieldComponentPropsMap[T], 'modelValue'>;
  };
}[AcroDynamicFormFieldType];

/** 字段类型 */
type AcroDynamicFormFieldType = keyof AcroDynamicFormFieldComponentPropsMap;

/** 字段配置组件参数映射 */
interface AcroDynamicFormFieldComponentPropsMap {
  'input': InputInstance['$props'];
  'input-group': InputGroupInstance['$props'];
  'input-number': InputNumberInstance['$props'];
  'input-password': InputPasswordInstance['$props'];
  'input-search': InputSearchInstance['$props'];
  'input-tag': InputTagInstance['$props'];
  'textarea': TextareaInstance['$props'];
  'select': SelectInstance['$props'];
  'cascader': CascaderInstance['$props'];
  'cascader-panel': CascaderPanelInstance['$props'];
  'tree-select': TreeSelectInstance['$props'];
  'date-picker': DatePickerInstance['$props'];
  'time-picker': TimePickerInstance['$props'];
  'year-picker': YearPickerInstance['$props'];
  'month-picker': MonthPickerInstance['$props'];
  'quarter-picker': QuarterPickerInstance['$props'];
  'week-picker': WeekPickerInstance['$props'];
  'range-picker': RangePickerInstance['$props'];
  'checkbox': CheckboxInstance['$props'];
  'checkbox-group': CheckboxGroupInstance['$props'];
  'radio': RadioInstance['$props'];
  'radio-group': RadioGroupInstance['$props'];
  'switch': SwitchInstance['$props'];
  'upload': UploadInstance['$props'];
  'transfer': TransferInstance['$props'];
  'slider': SliderInstance['$props'];
  'rate': RateInstance['$props'];
  'auto-complete': AutoCompleteInstance['$props'];
  'mention': MentionInstance['$props'];
  'verification-code': VerificationCodeInstance['$props'];
  'color-picker': ColorPickerInstance['$props'];
}

操作按钮区域配置

/** 操作按钮区域配置 */
interface ActionButtonAreaOptions {
  /**
   * 是否显示操作按钮区域
   * @default true
   */
  show?: boolean;
  /** 传递给操作按钮区域 FormItem 组件的参数 */
  props?: FormItemInstance['$props'];
  /** 传递给操作按钮区域 Space 组件的参数 */
  spaceProps?: SpaceInstance['$props'];
}

提交按钮配置

/** 提交按钮配置 */
interface SubmitButtonOptions {
  /**
   * 是否显示提交按钮
   * @default true
   */
  show?: boolean;
  /**
   * 提交按钮文字
   * @default '提交'
   */
  text?: string;
  /** 传递给提交按钮组件的参数 */
  props?: ButtonInstance['$props'];
}

重置按钮配置

/** 重置按钮配置 */
interface ResetButtonOptions {
  /**
   * 是否显示重置按钮
   * @default true
   */
  show?: boolean;
  /**
   * 重置按钮文字
   * @default '重置'
   */
  text?: string;
  /** 传递给重置按钮组件的参数 */
  props?: ButtonInstance['$props'];
}