platforms/.agents/skills/arco-design-vue/references/components/data-entry/form.md

name, description, user-invocable

name	description	user-invocable
arco-vue-form	Arco Design Vue 表单 Form 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-form>`、属性、事件、插槽、示例和实现细节。	false

表单 Form

简介

表单的基本用法。

基本用法

<template>
  <a-form :model="form" :style="{ width: '600px' }" @submit="handleSubmit">
    <a-form-item field="name" tooltip="Please enter username" label="Username">
      <a-input
        v-model="form.name"
        placeholder="please enter your username..."
      />
    </a-form-item>
    <a-form-item field="post" label="Post">
      <a-input v-model="form.post" placeholder="please enter your post..." />
    </a-form-item>
    <a-form-item field="isRead">
      <a-checkbox v-model="form.isRead"> I have read the manual </a-checkbox>
    </a-form-item>
    <a-form-item>
      <a-button html-type="submit">Submit</a-button>
    </a-form-item>
  </a-form>
  {{ form }}
</template>

<script>
import { reactive } from 'vue';

export default {
  setup() {
    const form = reactive({
      name: '',
      post: '',
      isRead: false,
    });
    const handleSubmit = (data) => {
      console.log(data);
    };

    return {
      form,
      handleSubmit,
    };
  },
};
</script>

API

<form> 属性

参数名	描述	类型	默认值	版本
model (必填)	表单数据对象	object	-
layout	表单的布局方式，包括水平、垂直、多列	'horizontal' | 'vertical' | 'inline'	'horizontal'
size	表单控件的尺寸	'mini' | 'small' | 'medium' | 'large'	'medium'
label-col-props	标签元素布局选项。参数同 <col> 组件一致	object	span: 5, offset: 0
wrapper-col-props	表单控件布局选项。参数同 <col> 组件一致	object	span: 19, offset: 0
label-align	标签的对齐方向	'left' | 'right'	'right'
disabled	是否禁用表单	boolean	-
rules	表单项校验规则	Record<string, FieldRule | FieldRule[]>	-
auto-label-width	是否开启自动标签宽度，仅在 layout="horizontal" 下生效。	boolean	false	2.13.0
id	表单 id 属性和表单控件 id 前缀	string	-
scroll-to-first-error	验证失败后滚动到第一个错误字段	boolean	false	2.51.0

<form> 事件

事件名	描述	参数
submit	表单提交时触发	data: {values: Record<string, any>; errors: Record<string, ValidatedError> | undefined} ev: Event
submit-success	验证成功时触发	values: Record<string, any> ev: Event
submit-failed	验证失败时触发	data: {values: Record<string, any>; errors: Record<string, ValidatedError>} ev: Event

<form> 方法

方法名	描述	参数	返回值	版本
validate	校验全部表单数据	callback: (errors: undefined | Record<string, ValidatedError>) => void	Promise<undefined | Record<string, ValidatedError>>
validateField	校验部分表单数据	field: string | string[] callback: (errors: undefined | Record<string, ValidatedError>) => void	Promise<undefined | Record<string, ValidatedError>>
resetFields	重置表单数据	field: string | string[]	-
clearValidate	清除校验状态	field: string | string[]	-
setFields	设置表单项的值和状态	data: Record<string, FieldData>	-
scrollToField	滚动到指定表单项	field: string	-	2.51.0

<form-item> 属性

参数名	描述	类型	默认值	版本
field	表单元素在数据对象中的path（数据项必填）	string	''
label	标签的文本	string	-
tooltip	提示内容	string	-	2.41.0
show-colon	是否显示冒号	boolean	false
no-style	是否去除样式	boolean	false
disabled	是否禁用	boolean	-
help	帮助文案	string	-
extra	额外显示的文案	string	-
required	是否必须填写	boolean	false
asterisk-position	可选择将星号置于 label 前/后	'start' | 'end'	'start'	2.41.0
rules	表单项校验规则（优先级高于 form 的 rules）	FieldRule | FieldRule[]	-
validate-status	校验状态	'success' | 'warning' | 'error' | 'validating'	-

仅列出常用项，低频属性按需查阅官方 API。

<form-item> 插槽

插槽名	描述	参数
label	标签	-
help	帮助信息	-
extra	额外内容	-

类型定义

FieldRule

参数名	描述	类型	默认值
type	校验的值的类型，默认为 'string'	'string' | 'number' | 'boolean' | 'array' | 'object' | 'email' | 'url' | 'ip'	-
required	是否必填	boolean	false
message	校验失败时展示的信息	string	-
length	校验长度（string, array）	number	-
maxLength	最大长度（string）	number	-
minLength	最小长度（string）	number	-
match	匹配校验（string）	RegExp	-
uppercase	大写（string）	boolean	false
lowercase	小写（string）	boolean	false
min	最小值（number）	number	-
max	最大值（number）	number	-
equal	校验数值（number）	number	-

仅列出常用项，低频属性按需查阅官方 API。

FieldData

参数名	描述	类型	默认值
value	字段的值	any	-
status	字段的状态	ValidateStatus	-
message	字段的错误信息	string	-

ValidatedError

参数名	描述	类型	默认值	版本
label	标签的文本	string	-	2.18.0
field	字段名	string	-
value	字段值	any	-
type	字段类型	string	-
isRequiredError	是否为 required 错误	boolean	false
message	错误信息	string	-

FormItemEventHandler

参数名	描述	类型	默认值
onChange	onChange	(ev?: Event) => void	-
onInput	onInput	(ev?: Event) => void	-
onFocus	onFocus	(ev?: Event) => void	-
onBlur	onBlur	(ev?: Event) => void	-

useFormItem

const useFormItem = (data: {
  size?: Ref<Size | undefined>;
  disabled?: Ref<boolean>;
  error?: Ref<boolean>;
}) => {
  mergedSize:Ref<Size>;
  mergedDisabled:Ref<boolean>;
  mergedError:Ref<boolean>;
  feedback:Ref<string>;
  eventHandlers:Ref<FormItemEventHandler>;
}

常用模式

• 表单布局：表单支持三种布局方式： horizontal - 水平排列 （默认）， vertical - 垂直排列， inline - 行内排列。
• 额外信息和帮助信息：可以使用 extra 添加额外信息。如果需要在外部自定义校验信息，可以使用 help 属性或插槽。设置 help 时校验信息会被屏蔽。
• 嵌套数据：展示了多种表单项嵌套的方式。表单项组件默认会将表单项状态和事件绑定到第一子组件，如果想要使用表单项进行布局设置，请设置 :merge-props="false" 以关闭绑定，或者使用函数指定需要绑定的数据。
• 栅格布局：展示了使用栅格布局的方式。可以使用 label-col-flex 属性指定标签的具体宽度。
• 自动标签宽度：设置 auto-label-width 开启自动标签宽度。仅在 layout="horizontal" 布局下生效。* 目前仅在首次加载后生效。
• 验证表单：展示了表单校验的使用方法。
• 验证表单2：展示了表单校验rules使用在a-form上的使用方法，以及可以直接校验email、ip、url
• 自定义表单校验状态：开启 feedback 可以让部分输入组件展示当前状态信息

最佳实践

• 新代码优先使用 Vue 3、Composition API 和 <script setup lang="ts">。
• 模板属性使用 kebab-case，事件使用 @event-name，插槽使用 #slot-name。
• 不要套用 React 专属 API，例如 JSX children、Component.Sub 或 Form.useForm。
• 需要进入表单校验或提交流程的控件，优先放在 a-form-item 中并绑定明确的 field。
• 输入值优先使用 v-model；范围、弹窗类状态使用组件文档中的命名 v-model:*。