::: sourceCode
## form
> issues: https://issues.dcloud.net.cn/?mid=component.form-component.form
> 源码: https://github.com/dcloudio/uni-app/tree/uni-app-x-alpha/src/uni_modules/uni-form/components/form
:::
> 组件类型:UniFormElement
表单
### 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.97; iOS: 4.11; HarmonyOS: 4.61
### 属性
| 名称 | 类型 | 默认值 | 兼容性 | 描述 |
| :- | :- | :- | :-: | :- |
| disabled | boolean | false | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: 3.97; iOS: 4.11; HarmonyOS: 4.61 | 是否禁用 |
| report-submit | boolean | | Web: x; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: x; iOS: x; HarmonyOS: x | 是否返回 formId 用于发送模板消息 |
| report-submit-timeout | number | | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | *(number)*
等待一段时间(毫秒数)以确认 formId 是否生效。如果未指定这个参数,formId 有很小的概率是无效的(如遇到网络失败的情况)。指定这个参数将可以检测 formId 是否有效,以这个参数的时间作为这项检测的超时时间。如果失败,将返回 requestFormId:fail 开头的 formId |
| @submit | (event: [UniFormSubmitEvent](#uniformsubmitevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.97; iOS: 4.11; HarmonyOS: 4.61 | 携带 form 中的数据触发 submit 事件,event.detail = {value : {'name': 'value'}} |
| @reset | (event: [UniFormResetEvent](#uniformresetevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.97; iOS: 4.11; HarmonyOS: 4.61 | 表单重置时会触发 reset 事件 |
### 事件
#### UniFormSubmitEvent
```mermaid
graph LR
UniFormSubmitEvent -- Extends --> UniCustomEvent<UniFormSubmitEventDetail>
style UniCustomEvent<UniFormSubmitEventDetail> color:#42b983
click UniCustomEvent<UniFormSubmitEventDetail> "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unicustomevent"
```
##### UniFormSubmitEventDetail
###### UniFormSubmitEventDetail 的属性值
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| value | [UTSJSONObject](/uts/buildin-object-api/utsjsonobject.md) | 是 |
#### UniFormResetEvent
```mermaid
graph LR
UniFormResetEvent -- Extends --> UniCustomEvent<UniFormResetEventDetail>
style UniCustomEvent<UniFormResetEventDetail> color:#42b983
click UniCustomEvent<UniFormResetEventDetail> "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unicustomevent"
```
## form内容项控制逻辑
form组件的内容子组件包括:input、textarea、checkbox、radio、switch、slider,以及负责提交或重置的button组件。
button可以设置form-type属性为submit或reset,点击时会分别触发form的提交或重置。
在表单submit或reset时,这些表单内容子组件的值会被提交或重置。
注意:目前不支持上述组件之外自行添加表单内容子组件。如有自定义组件,则不能使用form组件提交,需自行通过绑定data的方式获取组件值并自行编码提交数据。
### submit策略差异
form 组件的表单提交,微信小程序的实现策略,与浏览器W3C的策略略有差异。目前uni-app(x)在submit时,app和web上的实现与微信小程序相同。具体是:
- uni-app表单提交的数据是一个对象`{"name": "value"}`。而浏览器标准form是数组,每项为 pair,pair[0] 对应name,pair[1] 对应value 。
- 多个表单子项如果 name 相同,仅保留最后一个表单子项。而浏览器标准form整体是数组,不存在覆盖的情况。
- 设置 disabled 属性的表单子项,仍然会提交。而浏览器标准form提交时会忽略disabled的表单子项。
注意uni-app(x)编译到web平台,也是按uni-app(x)的策略,而不是浏览器的策略。uni-app(x) 的 web平台使用 uni-app 自己的 form 组件,而不是浏览器的 form 标签。
### reset策略差异
reset在浏览器W3C的策略是还原、重置。
在uni-app(x)中,不同平台的策略不同,有的是`还原`,有的是`清空`。
各平台策略如下:
**uni-app-x**
|App |Web |
|:-: |:-: |
|还原(3.97+) |还原(4.0+) |
**uni-app**
|App |Web |微信小程序 |支付宝小程序 |百度小程序 |抖音小程序 |
|:-: |:-: |:-: |:-: |:-: |:-: |
|清空 |清空 |清空 |还原 |清空 |清空 |
1. 还原初始值
```html
读书
写字
```
2. 清空已有值(含初始值和改变后的值)
```html
读书
写字
```
### 示例
示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/component/form/form.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/component/form/form.uvue)
::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/component/form/form
> appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/component/form/form
>示例
```vue
提交的表单数据
```
:::
### 参见
- [参见uni-app相关文档](https://uniapp.dcloud.io/component/form.html)