Form 表单
uni-appH5微信小程序App
跨端表单容器,支持字段注册、校验、重置和清除错误。
何时使用
需要收集并校验多个字段的表单场景:登录、注册、资料编辑、下单。
何时不使用
单个输入框就地提交(如搜索)不必套 Form。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model | Record<string, unknown> | - | 表单数据对象(必填),FormItem 的 prop 对应其 key |
rules | Record<string, FormRule[]> | - | 校验规则表,key 与 FormItem 的 prop 对应;FormRule: { required?, message, trigger?: 'change'|'blur', type?: 'email'|'url'|'number', min?, max?, pattern?, validator? };type 为内置快捷校验 |
labelPosition | string:'top' | 'left' | 'inline' | "top" | 标签位置;top 对移动端友好,left 适合桌面宽屏,inline 标签与控件同行(字段横向换行,适合搜索栏/筛选栏) |
labelWidth | string | "96px" | 标签宽度,labelPosition 为 left / inline 时生效 |
disabled | boolean | false | 整体禁用表单 |
scrollToError | boolean | "false" | 校验失败后自动平滑滚动到第一个错误字段 |
validateOnRuleChange | boolean | "true" | rules 变化时自动重新校验(深度监听) |
Slots
| 名称 | 说明 |
|---|---|
default | FormItem 子项 |
Methods
| 名称 | 签名 | 说明 |
|---|---|---|
validate | () => Promise<boolean> | - |
validateField | (prop: string) => Promise<boolean> | - |
resetFields | - | - |
clearValidate | - | - |
示例
登录表单
vue
<Form :model="model" :rules="rules">
<FormItem label="账号" prop="account" required>
<Input v-model="model.account" placeholder="请输入账号" />
</FormItem>
<FormItem label="密码" prop="password" required>
<Input v-model="model.password" type="password" placeholder="请输入密码" />
</FormItem>
<Button block variant="primary" style="margin-top:6px">登 录</Button>
</Form>横向标签
vue
<Form :model="info" label-position="left" label-width="72px">
<FormItem label="姓名" prop="name">
<Input v-model="info.name" placeholder="请输入姓名" />
</FormItem>
<FormItem label="邮箱" prop="email">
<Input v-model="info.email" placeholder="请输入邮箱" />
</FormItem>
</Form>整体禁用
vue
<Form :model="model" disabled>
<FormItem label="账号" prop="account">
<Input v-model="model.account" />
</FormItem>
<FormItem label="密码" prop="password">
<Input v-model="model.password" type="password" />
</FormItem>
</Form>校验失败自动滚动
vue
<Form :model="reg" :rules="rules" scroll-to-error validate-on-rule-change>
<FormItem label="手机号" prop="phone" required>
<Input v-model="reg.phone" placeholder="校验失败时自动滚动到该表单项" />
</FormItem>
<Button block variant="primary" style="margin-top:6px">提交校验</Button>
</Form>