跳到主要内容

Form 表单 ​

uni-appH5微信小程序App

跨端表单容器,支持字段注册、校验、重置和清除错误。

何时使用 ​

需要收集并校验多个字段的表单场景:登录、注册、资料编辑、下单。

何时不使用 ​

单个输入框就地提交(如搜索)不必套 Form。

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
Form 表单 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelRecord<string, unknown>-表单数据对象(必填),FormItem 的 prop 对应其 key
rulesRecord<string, FormRule[]>-校验规则表,key 与 FormItem 的 prop 对应;FormRule: { required?, message, trigger?: 'change'|'blur', type?: 'email'|'url'|'number', min?, max?, pattern?, validator? };type 为内置快捷校验
labelPositionstring:'top' | 'left' | 'inline'"top"标签位置;top 对移动端友好,left 适合桌面宽屏,inline 标签与控件同行(字段横向换行,适合搜索栏/筛选栏)
labelWidthstring"96px"标签宽度,labelPosition 为 left / inline 时生效
disabledbooleanfalse整体禁用表单
scrollToErrorboolean"false"校验失败后自动平滑滚动到第一个错误字段
validateOnRuleChangeboolean"true"rules 变化时自动重新校验(深度监听)

Slots ​

名称说明
defaultFormItem 子项

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>