wx.showModal详解

wx.showModal 是微信小程序中用于显示模态对话框的核心 API，常用于需要用户确认或输入信息的场景。以下是其详细使用方法和注意事项：

一、基础用法

通过调用 wx.showModal 并传入配置对象来显示对话框：

javascript

wx.showModal({
  title: '提示', // 对话框标题（必填）
  content: '这是一个模态对话框', // 对话框内容（必填）
  success(res) {
    if (res.confirm) {
      console.log('用户点击确定');
    } else if (res.cancel) {
      console.log('用户点击取消');
    }
  }
});

二、关键参数详解

1. 按钮配置

   • showCancel: 是否显示取消按钮，默认 true。若设为 false，则仅显示 “确定” 按钮2。
   • cancelText: 取消按钮文字，默认 '取消'，最多 4 个字符24。
   • cancelColor: 取消按钮文字颜色，使用 16 进制格式（如 '#ff0000'）2。
   • confirmText: 确定按钮文字，默认 '确定'，最多 4 个字符24。
   • confirmColor: 确定按钮文字颜色，默认 '#576B95'，支持 16 进制格式2。

2. 输入框支持

   • editable: 是否显示输入框，默认 false。设为 true 时，用户可在对话框中输入内容12。
   • placeholderText: 输入框提示文本，仅在 editable: true 时生效1。
   • 注意：若同时设置 content 和 editable: true，content 会被忽略，用户输入内容通过 res.value 获取4。

3. 回调处理

   • success: 接口调用成功的回调函数，返回对象 res 包含：
     • res.confirm: 布尔值，用户是否点击确定按钮。
     • res.cancel: 布尔值（仅 Android 6.7.2 及以上版本和 iOS 有效），表示用户是否点击取消按钮或蒙层（蒙层在 iOS 和高版本 Android 中不会触发关闭）210。
     • res.value: 若包含输入框，为用户输入的内容14。
   • fail: 接口调用失败的回调函数，例如用户手机系统不支持。
   • complete: 接口调用结束的回调函数（无论成功或失败）2。

三、高级配置示例

1. 自定义按钮文本和颜色

   javascript

   wx.showModal({
     title: '确认操作',
     content: '确定要删除这条记录吗？',
     cancelText: '再想想',
     cancelColor: '#999',
     confirmText: '确定删除',
     confirmColor: '#FF4D4F',
     success(res) {
       if (res.confirm) {
         // 执行删除逻辑
       }
     }
   });
   

2. 带输入框的对话框

   javascript

   wx.showModal({
     title: '请输入验证码',
     content: '验证码将发送至你的手机',
     editable: true,
     placeholderText: '请输入6位验证码',
     success(res) {
       if (res.confirm) {
         console.log('用户输入：', res.value);
       }
     }
   });
   

四、兼容性与注意事项

1. 蒙层关闭行为

   • Android 6.7.2 以下版本：点击蒙层会触发 fail 回调，errMsg 为 'fail cancel'。
   • Android 6.7.2 及以上版本和 iOS：点击蒙层不会关闭对话框，仅响应按钮点击210。

2. 版本兼容性

   • 使用 wx.canIUse 判断 API 支持情况：

     javascript

     if (!wx.canIUse('showModal.cancel')) {
       wx.showToast({ title: '当前微信版本过低，不支持此功能' });
     }
     

3. 用户体验优化

   • 避免频繁弹出对话框，仅在关键操作（如删除、支付）时使用。
   • 输入框场景需添加输入验证，例如手机号格式检查34。
   • 按钮文字应简洁明确，如 “删除”“保存” 等，避免歧义3。

五、常见场景代码

1. 删除确认

   javascript

   wx.showModal({
     title: '警告',
     content: '删除后不可恢复，确认操作？',
     success(res) {
       if (res.confirm) {
         // 执行删除
       }
     }
   });
   

2. 必填项提示

   javascript

   wx.showModal({
     title: '提示',
     content: '请先填写姓名和手机号',
     showCancel: false, // 隐藏取消按钮
     confirmText: '去填写',
     success() {
       // 跳转至填写页面
     }
   });
   

通过合理配置参数和回调逻辑，wx.showModal 能有效提升小程序的交互体验，确保用户操作的准确性和安全性。实际开发中需结合业务场景灵活运用，并注意兼容性处理。