# 小程序 form 表单完整讲解

小程序 form 表单完整讲解

<form catchsubmit="formSubmit" catchreset="formReset">

1. 关键字说明

① catchsubmit

• 触发时机：表单内 button form-type="submit" 点击时执行
• catch：阻止事件冒泡（区别于 bindsubmit，bind 会向上冒泡）
• 绑定函数：formSubmit，表单数据会自动封装进 e.detail.value

② catchreset

• 触发时机：表单内 button form-type="reset" 点击时执行
• 作用：清空所有输入框、picker 等表单组件的值

2. 完整可运行示例（包含 input、picker、提交、重置）

WXML

<form catchsubmit="formSubmit" catchreset="formReset">
  <!-- 输入框 -->
  <view class="page-section">
    <input name="username" placeholder="请输入姓名" />
  </view>

  <!-- 下拉选择器，必须写 name 才能提交携带值 -->
  <picker name="dept" mode="selector" range="{{partListArray}}" range-key="name" value="{{index}}" bindChange="bindPickerChange">
    <view wx:if="{{index > -1}}">隶属部门：{{partListArray[index].name}}</view>
    <view wx:else>隶属部门</view>
  </picker>

  <!-- 提交按钮 -->
  <button form-type="submit">提交表单</button>
  <!-- 重置按钮 -->
  <button form-type="reset">重置</button>
</form>

3. 配套 JS

Page({
  data: {
    index: -1,
    partListArray: [
      { id: 1, name: '研发部' },
      { id: 2, name: '市场部' }
    ]
  },

  bindPickerChange(e) {
    this.setData({ index: e.detail.value })
  },

  // 表单提交回调
  formSubmit(e) {
    // 所有带 name 的表单组件自动打包在这里
    const formData = e.detail.value;
    console.log('表单全部数据：', formData);
    /*
    输出格式示例：
    {
      username: "用户输入的名字",
      dept: "选中项下标"
    }
    */

    // 直接传给后端接口
    wx.request({
      url: 'http://192.168.xxx:8000/smart/xxx/',
      method: 'POST',
      data: formData,
      success: res => {
        wx.showToast({ title: '提交成功' })
      }
    })
  },

  // 表单重置回调
  formReset() {
    console.log('表单已清空');
    // 手动重置picker下标
    this.setData({ index: -1 })
  }
})

4. 必记核心规则

1. 所有表单组件必须加 name 属性
   没有 name 的 input / picker / radio 不会被提交携带。
2. submit 按钮必须标记 form-type="submit"
3. reset 按钮必须标记 form-type="reset"
4. catchsubmit vs bindsubmit
   • catchsubmit：阻止冒泡，推荐使用
   • bindsubmit：事件会冒泡到外层父标签
5. picker 提交拿到的是选中下标数字，不是 name/id，需要自己根据下标匹配完整对象

5. 踩坑点

• reset 只能清空 input 原生值，picker 的 index 不会自动变回 -1，需要在 formReset 里手动 setData({index:-1})
• 表单组件不加 name，接口接收不到该字段
• form 不能嵌套 form，小程序不支持