# `<Form />`

组件继承了 element-plus form 所有属性, 并扩展了更多属性

<Form v-model="demoForm" :props="formProps" :loading="false" style="margin-bottom: 20px">
  <template #form-address>字段插槽</template>
</Form>

<!-- 表单项单独使用 -->
<FormItem
  v-model="formItem"
  :items="[
    {
      prop: 'formItem',
      label: '',
      type: 'selectRemote',
      remoteUrl: '/api',
      remoteParams: {},
      remoteFilterKey: 'keyword',
      remoteInit: true,
      remoteValue: 'code',
      ...
    },
  ]"
></FormItem>

<script setup>
import { ref } from "vue"
const formProps = [{ prop: "address", label: "地址", type: "text", disabled: false }]
const demoForm = ref({})
</script>

# 表单属性

属性名	描述说明	类型	默认
model-value / v-model	表单数据对象	Object	-
auto-remote	是否自动获取远程数据(类型为 selectRemote 生效)	Boolean	true
loading	发起请求时可控制提交按钮状态	Boolean	false
disable	是否禁用表单	Boolean	false
props	表单配置(详情见 props 配置)	Array	-
rules	表单验证, 同 element-plus 表单验证	Object	-
label-width	表单项标题宽度	String/Number	'100px'
grid	是否显示为展示样式	Boolean	false
confirm-text	提交按钮文字	String	'提交'
button-align	表单按钮位置, 为 CSS justify-content 的值	String	'center'
button-vertical	表单按钮在上还是下, top/bottom/flowing	String	'bottom'
enable-button	是否启用表单按钮	Boolean	true
enable-reset	是否启用重置按钮	Boolean	true
enable-clear	是否启用清空按钮	Boolean	true
enable-enter	是否启用回车触发 submit 事件	Boolean	true
column-count	表单分为几列	String/Number	1
size	表单项大小, 同 element-plus size	String	'default'
do-not-clear	在清空时排除清空字段	Array[Key]	-
do-not-init-remote	在初始化时排除自动拉取数据的字段(类型为 selectRemote 生效)	Array[Key]	-

# 表单项属性

属性	描述说明	类型
prop	字段名	String
attrs	同 element-plus 表单元素项配置	Object
label	显示名	String
type	字段类型(详情见 props type)	String
placeholder	占位描述	String
disabled	是否禁用	Boolean
input-type	type 为 text 设置为 number 可启用数量选择框	String
min	input-type 为 number 设置最小值	Number
max	input-type 为 number 设置最大值	Number
options	type 为 select 时, 下拉选项 (除必要属性可自行扩展其他属性)	Array[{label, value, disabled}]
multiple	type 为 select 时, 是否多选 , type 为 upload 时, 是否多文件	Boolean
collapse-tags	type 为 select 时, 多选时是否将选中值按文字的形式展示	Boolean
cascade-items	type 为 cascade 时的配置(详情见 data cascade item)	Array
maxlength	type 为 textarea 时设置输入最大长度	Number
remoteUrl	远程接口(仅 type 为 selectRemote 有效)	String
remoteInit	远程下拉是否初始化	Boolean
remoteParams	远程接口参数(仅 type 为 selectRemote 有效)	String
remoteLabel	远程下拉显示 key, 默认: name	String
remoteValue	远程下拉返回值 key, 默认: id	String
remoteFilterKey	远程下拉搜索 key: 默认: 'name'	String
beforeInitRemote	远程下拉发起请求之前回调(可修改请求参数)	Funtion(query, remoteParams,item)
formShow	是否显示表单项	Boolean
formItemProps	表单项的 Props (同 element plus form item)	Object
accept	文件上传接受的文件类型	String
size	文件上传大小文案	String

# 表单项属性 Type 类型

属性	描述说明
text	输入框
password	密码框
checkbox	多选
radio	单选
textarea	文本域
select	下拉选项
selectRemote	带远程搜索的下拉(remoteUrl: 远程接口, remoteParams: 请求参数 )
treeSelect	下拉树
date	单日期
year	年
month	月
week	周
dates	日期数组
datetime	单日期和时间
daterange	日期范围
monthrange	月范围
datetimerange	日期范围和时间
switch	开关
cascade	级联组件(组件配置见(详情见 data cascade item))
upload	base64 上传, 非流直接上传

# 表单项属性为 cascade 的配置

联动组件 type 类型只能是 select

属性	描述说明	类型
method	请求类型	String
cascadeKeys	显示 key 和值 key	['name', 'id']
cascadeUrl	远程请求地址	String
cascadeParams	远程请求参数	Object
cascadeData	远程请求参数	Object
cascadeMaxLevel	必须选择的级别,默认 1	String/Number
cascadeItems	级联的 Options	Array
cascadeStatic	是否静态级联	Boolean
cascadeVertical	是否垂直的	Boolean
oneSelect	如果为 true 则启用 element-plus 的 el-cascader	Boolean
oneSelectProps	同 el-cascader props	Object
beforeInitOptions	发起请求前的处理(可处理请求参数, cascadeItems 配置项的属性)	Function(val, next, item)

# 表单事件

事件	描述说明	类型
before-submit	提交触发之前	Function(form)
submit	提交验证通过之后	Function(form)
clear	清空按钮触发时	Function(clearAll: Boolean)
reset	重置按钮触发时	Function()
change	表单项修改时	Function(val, item)
focus	表单项获取焦点时	Function()
blur	表单项失去焦点时	Function()
init-remote-complete	type 为 selectRemote 并且 auto-remote 为 true 时在远程接口调用完成时	Function(query, item)

# 表单方法

方法	描述说明	类型
clear	清空表单, 参数为 true 时强制清空所有(包含:do-not-clear 字段)	Function(Boolean)
submit	提交表单	Function ()
validate	表单校验	Function(callback(Boolean))
resetFields	重置表单	Function()
disabled	禁用表单	Function(Boolean)
getData	获取表单数据	Function() => Object
getValue	获取表单字段值	Function(Key) => Value
setValue	设置表单字段值	Function(Key, Value)
setAttr	设置表单配置属性的值	Function(Key, Attr, Value)

# 表单项方法

方法	描述说明	类型
initRemote	单独使用 FormItem 时, type 为 selectRemote 时手动初始化	Function(query, FormItem)
validate	单独使用 FormItem 时手动校验	Function() => Boolean

# 表单插槽

插槽	描述说明
form-[slot]	动态字段名插槽
form-[slot]-right	动态字段插槽内容下方
form-[slot]-error	动态字段校验错误插槽
buttons	提交按钮和重置按钮之间

← <Dialog /> <Pagination /> →