字段操作

API 提供了一系列丰富的字段操作方法，允许开发者在表单的各个阶段动态控制和操作表单中的字段。这些方法帮助您更灵活地处理表单数据和交互需求。

获取表单字段

fields 方法返回表单中所有字段的名称列表。该方法非常适合在需要遍历表单字段或动态操作多个字段时使用。

type fields = ()=>string[]

• 示例：

获取指定字段值

getValue 方法根据字段名获取对应字段的当前值。

type getValue = (field:string) => any

• 示例：

设置表单值

覆盖字段值 (coverValue)

coverValue 方法会覆盖未定义的字段，设置为 undefined。

type coverValue = (formData:{[field:string]:any}) => void

• 示例： 只传入商品名称时，价格会被覆盖成空值。

合并字段值 (setValue)

setValue 方法会合并传入的字段值，formData 中未定义的字段不做修改。

interface setValue {
    (formData:{[field:string]:any}): void
    (field:string, value:any): void
}

• 示例： 未传入的字段保持原值。

别名方法changeValue, changeField

重置表单值

resetFields 方法用于重置表单的所有字段值，或重置指定字段的值。

interface resetFields {
    ():void
    (field:string[]):void
}

• 示例： 先修改输入框，再分别重置全部或只重置商品名称。

隐藏字段 (不渲染)

隐藏字段的组件不会渲染，DOM 节点不生成，因此表单验证不会生效。

interface hidden {
    //隐藏全部组件
    (status:Boolean):void
    //隐藏指定组件
    (status:Boolean, field:string):void
    //隐藏部分组件
    (status:Boolean, field:string[]):void 
}

• 示例： 隐藏后组件不会渲染。

获取组件隐藏状态

hiddenStatus 方法用于获取指定字段是否处于隐藏状态。

type hiddenStatus = (field:string)=>Boolean

• 示例： 上面的示例里，「查看隐藏状态」会返回 true 或 false。

隐藏组件 (渲染)

通过 display: none 隐藏组件，组件仍然渲染但不显示。

interface display {
    //隐藏全部组件
    (status:Boolean):void
    //隐藏指定组件
    (status:Boolean, field:string):void 
    //隐藏部分组件
    (status:Boolean, field:string[]):void 
}

• 示例： display(false) 隐藏组件，DOM 仍然存在。display(true) 重新显示。

获取组件隐藏状态

displayStatus 方法用于获取指定字段是否处于显示状态。

type displayStatus = (field:string)=>Boolean

• 示例： 上面的示例里，「查看显示状态」会返回 true 或 false。

禁用组件

disabled 方法用于禁用表单中的所有组件、指定组件或部分组件。

interface disabled {
    //禁用全部组件
    (status:Boolean):void 
    //禁用指定组件
    (status:Boolean, field:string):void 
    //禁用部分组件
    (status:Boolean, field:string[]):void 
}

• 示例：

切换必填

required 方法用于切换字段的自定义必填属性，对应规则里的 $required 或 effect.required。不传字段时作用于全部字段。

interface required {
    //切换全部字段
    (status:Boolean):void
    //切换指定字段
    (status:Boolean, field:string):void
    //切换部分字段
    (status:Boolean, field:string[]):void
}

当前值是对象时，只修改对象里的 required，message 等配置会保留。当前值是布尔值、字符串或未设置时，会把必填状态写成 true 或 false。

• 示例：

删除字段

removeField 方法用于从表单中删除指定组件。

type removeField = (field:string) => Rule

• 示例：

刷新组件渲染

sync 方法用于手动刷新指定字段的组件渲染。

interface sync{
    //通过 field 更新指定组件
    (field:string):void
    //通过生成规则更新指定组件
    (rule:Rule):void
}

• 示例：

组件方法

exec 方法用于手动执行指定字段组件的某个方法。

type exec = (field:string, method:string, ...args:any[]) => any

• 示例：

method 方法用于获取指定字段组件的某个方法，以便后续手动调用。

type method = (field:string, method:string) => Function

• 示例： 上面的示例里，「method 聚焦」会先取出 focus 再调用。

手动触发组件事件

trigger 方法用于手动触发指定字段组件的事件。

type trigger = (field:string, event:string, ...args:any[]) => void

• 示例：

获取组件的vm/dom元素

el 方法用于获取指定字段组件的 Vue 实例或 DOM 元素。

type el = (field:string) => Vue|Document|undefined

• 示例：

滚动至指定字段

scrollTo 方法将指定表单项滚动到可视区域内，底层行为与 DOM scrollIntoView 一致。第二个参数 arg 可选：传入 boolean 时对应 alignToTop；传入对象时使用 ScrollIntoViewOptions。

type scrollTo = (
  id: string,
  arg?: boolean | ScrollIntoViewOptions
) => void

• 示例：

聚焦指定字段

focus 方法用于让指定表单项获得键盘焦点，便于在提交失败或远程校验后引导用户修正对应输入。

type focus = (id: string) => void

• 示例：

关闭frame组件的弹出框

closeModal 方法用于关闭指定 frame 组件的弹出框。

type closeModal = (field:string) => void

• 示例：

示例

动态隐藏和显示表单字段

选择「公司客户」时显示公司名称。

批量设置表单字段的值

移除不必要的表单字段

关闭开关后会删除特殊字段。

动态同步表单数据

单价或数量变化时计算总价，并刷新总价组件。

提交后清空表单

验证失败后定位字段

验证未通过时，滚动到价格并聚焦。