# API

# 获取API

  • 全局方法

    const fApi = formCreate(rules)
    const fApi = vm.$formCreate(rules)
    
  • 组件模式

    <form-create v-model="fApi"></form-create>
    
    export default {
      data(){
        return {
          fApi: null
        }
      }
    }
    

# 属性

# 生成规则

type rule = FormRule[]
  • 用法
const rules = fApi.rule

# 全局配置

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

别名 fApi.options

# 表单数据

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

该属性是双向绑定的

# 字段操作

# 获取表单字段

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

# 获取指定字段值

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

# 设置表单值

覆盖方式 v2.5.0+

未定义的字段会设置为 null

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

合并方式

未定义的字段不做修改

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

别名方法changeValue, changeField

# 重置表单值

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

# 隐藏字段 (不渲染)

组件不渲染

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

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

# 获取组件隐藏状态

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

# 隐藏组件 (渲染)

css隐藏

通过 display:none 隐藏组件

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

# 获取组件隐藏状态

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

# 禁用组件

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

# 删除字段

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

# 刷新组件渲染

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

# 组件方法

执行组件方法 v2.5.0+

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

获取组件方法

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

# 手动触发组件事件

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

# 获取组件的vm/dom元素

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

# 关闭frame组件的弹出框

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

# 规则操作

# 获取规则

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

origin 参数 v2.5.0+ 支持

# 插入规则

前置插入

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

后置追加

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

# 删除指定规则

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

# 获取表单组件规则

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

origin 参数 v2.5.0+ 支持

# 获取自定义组件规则

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

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

origin 参数 v2.5.0+ 支持

# 更新指定规则

合并更新

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

# 批量更新

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

覆盖更新

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

# 批量更新

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

# 验证操作

# 验证表单

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

# 验证指定字段

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

# 更新验证规则

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

# 批量更新

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

# 刷新验证规则

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

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

# 清除表单验证状态

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

# 清除子表单验证状态

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

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

# 表单操作

# 获取表单数据

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

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

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

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

该方法是form属性的别名

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

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

# 清除变化状态

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

# 修改提交按钮

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

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

# 修改重置按钮

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

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

# 更新表单配置

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

# 更新表单提交事件

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

# 刷新表单配置

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

# 刷新表单渲染

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

# 隐藏表单

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

# 重载表单

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

# 销毁表单

type destroy = () => void
  • 用法
fApi.destroy()

# 表单渲染后回调

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

# 自动刷新

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

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

# 提交表单

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

# 获取表单json规则

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

# 监听表单事件

  • 参数

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

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

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

  • 参数

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

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

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

# 移除表单事件监听器

  • 参数

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

    移除自定义事件监听器。

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

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

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

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

# fApi.set

  • 参数

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

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

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