uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
uni-app x
uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
简体中文
组件
form
form 兼容性
属性
事件
UniFormSubmitEvent
UniFormResetEvent
form 属性兼容性
submit策略差异
reset策略差异
示例
展示全部

# form

组件类型：UniFormElement

表单

# form 兼容性

Android iOS web
3.97 4.11 4.0

# 属性

名称 类型 默认值 描述
disabled boolean - 是否禁用
report-submit boolean - 是否返回 formId 用于发送模板消息
@submit (event: UniFormSubmitEvent) => void - 携带 form 中的数据触发 submit 事件，event.detail = {value : {'name': 'value'}}
@reset (event: UniFormResetEvent) => void - 表单重置时会触发 reset 事件

# 事件

# UniFormSubmitEvent

# UniFormSubmitEvent 的属性值
名称 类型 必填 默认值 描述
detail UniFormSubmitEventDetail 是 - -
名称 类型 必备 默认值 描述
value UTSJSONObject 是 - -
bubbles boolean 是 - 是否冒泡
cancelable boolean 是 - 是否可以取消
type string 是 - 事件类型
target UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number 是 - 事件发生时的时间戳
# UniFormSubmitEvent 的方法
名称 类型 必填 默认值 描述
stopPropagation () => void 是 - 阻止当前事件的进一步传播
preventDefault () => void 是 - 阻止当前事件的默认行为

# UniFormResetEvent

# UniFormResetEvent 的属性值
名称 类型 必填 默认值 描述
detail UniFormResetEventDetail 是 - -
bubbles boolean 是 - 是否冒泡
cancelable boolean 是 - 是否可以取消
type string 是 - 事件类型
target UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null 否 - UVUE DOM 元素对象，描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number 是 - 事件发生时的时间戳
# UniFormResetEvent 的方法
名称 类型 必填 默认值 描述
stopPropagation () => void 是 - 阻止当前事件的进一步传播
preventDefault () => void 是 - 阻止当前事件的默认行为

# form 属性兼容性

Android iOS web
disabled 3.97 4.11 4.0
report-submit x x 4.0
@submit 3.97 4.11 4.0
@reset 3.97 4.11 4.0

# submit策略差异

form 组件的表单提交，微信小程序的实现策略，与浏览器W3C的策略略有差异。目前uni-app在app和web上的实现参考了微信小程序。具体是：

  • uni-app表单提交的数据是一个对象{"name": "value"}。而浏览器标准form是数组，每项为 pair，pair[0] 对应name，pair[1] 对应value 。
  • 多个表单子项如果 name 相同，仅保留最后一个表单子项。而浏览器标准form整体是数组，不存在覆盖的情况。
  • 设置 disabled 属性的表单子项，仍然会提交。而浏览器标准form提交时会忽略disabled的表单子项。

注意uni-app编译到web平台，也是按uni-app的策略，而不是浏览器的策略。uni-app 的 web平台使用 uni-app 自己的 form 组件，而不是浏览器的 form 标签。

# reset策略差异

reset在浏览器W3C的策略是还原、重置。

在uni-app中，不同平台的策略不同，有的是还原，有的是清空。

各平台策略如下：

uni-app-x

App Web
还原(3.97+) 还原(4.0+)

uni-app

App Web 微信小程序 支付宝小程序 百度小程序 抖音小程序
清空 清空 清空 还原 清空 清空
  1. 还原初始值
<!-- reset 后为 name -->
<input name="input1" value="name" />

<!-- reset 后为 true -->
<switch name="switch1" :checked="true" />

<!-- reset 后为 50 -->
<slider name="slider1" :value="50" :min="10" :max="110" />

<!-- reset 后为 "写字" 被 checked -->
<checkbox-group name="loves">
  <view>
    <checkbox value="0" /><text>读书</text>
  </view>
  <view>
    <checkbox value="1" :checked="true" /><text>写字</text>
  </view>
</checkbox-group>
  1. 清空已有值(含初始值和改变后的值)
<!-- reset 后为 "" -->
<input name="input1" value="name" />

<!-- reset 后为 false -->
<switch name="switch1" :checked="true" />

<!-- reset 后为 最小值10 -->
<slider name="slider1" :value="50" :min="10" :max="110" />

<!-- reset 后为 无任何 checked -->
<checkbox-group name="loves">
  <view>
    <checkbox value="0" /><text>读书</text>
  </view>
  <view>
    <checkbox value="1" :checked="true" /><text>写字</text>
  </view>
</checkbox-group>

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view class="scroll-view">
  <!-- #endif -->
    <view class="page">
      <form @submit="onFormSubmit" @reset="onFormReset">
        <view class="uni-form-item">
          <view class="title">姓名</view>
          <input class="uni-input" name="nickname" :value="nickname" placeholder="请输入姓名" maxlength="-1"/>
        </view>
        <view class="uni-form-item">
          <view class="title">性别</view>
          <radio-group name="gender" class="flex-row">
            <view class="group-item">
              <radio value="0" :checked="gender=='0'" /><text>男</text>
            </view>
            <view class="group-item">
              <radio value="1" :checked="gender=='1'" /><text>女</text>
            </view>
          </radio-group>
        </view>
        <view class="uni-form-item">
          <view class="title">爱好</view>
          <checkbox-group name="loves" class="flex-row">
            <view class="group-item">
              <checkbox value="0" :checked="loves.indexOf('0')>-1" /><text>读书</text>
            </view>
            <view class="group-item">
              <checkbox value="1" :checked="loves.indexOf('1')>-1" /><text>写字</text>
            </view>
          </checkbox-group>
        </view>
        <view class="uni-form-item">
          <view class="title">年龄</view>
          <slider name="age" :value="age" :show-value="true"></slider>
        </view>
        <view class="uni-form-item">
          <view class="title">保留选项</view>
          <view>
            <switch name="switch" :checked="switch" />
          </view>
        </view>
        <view class="uni-btn-v flex-row">
          <button class="btn btn-submit" form-type="submit" type="primary">Submit</button>
          <button class="btn btn-reset" type="default" form-type="reset">Reset</button>
        </view>
      </form>
      <view class="result">提交的表单数据</view>
      <textarea class="textarea" :value="formDataText" :maxlength="-1" :auto-height="true"></textarea>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>



<style>
  .scroll-view {
    flex: 1;
  }

  .page {
    padding: 15px;
  }

  .flex-row {
    flex-direction: row;
  }

  .uni-form-item {
    padding: 15px 0;
  }

  .title {
    margin-bottom: 10px;
  }

  .group-item {
    flex-direction: row;
    margin-right: 20px;
  }

  .btn {
    flex: 1;
  }

  .btn-submit {
    margin-right: 5px;
  }

  .btn-reset {
    margin-left: 5px;
  }

  .result {
    margin-top: 30px;
  }

  .textarea {
    margin-top: 5px;
    padding: 5px;
    background-color: #fff;
  }
</style>

# 参见

# Bug & Tips

  • App平台仅支持 uni 内置表单组件，暂不支持开发者组件内的表单组件
本页导读
form
form 兼容性
属性
事件
UniFormSubmitEvent
UniFormResetEvent
form 属性兼容性
submit策略差异
reset策略差异
示例
参见
Bug & Tips