uni-app 模态弹窗 API 实战指南：showModal 与 hideModal 全平台详解

uni-app 模态弹窗 API 实战指南showModal 与 hideModal 全平台详解【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读本文围绕 uni-app 仓库中 docs/api/modal.md 文档系统讲解模态弹窗 APIuni.showModal与uni.hideModal的完整用法从参数协议、回调结果、返回值到底层实现原理并结合仓库中的 UTS 源码uni-prompt 与 uni-modal 模块、示例页面 modal.uvue 与自动化测试 modal.test.js 做源码级印证。读完本文你将能够在 Web、微信小程序、Android、iOS、HarmonyOS 上正确使用模态弹窗掌握定制按钮文案与颜色、带输入框的确认框、多弹窗管理与延迟关闭等实战能力。一、API 概览一个 API 整合 alert 与 confirmuni.showModal(options?)用于显示模态弹窗它可以只有一个确定按钮也可以同时拥有确定和取消按钮。从语义上讲它相当于把 HTML 中的alert仅确定与confirm确定 取消整合进了一个 API这是 uni-app 中 UI 交互提示体系showToast/showModal/showActionSheet/showLoading中应用最广的成员之一。对应地uni.hideModal(options?)用于隐藏已弹出的对话框实例如果modalPage参数为空则隐藏当前栈顶的全部对话框。兼容性一览| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 4.61 | 4.61 | 4.61 |hideModal的兼容性略有差异| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | x暂不支持 | 4.61 | 4.61 | 4.61 |表格中的版本号对应 uni-app x即本仓库src/uni_modules/uni-modal/utssdk/interface.uts中uniPlatform注释标注的unixVer版本。微信小程序目前只对showModal提供4.41支持hideModal在各家小程序宿主中均标记为x不支持需要在 App 与 Web 端使用。二、showModal 参数详解uni.showModal接受一个可选参数options类型为ShowModalOptions。2.1 参数属性表| 名称 | 类型 | 必备 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | title | string | 否 | - | 提示的标题 | | content | string | 否 | - | 提示的内容 | | showCancel | boolean | 否 | true | 是否显示取消按钮默认为 true | | cancelText | string | 否 | 取消 | 取消按钮的文字 | | cancelColor | string.ColorString | 否 | #000000 | 取消按钮的文字颜色 | | confirmText | string | 否 | 确定 | 确定按钮的文字 | | confirmColor | string.ColorString | 否 | - | 确定按钮的文字颜色 | | editable | boolean | 否 | false | 是否显示输入框 | | placeholderText | string | 否 | - | 显示输入框时的提示文本 | | success | (result: ShowModalSuccess) void | 否 | - | 接口调用成功的回调函数 | | fail | (result: ShowModalFail) void | 否 | - | 接口调用失败的回调函数 | | complete | (result: any) void | 否 | - | 接口调用结束的回调函数成功、失败都会执行 |2.2 底层默认值与参数校验源码印证这些默认值并非只写在文档里而是有真实的协议实现。在 uni-prompt/utssdk/protocol.uts 中ShowModalApiOptions.formatArgs定义了参数格式化与默认值填充export const PRIMARY_COLOR #007aff // 确定按钮默认主色 export const ShowModalApiOptions: ApiOptionsShowModalOptions { formatArgs: new Mapstring, Function | string | boolean([ [title, ], [content, ], [placeholderText, ], [showCancel, true], [editable, false], [cancelColor, #000000], [confirmColor, PRIMARY_COLOR], ]) }可以看到showCancel默认true、editable默认false、取消按钮颜色默认#000000、确定按钮颜色默认系统蓝#007aff。同时ShowModalProtocol对title、content、showCancel、cancelText、cancelColor、confirmText、confirmColor七个字段做了类型声明供参数校验使用。类型定义见 uni-modal/utssdk/interface.uts。需要说明protocol.uts中的默认值属于 uni-appVue体系的通用协议在 uni-app x 的 dialogPage 实现中见下文“多端实现”章节dialog 页面自身还会按主题二次调整颜色例如深色模式下确定按钮使用#7388a2、取消按钮使用#a5a5a5。2.3 success 回调结果 ShowModalSuccess| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errMsg | string | 是 | 错误信息 | | content | string | 否 | editable 为 true 时用户输入的文本 | | cancel | boolean | 是 | 为 true 时表示用户点击了取消用于 Android 系统区分点击蒙层关闭还是点击取消按钮关闭 | | confirm | boolean | 是 | 为 true 时表示用户点击了确定按钮 |在源码实现中成功回调结果由 ShowModalSuccessImpl 构造默认errMsg为showModal:okexport class ShowModalSuccessImpl implements ShowModalSuccess { constructor(cancel: boolean, confirm: boolean, content: string | null null, errMsg: string showModal:ok) { // ... } }2.4 fail 回调结果 ShowModalFail| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errCode | number | 是 | 错误码showModal 固定为 4 | | errSubject | string | 是 | 统一错误主题模块名称 | | data | any | 否 | 错误信息中包含的数据 | | cause | Error | 否 | 源错误信息可以包含多个错误 | | errMsg | string | 是 | 错误信息 |失败实现见 ShowModalFailImpl默认错误信息为showModal:fail cancelerrCode为4对应ShowModalErrorCode 4。统一错误规范可参考 docs/err-spec.md 中的UniError说明。2.5 返回值ModalPageUniPageshowModal的返回值类型为UniPage即ModalPage见 interface.uts可用于后续调用hideModal定向关闭指定的弹窗。三、基础用法示例3.1 最简单的确认框uni.showModal({ title: 提示, content: 这是一个模态弹窗, success: function (res) { if (res.confirm) { console.log(用户点击确定) } else if (res.cancel) { console.log(用户点击取消) } } })3.2 仅确定按钮等价于 alertuni.showModal({ title: 操作成功, content: 数据已保存, showCancel: false, // 隐藏取消按钮只保留确定 confirmText: 知道了, confirmColor: #07c160 })3.3 带输入框的弹窗editableuni.showModal({ title: 请输入昵称, editable: true, placeholderText: 最多 12 个字符, success: (res) { if (res.confirm) { console.log(用户输入的内容, res.content) } } })当editable: true时弹窗内会渲染一个输入框placeholderText作为占位提示用户输入内容会通过success回调的res.content返回仅确定时携带。3.4 完整参数示例类型标注为 ShowModalOptions参考示例页面 modal.uvue 中modalTap的写法我们可以构造一个覆盖全部可配置项的调用let op { title: 标题, editable: false, placeholderText: , content: 弹窗内容告知当前状态、信息和解决方法, showCancel: true, cancelText: 取消, cancelColor: #000000, confirmText: 确定, confirmColor: #007aff, success: (res) { console.log(JSON.stringify(res)) }, fail: (res) { console.log(JSON.stringify(res)) }, complete: (res) { console.log(JSON.stringify(res)) } } as ShowModalOptions data.lastModal uni.showModal(op) // 返回值可保存用于定向关闭四、hideModal多弹窗管理uni.hideModal(options?)用于隐藏已弹出的对话框。它的核心参数只有一个| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :- | :- | | modalPage | UniPage | 否 | Web: 4.0; Android: 4.61; iOS: 4.61; HarmonyOS: 4.61微信小程序: x | 期望隐藏的目标 modal为 null 时关闭当前栈顶全部 modal | | success / fail / complete | 回调 | 否 | 同上 | 与 showModal 一致的回调体系 |4.1 关闭全部弹窗uni.hideModal({ modalPage: null, // 关闭当前栈顶全部 modal success: (res) { console.log(res.errMsg) // hideModal:ok } })4.2 关闭指定弹窗定向关闭// 弹出时保存返回的 modalPage const modalPage uni.showModal({ title: 提示, content: 3 秒后自动关闭, success: () {} }) // 延迟 3 秒后只关闭这一个弹窗 setTimeout(() { uni.hideModal({ modalPage: modalPage }) }, 3000)4.3 多次弹出 延迟关闭的组合演示示例页面 modal.uvue 提供了三个典型场景closeAllModal立即关闭全部、setTimeoutCloseAllModal延迟 3 秒关闭全部、setTimeoutCloseLastModal延迟 3 秒只关闭最后一个弹窗。多个弹窗同时存在时showModal会按调用顺序压入弹窗栈hideModal的modalPage参数即可精确控制要关闭哪一层。注意示例中这几个按钮使用了#ifndef MP条件编译即小程序端不渲染与hideModal在小程序端不支持的事实一致。4.4 hideModal 的底层实现源码印证从 uni-modal/utssdk/index.uts 可以看出 hideModal 的实现思路通过getCurrentPages()拿到当前页面栈的最后一页调用currentPage.$getSystemDialogPages()获取系统对话框页面栈从栈顶向下遍历过滤出路由以uni:uniModal开头的 modal 页面SYSTEM_DIALOG_MODAL_PAGE_PATH若modalPage为空则逐个调用uni.closeDialogPage关闭全部否则只关闭与传入modalPage相等的目标页面iOS Vapor 场景下通过__nativePageId判断是否为同一页面代码注释中说明了 dom1/dom2 架构下 UniPage 对象引用差异最后构造HideModalSuccessImpl默认errMsg: hideModal:ok触发 success 与 complete 回调。五、多端实现原理从原生 Dialog 到 dialogPage 重构5.1 一个重要的版本事实原文档特别强调App 和 Web 平台showModal 从 4.61 起重构为使用 dialogPage 实现。重构后的版本支持暗黑主题、国际化、横屏宽屏适配。这意味着仓库中并存着两套实现5.2 旧实现Android 原生 Dialoguni-app 体系uni-prompt/utssdk/app-android/showModal.uts 是基于android.app.Dialog的原生实现通过UTSAndroid.getAppDarkMode()判断深浅色选择uni_app_uni_prompt_modal_dialog或_night布局对应 res/layout 下的两个布局文件showCancel为 true 时显示取消按钮与分割线确定按钮使用“右侧圆角”背景为 false 时隐藏取消按钮确定按钮使用“通栏圆角”背景对应 res/drawable 中大量_select_left/_select_right/_select_total及_night变体资源editable: true时显示EditText并把content预填入输入框、placeholderText作为 hint同时让输入框获得焦点editable: false时如果 title 为空还会把 content 以标题颜色渲染源码注释“如果此时 title 为空需要修改文本颜色”取消与确定按钮颜色通过Color.parseColor解析传入非法颜色会被 try/catch 吞掉即非法颜色不影响弹窗正常弹出——这正是示例页“测试非法的颜色”一项所验证的行为dismiss 与点击按钮时都会构造ShowModalSuccess并保证complete只调用一次执行后手动置空hostStyle.complete弹窗与顶层 Activity 生命周期绑定UTSAndroid.onAppActivityDestroy时自动 dismiss避免 Activity 销毁后弹窗泄漏。这套资源体系同时服务于showModal/showToast/showActionSheet/showLoading见 uni-prompt/utssdk/app-android/index.utsiOS 侧对应 app-ios/UniAlert 下的一组DCAlert*Swift 组件HarmonyOS 侧对应 app-harmony/modal.uts。5.3 新实现dialogPageuni-app x4.61在 uni-app x 中showModal由 uni-modal 模块实现核心思路是把弹窗当作一个系统对话框页面来打开showModal首先生成一组基于时间戳与随机数的唯一事件名uni_modal_${uuid}系列见 index.uts调用uni.openDialogPage打开 uniModal.uvue并把四个事件名通过 URL query 传入对话框页面onLoad后通过uni.$on/uni.$emit事件桥接ready事件通知宿主已就绪宿主收到后通过options事件把配置项title/content/showCancel/editable/各按钮文案与颜色等注入页面页面据此渲染用户点击确定/取消/返回键时页面通过success事件把{cancel, confirm, content}结果回传给宿主宿主再包装成ShowModalSuccessImpl依次触发 success → completeopenDialogPage失败或页面未成功打开时触发 fail → complete并清理事件监听。这种“页面即弹窗”的架构带来了几个直接收益均可从 uniModal.uvue 源码中看到暗黑主题页面监听uni.onThemeChangeWeb与uni.onAppThemeChangeApp通过isDark类切换蒙层、面板、文字、分割线配色见 L55-L204、L259-L288、L406-L408国际化根据appLanguage/osLanguageApp或uni.getLocale()Web自动切换取消/确定按钮文案内置 en/es/fr/zh-Hans/zh-Hant 五套见 L57-L144长内容与输入框体验内容过长时使用scroll-view滚动maxScrollHeight取屏幕高度的 55%输入框在键盘弹出时通过keyboardheightchange把弹窗整体上移键盘高度的一半避免被遮挡见 L146-L159、L246-L249横屏宽屏适配Web 端在min-width: 768px时把弹窗最大宽度限制为 556px见 L393-L399颜色合法性校验页面内用isValidColor匹配#RGB/#RRGGBB校验传入颜色非法颜色回退为主题默认色见 L161-L204——这也解释了文档示例中“非法颜色”测试项的预期行为。六、Web 平台使用提示Tips原文档给出了一条 Web 平台的关键提示在 Web 平台如果希望通过const modalPage uni.showModal(...)获取modalPage对象需要至少传入一个回调函数如 success否则拿到的返回值可能不是有效的 modalPage。uni.showModal({ success: function (showRet: ShowModalSuccess) { // 至少传入一个回调Web 平台才能正确返回 modalPage } })这是因为 Web 端通过事件桥接异步建立 modal 页面引用只有注册了回调才能确认页面实例已就绪并拿到有效的ModalPage进而支持后续的hideModal({ modalPage })定向关闭。七、完整实战示例hello uni-app x 示例页仓库内置的示例页面位于 src/pages/API/modal/modal.uvue它集中演示了文档提到的几乎所有能力标题三态切换有标题 / 无标题 / 超长标题data.items中预置了超长标题字符串开关控制空内容、超长内容、显示/隐藏取消按钮、定制取消与确认文案、非法颜色、超长按钮文本、是否显示输入框、定制输入提示词单次弹出modalTap与多次弹出modalTapTimes200ms 内连续弹出 3 个立即关闭全部、延迟 3s 关闭全部、延迟 3s 关闭最后一个closeAllModal/setTimeoutCloseAllModal/setTimeoutCloseLastModal均通过uni.hideModal实现所有 success / fail / complete 回调结果实时渲染在页面上data.exeRet、data.timesShowRet便于直观验证回调触发顺序onLoad时默认弹出一个“请手动取消”的示例弹窗支付宝小程序端因平台限制改为 content 传参。配套的自动化测试 src/pages/API/modal/modal.test.js 覆盖了 Web/App/Harmony 平台小程序端无法截图弹窗故跳过部分旧 iOS 版本已知测试异常也做了跳过处理通过program.reLaunch打开示例页后断言弹窗的展示与交互结果是验证本文所述参数行为的最直接途径。八、总结与建议| 关注点 | 结论 | | :- | :- | | 弹窗按钮布局 |showCancel: false时只保留确定按钮通栏样式默认为“取消 确定”双按钮 | | 带输入 |editable: true显示输入框placeholderText为占位输入内容经success.content返回 | | 颜色合法性 | 非法颜色不会导致崩溃两端实现原生 Dialog 的 try/catch、dialogPage 的正则校验都会回退或忽略 | | 多弹窗管理 |showModal返回值ModalPage可保存配合hideModal({ modalPage })定向关闭modalPage: null关闭全部 | | 平台差异 |hideModal微信小程序暂不支持Web 上要拿到 modalPage 返回值必须至少传一个回调 | | 架构演进 | 4.61 起 App/Web 重构为 dialogPage 实现原生获得暗黑主题、国际化与横屏宽屏适配能力 |推荐继续阅读仓库中的相关文件以获得一手信息API 文档docs/api/modal.md、docs/api/unipage.md、docs/err-spec.md接口与类型定义src/uni_modules/uni-modal/utssdk/interface.uts、src/uni_modules/uni-modal/utssdk/index.uts参数协议uni-app 体系src/uni_modules/uni-prompt/utssdk/protocol.utsdialogPage 页面实现src/uni_modules/uni-modal/pages/uniModal/uniModal.uvue原生 Dialog 实现Androidsrc/uni_modules/uni-prompt/utssdk/app-android/showModal.uts示例页面与测试src/pages/API/modal/modal.uvue、src/pages/API/modal/modal.test.js【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考