Skip to content

API

高级版FormCreate设计器强势登场,让表单设计更简单!

获取API

  • 全局方法
js
const fApi = formCreate(rules)
  • 组件模式
html
<form-create v-model:api="fApi"></form-create>
js
export default {
  data(){
    return {
      fApi: null
    }
  }
}

数据结构

ts
interface Api {
  //表单配置
  readonly config: Options;
  readonly options: Options;
  //表单数据
  readonly form: Object;
  //表单生成规则
  readonly rule: Rule[];
  //父级表单的api
  readonly parent: Api | undefined;
  //最顶级表单的api
  readonly top: Api | undefined;
  //子表单的api
  readonly children: Api[];
  btn: {
    //设置表单提交按钮加载状态
    loading(loading: boolean): void;
    //设置表单提交按钮禁用状态
    disabled(disabled: boolean): void;
    //设置表单提交按钮显示状态
    show(show: boolean): void;
  }
  resetBtn: {
    //设置表单重置按钮加载状态
    loading(loading: boolean): void;
    //设置表单重置按钮禁用状态
    disabled(disabled: boolean): void;
    //设置表单重置按钮显示状态
    show(show: boolean): void;
  }
  //获取组件的el/vm
  el(id: string): any;
  //获取`Form`组件的vm
  formEl(): undefined | ComponentInternalInstance;
  //获取`FormItem`组件的vm
  wrapEl(id: string): undefined | ComponentInternalInstance;
  //更新表单提交按钮配置
  submitBtnProps(props: ButtonProps): void;
  //更新表单重置按钮配置
  resetBtnProps(props: ButtonProps): void;
  //获取表单数据
  formData(): Object;
  formData(field: string[]): Object;
  //根据field获取value
  getValue(field: string): any;
  //设置表单数据
  coverValue(formData: Object): void;
  setValue(formData: Object): void;
  setValue(field: string, value: any): void;
  //根据field删除规则
  removeField(field: string): Rule;
  //删除表单生成规则中的 rule
  removeRule(rule: Rule): Rule;
  //获取所有字段名
  fields(): string[];
  //后置追加规则
  append(rule: Rule): void;
  append(rule: Rule, field: string): void;
  append(rule: Rule, field: string, child: boolean): void;
  //前置插入规则
  prepend(rule: Rule): void;
  prepend(rule: Rule, field: string): void;
  prepend(rule: Rule, field: string, child: boolean): void;
  //隐藏组件
  hidden(hidden: Boolean): void;
  hidden(hidden: Boolean, field: string | Array<string>): void;
  display(hidden: Boolean): void;
  display(hidden: Boolean, field: string | Array<string>): void;
  //获取隐藏状态
  hiddenStatus(field: String): Boolean;
  displayStatus(field: String): Boolean;
  //禁用组件
  disabled(disabled: Boolean): void;
  disabled(disabled: Boolean, field: string | Array<string>): void;
  //获取所有的表单组件规则
  model(): { [field: string]: Rule };
  //获取所有定义`name`的组件规则
  component(): { [name: string]: Rule };
  //重新加载表单
  reload(rules: Rule[]): void;
  //更新表单配置
  updateOptions(options: Options): void;
  //监听提交表单
  onSubmit(fn: (formData: Object, api: Api) => void): void;
  //提交表单
  submit(success?: (formData: Object, api: Api) => void, fail?: (api: Api) => void): Promise<any>;
  //同步指定规则
  sync(field: string | string[]): void;
  sync(rule: Rule | Rule[]): void;
  //重新渲染表单
  refresh(): void;
  refreshOptions(): void;
  //隐藏表单
  hideForm(hide?: Boolean): void;
  //表单修改状态
  changeStatus(): Boolean;
  //重置表单修改状态
  clearChangeStatus(): void;
  //设置自定义属性
  setEffect(id: string, attr: string, value: any): void;
  //清理自定义属性数据
  clearEffectData(id: string, attr?: string): void;
  //更新组件规则
  updateRule(field: string, rule: Rule): void;
  updateRule(rules: { [field: string]: Rule }): void;
  mergeRule(field: string, rule: Rule): void;
  mergeRules(rules: { [field: string]: Rule }): void;
  //获取组件规则
  getRule(id: string): Rule;
  getRule(id: string, origin: true): Rule;
  getRule(id: string, origin: false): Rule;
  //获取组件最终渲染规则
  getRenderRule(id: string): Rule;
  //通过`name`获取组件规则
  getRefRule(id: string): Rule | Rule[];
  //更新组件验证规则
  updateValidate(id: string, validate: Object[], merge?: Boolean): Promise<any>;
  updateValidates(validates: { [id: string]: Object[] }, merge?: Boolean): Promise<any>;
  refreshValidate(): void;
  //清理表单验证信息
  clearValidateState(fields?: string | string[], clearSub?: Boolean): void;
  clearSubValidateState(fields?: string | string[]): void;
  //表单验证
  validate(callback?: (state: any) => void): Promise<any>;
  validateField(field: string, callback?: (state: any) => void): Promise<any>;
  //获取组件的方法
  method(id: string, name: string): (...args: any[]) => any;
  //手动执行组件的方法
  exec(id: string, name: string, ...args: any[]): any;
  //获取表单的json生成规则
  toJson(space?: string | number): string;
  //手动触发组件的事件
  trigger(id: string, event: string, ...args: any[]): void;
  //关闭指定frame组件的弹出框
  closeModal(id: string): void;
  //重置表单
  resetFields(): void;
  resetFields(field: string | string[]): void;
  //获取指定子表单
  getSubForm(field: string): Api | Api[];
  //表单渲染后执行回调
  nextTick(fn: (api: Api) => void): void;
  //执行回调后重新渲染表单
  nextRefresh(fn: Function): void;
  //执行回调后同步formData
  deferSyncValue(fn: Function, autoSync?: boolean): void;
  //手动触发表单的事件
  emit(event: string, ...args: any[]): void;
  //监听表单事件
  on(event: string | string[], callback: Function): this;
  //监听表单事件,只触发一次
  once(event: string | string[], callback: Function): this;
  //取消监听事件
  off(event?: string | string[], callback?: Function): this;
}

属性

生成规则

typescript
type rule = Rule[]
  • 用法
js
const rules = fApi.rule

全局配置

typescript
type config = Object
  • 用法
js
const options = fApi.config

别名 fApi.options

表单数据

typescript
type form = { [field:string]:any }
  • 用法
js
const formData = fApi.form
formData.goods_name = 'huawei'

该属性是双向绑定的

字段操作

获取表单字段

typescript
type fields = ()=>string[]
  • 用法
js
const fields = fApi.fields()

获取指定字段值

typescript
type getValue = (field:string) => any
  • 用法
js
const value = fApi.getValue('goods_name')

设置表单值

覆盖方式

未定义的字段会设置为 null

typescript
type coverValue = (formData:{[field:string]:any}) => void
  • 用法
js
fApi.coverValue({goods_name:'HuaWei'})

合并方式

未定义的字段不做修改

typescript
interface setValue {
    (formData:{[field:string]:any}): void
    (field:string, value:any): void
}
  • 用法
js
fApi.setValue({goods_name:'HuaWei'})

别名方法changeValue, changeField

重置表单值

typescript
interface resetFields {
    ():void
    (field:string[]):void
}
  • 用法
js
fApi.resetFields()

隐藏字段 (不渲染)

组件不渲染

Dom 节点不渲染, 可以避免表单验证生效

typescript
interface hidden {
    //隐藏全部组件
    (status:Boolean):void
    //隐藏指定组件
    (status:Boolean, field:string):void
    //隐藏部分组件
    (status:Boolean, field:string[]):void 
}
  • 用法
js
fApi.hidden(true, 'goods_name')

获取组件隐藏状态

typescript
type hiddenStatus = (field:string)=>Boolean
  • 用法
js
const status = fApi.hiddenStatus('goods_name')

隐藏组件 (渲染)

css隐藏

通过 display:none 隐藏组件

typescript
interface display {
    //隐藏全部组件
    (status:Boolean):void
    //隐藏指定组件
    (status:Boolean, field:string):void 
    //隐藏部分组件
    (status:Boolean, field:string[]):void 
}
  • 用法
js
fApi.display(false, 'goods_name')

获取组件隐藏状态

typescript
type displayStatus = (field:string)=>Boolean
  • 用法
js
const status = fApi.displayStatus('goods_name')

禁用组件

typescript
interface disabled {
    //禁用全部组件
    (status:Boolean):void 
    //禁用指定组件
    (status:Boolean, field:string):void 
    //禁用部分组件
    (status:Boolean, field:string[]):void 
}
  • 用法
js
fApi.disabled(true, 'goods_name')

删除字段

typescript
type removeField = (field:string) => Rule
  • 用法
js
const rule = fApi.removeField('goods_name')

刷新组件渲染

typescript
interface sync{
    //通过 field 更新指定组件
    (field:string):void
    //通过生成规则更新指定组件
    (rule:Rule):void
}
  • 用法
js
fApi.sync('goods_name')

组件方法

执行组件方法

typescript
type exec = (field:string, method:string, ...args:any[]) => any
  • 用法
js
fApi.exec('goods_name','force')

获取组件方法

typescript
type method = (field:string, method:string) => Function
  • 用法
js
const method = fApi.method('goods_name','force')

手动触发组件事件

typescript
type trigger = (field:string, event:string, ...args:any[]) => void
  • 用法
js
fApi.trigger('goods_name', 'on-change')

获取组件的vm/dom元素

typescript
type el = (field:string) => Vue|Document|undefined
  • 用法
js
const vm = fApi.el('goods_name')

关闭frame组件的弹出框

typescript
type closeModal = (field:string) => void
  • 用法
js
fApi.closeModal('frame')

规则操作

获取规则

typescript
interface getRule {
    (field:string):Rule
    (field:string, origin: true): Rule
}
  • 用法
js
const rule = fApi.getRule('goods_name')

通过name获取组件的规则

typescript
interface getRefRule {
    (name:string):Rule | Rule[]
}
  • 用法
js
const rule = fApi.getRefRule('input')

获取组件最终的渲染规则

typescript
interface getRenderRule {
    (field:string):Rule
}
  • 用法
js
const rule = fApi.getRenderRule('input')

插入规则

前置插入

typescript
interface prepend {
    //插入到第一个
    (rule:Rule):void 
    //插入指定字段前面
    (rule:Rule, field:string):void
    //插入到指定字段 children 中
    (rule:Rule, field:string, child:true):void
}
  • 用法
js
fApi.prepend({
     type:"input",
     title:"商品简介",
     field:"goods_info",
     value:"",
     props: {
         "type": "text",
         "placeholder": "请输入商品简介",
     },
     validate:[
         { required: true, message: '请输入商品简介', trigger: 'blur' },
     ],
}, 'goods-name')

后置追加

typescript
interface append {
    //插入到最后一个
    (rule:Rule):void 
    //插入指定字段后面
    (rule:Rule, field:string):void
    //插入到指定字段 children 中
    (rule:Rule, field:string, child:true):void
}
  • 用法
js
fApi.append({
     type:"input",
     title:"商品简介",
     field:"goods_info",
     value:"",
     props: {
         "type": "text",
         "placeholder": "请输入商品简介",
     },
     validate:[
         { required: true, message: '请输入商品简介', trigger: 'blur' },
     ],
}, 'goods-name')

删除指定规则

typescript
type removeRule = (rule:Rule) => Rule
  • 用法
js
const rule = {type:'input', /** ... **/}
fApi.removeRule(rule)

获取表单组件规则

typescript
interface model{                
    //获取Object规则
    ():Rule[]              
    //获取原始规则
    (origin:true):Rule[]
}
  • 用法
js
const rules = fApi.model()

获取自定义组件规则

定义 name 配置后才可以获取到

typescript
interface component{                
    //获取Object规则
    ():Rule[]              
    //获取原始规则
    (origin:true):Rule[]
}
  • 用法
js
const componentRules = fApi.component()

更新指定规则

合并更新

typescript
type mergeRule = (rule:Rule)=>void
  • 用法
js
fApi.mergeRule('goods_name', {hidden: true})

批量更新

typescript
type mergeRules = (rules:{[field:string]:Rule})=>void
  • 用法
js
fApi.mergeRules({'goods_name': {hidden: true}})

覆盖更新

typescript
type updateRule = (rule:Rule)=>void
  • 用法
js
fApi.updateRule('goods_name', {hidden: true})
  • 例子🌰:

CodeSandbox

@vue/componsition-api版本

批量更新

typescript
type updateRules = (rules:{[field:string]:Rule})=>void
  • 用法
js
fApi.updateRules({'goods_name': {hidden: true}})

更新自定义属性

typescript
type setEffect = (id:string, attr: string, value:any)=>void
  • 用法
js
fApi.setEffect('goods_name', 'required', false)

验证操作

验证表单

typescript
type validate = (callback:(...args:any[]) => void)=> Promise
  • 用法
js
fApi.validate((valid, fail) => {
    if(valid){
        //todo 表单验证通过
    }else{
        //todo 表单验证未通过
    }
})

验证指定字段

typescript
type validateField = (field, callback:(...args:any[]) => void)=> Promise
  • 用法
js
fApi.validateField('goods_name', (valid, fail) => {
    if(valid){
        //todo 字段验证通过
    }else{
        //todo 字段验证未通过
    }
})

更新验证规则

typescript
interface updateValidate{
    //覆盖更新
    (field:string, validate:Object[]):void
    //合并更新
    (field:string, validate:Object[], merge:true):void
}
  • 用法
js
fApi.updateValidate('goods_name',[{required:true}], true)

批量更新

typescript
interface updateValidates{
    //覆盖更新
    (validates:{[field:string]: Object[]}):void
    //合并更新
    (validates:{[field:string]: Object[]}, merge:true):void
}
  • 用法
js
fApi.updateValidates({'goods_name': [{required:false}]})

刷新验证规则

如果修改验证规则后没有生效,可通过该方法手动刷新

typescript
type refreshValidate = ()=>void
  • 用法
js
fApi.refreshValidate()

清除表单验证状态

typescript
interface clearValidateState {
    ():void
    (field:string, clearSub?:boolean):void
    (field:string[], clearSub?:boolean):void
}
  • 用法
js
fApi.clearValidateState('goods_name')

清除子表单验证状态

可清除group,object子表单的验证状态

typescript
interface clearSubValidateState {
    (field:string):void
    (field:string[]):void
}
  • 用法
js
fApi.clearSubValidateState('goods_name')

表单操作

获取表单组件的vm/dom元素

typescript
type formEl = () => Vue|Document|undefined
  • 用法
js
const vm = fApi.formEl()

获取FormItem组件的vm/dom元素

typescript
type wrapEl = (field:string) => Vue|Document|undefined
  • 用法
js
const vm = fApi.wrapEl('goods_name')

获取表单数据

typescript
interface formData {
    //获取全部数据
    (): {[field:string]:any }
    //获取部分字段的数据
    (field:string[]): {[field:string]:any }
}
  • 用法
js
const formData = fApi.formData()

该方法的返回值不是双向绑定

获取表单数据 (双向绑定)

typescript
type bind = () => { [field:string]:any }
  • 用法
js
const formData = fApi.bind()

该方法是form属性的别名

表单中的值是否发生变化状态

typescript
type changeStatus = ()=>Boolean
  • 用法
js
const status = fApi.changeStatus()

清除变化状态

typescript
type clearChangeStatus = ()=>void
  • 用法
js
fApi.clearChangeStatus()

修改提交按钮

typescript
type submitBtnProps = (props:Object) => void
  • 用法
js
fApi.submitBtnProps({disabled:true})
  • 快捷操作:

  • fApi.btn.loading(true) 设置提交按钮进入loading状态

    • fApi.btn.disabled(true) 设置提交按钮禁用状态
    • fApi.btn.show(true) 设置提交按钮显示状态

修改重置按钮

typescript
type resetBtnProps = ( props:Object) => void
  • 用法
js
fApi.resetBtnProps({disabled:true})
  • 快捷操作:

  • fApi.resetBtn.loading(true) 设置重置按钮进入loading状态

    • fApi.resetBtn.disabled(true) 设置重置按钮禁用状态
    • fApi.resetBtn.show(true) 设置重置按钮显示状态

更新表单配置

typescript
type updateOptions = (options:Object) => void
  • 用法
js
fApi.updateOptions({form:{inline:true}})
  • 例子🌰

CodeSandbox

更新表单提交事件

typescript
type onSubmit = (callback:(formData:Object,fApi:fApi)=>void) => void
  • 用法
js
fApi.onSubmit((formData, fApi)=>{
    //todo 提交表单
})

刷新表单配置

typescript
type refreshOptions = ()=>void
  • 用法
js
fApi.refreshOptions()

刷新表单渲染

typescript
type refresh = ()=>void
  • 用法
js
fApi.refresh()

隐藏表单

typescript
type hideForm = (hide:Boolean)=>void
  • 用法
js
fApi.hideForm(true)

重载表单

typescript
interface reload{
    ():void
    (rules:Rule[]):void
}
  • 用法
js
fApi.reload()

表单渲染后回调

typescript
type nextTick = (callback:Function) => void
  • 用法
js
fApi.nextTick(() => {
    //todo 渲染回调
})

自动刷新

callback执行后如果表单没刷新, 会自动刷新表单渲染

typescript
type nextRefresh = (callback:Function) => void
  • 用法
js
fApi.nextRefresh(() => {
    //todo 表单操作
})

提交表单

typescript
type submit = (success?: (formData: Object, $f: fApi) => void, fail: ($f: fApi) => void)=> Promise
  • 用法
js
fApi.submit((formData, fapi) => {
    //todo 提交表单
},()=>{
    //todo 表单验证未通过
})

获取表单json规则

typescript
type toJson = () => string
  • 用法
js
const jsonString = fApi.toJson()

触发表单事件

typescript
type emit = (emitName:string, ...args:any[]) => void
  • 用法
js
fApi.emit('custom', 1)

监听表单事件

  • 参数

    • {string} emitName 生成规则emit事件名称
    • {Function} callback 回调方法
  • 用法

js
  /*
  rule:{
    field:'goods-name'
    //...
    emit:['on-change']
  }
  */


fApi.on('goods-name-on-change',() => {
    //TODO
  })

监听表单事件,只触发一次

  • 参数

    • {string} emitName 生成规则emit事件名称
    • {Function} callback 回调方法
  • 用法

js
  /*
    rule:{
      field:'goods-name'
      //...
      emit:['on-change']
    }
    */
  fApi.once('goods-name-on-change',() => {
    //TODO
  })

监听一个自定义事件,但是只触发一次,在第一次触发之后移除监听器

移除表单事件监听器

  • 参数

    • {string | Array} emitName 生成规则emit事件名称
    • {Function} [callback] 回调方法
  • 用法

移除自定义事件监听器。

  • 如果没有提供参数,则移除所有的事件监听器;

  • 如果只提供了事件,则移除该事件所有的监听器;

  • 如果同时提供了事件与回调,则只移除这个回调的监听器。

js
  fApi.off('goods-name-on-change')
  // fApi.off('goods-name-on-change', fn)

fApi.set

  • 参数

    • {object} node
    • {string} key
    • {any} value
  • 用法

js
fApi.set(field.rule.col,'span',12)

如果修改组件的规则后页面没有更新时可以尝试使用该方法,该方法与Vue.$set相同