表单组件

form 组件是 Uniapp 中用于将用户输入的 <switch>、<input>、<checkbox>、<slider>、<radio>、<picker> 等表单控件的值进行统一提交的容器组件。点击表单中的 submit 按钮时，表单控件的 value 值会统一提交。每个表单控件需要设置 name 属性，以作为提交时的键名。

1. 什么是 form 组件？

form 组件是用于收集和提交用户输入的控件集合。通过 form 组件，开发者可以在点击提交按钮时统一获取表单内所有控件的值。表单支持多种常见的输入控件，如开关、输入框、复选框、单选框、滑块、选择器等。通过提交事件，可以将这些控件的值以对象的形式提交，便于数据收集和处理。

使用场景

• 表单提交：用户在表单中输入数据，并通过提交按钮将数据提交到服务器或进行下一步处理。
• 多控件数据管理：将多个输入控件的值收集并统一处理，适用于注册、登录、搜索、配置等场景。
• 表单重置：在需要时提供重置按钮，清空用户的输入。

2. form 组件的常用属性

form 组件提供了一些属性和事件，用于处理表单的提交与重置等操作。以下是常用属性的详细说明：

属性名	类型	说明	平台差异说明
report-submit	Boolean	是否返回 formId，用于发送模板消息（微信、支付宝等平台支持）。	微信小程序、支付宝小程序
report-submit-timeout	Number	等待指定时间（毫秒）以确认 formId 是否生效，用于确保网络失败时仍能获取 formId。	微信小程序 2.6.2+
@submit	EventHandle	表单提交时触发，事件参数 detail 返回表单数据 {value: {name: value}, formId: ''}。
@reset	EventHandle	表单重置时触发，清空所有表单控件的值。

2.1 提交事件 @submit

• 说明：当点击 form 中 submit 按钮时，表单内所有控件的值会通过 @submit 事件提交，事件参数 detail 返回表单控件的值和 formId（如果启用 report-submit）。
• 类型：EventHandle

<template>
  <view>
    <form @submit="onFormSubmit">
      <!-- 表单控件 -->
      <input name="username" placeholder="输入用户名" />
      <input name="password" type="password" placeholder="输入密码" />
      <button form-type="submit">提交</button>
    </form>
  </view>
</template>

<script setup>
const onFormSubmit = (e) => {
  // 获取表单的提交数据
  console.log('表单提交数据:', e.detail.value);
};
</script>

2.2 重置事件 @reset

• 说明：当点击 form 中 reset 按钮时，表单内所有控件的值会被清空，触发 @reset 事件。
• 类型：EventHandle

<template>
  <view>
    <form @reset="onFormReset">
      <!-- 表单控件 -->
      <input name="username" placeholder="输入用户名" />
      <button form-type="reset">重置</button>
    </form>
  </view>
</template>

<script setup>
const onFormReset = () => {
  console.log('表单已重置');
};
</script>

3. 表单控件组合使用案例

form 组件内可以包含多种表单控件，如 switch、radio、checkbox、slider、input 等。通过设置每个控件的 name 属性，可以在表单提交时获取控件的值。

<template>
  <view>
    <form @submit="onFormSubmit" @reset="onFormReset">
      <!-- Switch 开关 -->
      <view class="form-item">
        <text>开关</text>
        <switch name="switch" />
      </view>

      <!-- Radio 单选框 -->
      <view class="form-item">
        <text>单选框</text>
        <radio-group name="radio">
          <label>
            <radio value="option1" /> 选项一
          </label>
          <label>
            <radio value="option2" /> 选项二
          </label>
        </radio-group>
      </view>

      <!-- Checkbox 复选框 -->
      <view class="form-item">
        <text>复选框</text>
        <checkbox-group name="checkbox">
          <label>
            <checkbox value="option1" /> 选项一
          </label>
          <label>
            <checkbox value="option2" /> 选项二
          </label>
        </checkbox-group>
      </view>

      <!-- Slider 滑块 -->
      <view class="form-item">
        <text>滑块</text>
        <slider name="slider" value="50" show-value />
      </view>

      <!-- Input 输入框 -->
      <view class="form-item">
        <text>输入框</text>
        <input name="input" placeholder="请输入内容" />
      </view>

      <!-- 提交和重置按钮 -->
      <view class="form-buttons">
        <button form-type="submit">提交</button>
        <button form-type="reset">重置</button>
      </view>
    </form>
  </view>
</template>

<script setup>
const onFormSubmit = (e) => {
  console.log('表单提交数据:', e.detail.value);
};

const onFormReset = () => {
  console.log('表单已重置');
};
</script>

<style scoped>
.form-item {
  margin: 10px 0;
}
.form-buttons {
  display: flex;
  justify-content: space-around;
  margin-top: 20px;
}
</style>

---

4. 内置 behaviors 处理自定义组件

在表单中，默认支持的表单控件如 input、switch 等可以直接获取值。但在一些自定义组件中，无法自动获取表单值。此时可以使用 behaviors 来实现类似表单控件的行为。

• 内置 uni://form-field 行为：通过将该行为添加到自定义组件中，表单可以自动识别该组件并在 submit 事件中获取其值。

<template>
  <view>
    <form @submit="onFormSubmit">
      <!-- 自定义表单组件 -->
      <comp-input name="customInput" v-model="customInputValue" />
      <button form-type="submit">提交</button>
    </form>
  </view>
</template>

<script setup>
import { ref } from 'vue';

// 自定义表单组件的值
const customInputValue = ref('初始值');

const onFormSubmit = (e) => {
  console.log('表单提交数据:', e.detail.value);
};
</script>

• 自定义组件 compInput 实现：

<template>
  <view>
    <!-- 自定义输入框 -->
    <input :value="modelValue" @input="onInput" />
  </view>
</template>

<script>
export default {
  name: 'compInput',
  behaviors: ['uni://form-field'],
  props: {
    modelValue: String,
  },
  methods: {
    onInput(e) {
      this.$emit('update:modelValue', e.detail.value);
    },
  },
};
</script>