uni-app 中 uni-actionSheet 插件源码解析:uni.showActionSheet 与 uni.hideActionSheet 的完整实现
uni-app 中 uni-actionSheet 插件源码解析:uni.showActionSheet 与 uni.hideActionSheet 的完整实现
uni-actionSheet 是 uni-app 仓库中一个以 UTS 语言实现的 uni_modules 插件,负责从底部向上弹出操作菜单(uni.showActionSheet)与关闭栈顶页面操作菜单(uni.hideActionSheet)。本文以插件目录下的 changelog.md 所指向的功能模块为骨架,结合其 utssdk 源码、dialogPage 页面实现、package.json 元数据与自动化测试,完整讲解该插件的参数规范、跨端架构与底层调用链,读完即可掌握在 App、Web、小程序端正确使用并二次理解 actionSheet 的运行机制。
插件概览:文件结构、定位与数据模型
uni-actionSheet 是仓库 src/uni_modules/uni-actionSheet 下的一个标准 uni_modules 插件(changelog.md 位于该目录根部,属于插件的版本变更记录),其模块内文件结构如下:
- src/uni_modules/uni-actionSheet/readme.md:插件说明,声明其核心功能是“实现弹出操作菜单(uni.showActionSheet)和关闭栈顶页面操作菜单(uni.hideActionSheet)功能”。
- src/uni_modules/uni-actionSheet/package.json:插件元数据,声明了插件的 uni-ext-api 扩展点、平台兼容范围与依赖关系。
- src/uni_modules/uni-actionSheet/utssdk/index.uts:插件跨端公共实现,所有平台共用,是
showActionSheet/hideActionSheet的入口逻辑。 - src/uni_modules/uni-actionSheet/utssdk/interface.uts:类型声明文件,定义了全部参数、回调与错误码类型。
- src/uni_modules/uni-actionSheet/pages/actionSheet/actionSheet.uvue:操作菜单的 UI 页面实现,以 dialogPage 形式呈现。
从 package.json 可以看到,该插件的 uni-ext-api 声明了 uni.showActionSheet 与 uni.hideActionSheet 两个扩展 API,且 app 平台的 js 能力为 false,仅 kotlin、swift、arkts 为 true,这意味着在 App 端该插件是编译为 Kotlin / Swift / ArkTS 的原生能力,而不是 JS 实现。同时,插件依赖了 uni-framework、uni-theme、uni-getAppBaseInfo、uni-getDeviceInfo、uni-getSystemInfo、uni-dialogPage、uni-event 等基础模块,说明它的实现深度依赖主题、设备信息与 dialogPage 弹窗体系。
参数全解析:ShowActionSheetOptions 与 Popover
从 utssdk/interface.uts 中可以看出,ShowActionSheetOptions 定义了全部可配置参数:
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | null | 否 | 菜单标题 |
| alertText | string | null | 否 | 警示文案(仅微信小程序真机有效) |
| itemList | string[] | 是 | 按钮的文字数组,必填项 |
| itemColor | string.ColorString | null | 否 | 按钮的文字颜色,字符串格式 |
| popover | Popover | null | 否 | 大屏设备弹出原生选择按钮框的指示区域,默认居中显示 |
| titleColor | string.ColorString | null | 否 | 菜单标题文字颜色 |
| cancelText | string | null | 否 | 取消按钮的文字,默认为"取消" |
| cancelColor | string.ColorString | null | 否 | 取消按钮的文字颜色 |
| backgroundColor | string.ColorString | null | 否 | 弹框背景颜色 |
| success | ShowActionSheetSuccessCallback | null | 否 | 接口调用成功的回调函数 |
| fail | ShowActionSheetFailCallback | null | 否 | 接口调用失败的回调函数 |
| complete | ShowActionSheetCompleteCallback | null | 否 | 接口调用结束的回调函数(成功、失败都会执行) |
Popover 用于在 Web 大屏上指定弹出框的指示区域(interface.uts),包含四个必填字段:top(指示区域坐标,使用原生 navigationBar 时一般需要加上 navigationBar 的高度)、left(指示区域坐标)、width(指示区域宽度)、height(指示区域高度)。不传 popover 时,菜单默认居中显示。
回调结果的类型定义同样完整:
ShowActionSheetSuccess包含errMsg: string(错误信息,成功时为showActionSheet:ok)与tapIndex: number(用户点击的按钮序号,从上到下从 0 开始),其默认实现类ShowActionSheetSuccessImpl在 interface.uts 中定义。ShowActionSheetFail继承IUniError,错误码ShowActionSheetErrorCode固定为4,代表“框架内部异常”,默认错误信息为showActionSheet:fail cancel,实现类为ShowActionSheetFailImpl(interface.uts)。
从底部弹起的跨端 API:showActionSheet 的实现原理
showActionSheet 的入口实现位于 utssdk/index.uts。它并不是直接弹出一个系统原生对话框,而是走了一条“事件总线 + dialogPage”的完整链路:
- 生成事件名:先用
Date.now()加随机数拼出唯一的baseEventName(形如uni_action_sheet_16800000000001234567),再派生出_ready、_options、_success、_fail四个事件名,用于页面与调用方之间的通信,避免多弹窗并发时的命名冲突。 - 注册监听回调:通过
uni.$on监听 ready 事件(菜单页就绪后把 options 发回去)、success 事件(用户点了第几个按钮,触发options.success与options.complete)、fail 事件(取消或关闭,触发options.fail与options.complete)。 - 打开 dialogPage:调用
uni.openDialogPage打开/uni_modules/uni-actionSheet/pages/actionSheet/actionSheet,并把四个事件名拼进 URL 参数传入菜单页。若打开失败,则构造ShowActionSheetFailImpl回调失败并清理所有监听(index.uts)。
这里 uni.$on / uni.$emit 走的是 uni-event 模块的事件总线,而 uni.openDialogPage 走的是 uni-dialogPage 模块。dialogPage 是一种背景透明的页面,可以覆盖 pages.json 中的导航栏和 tabbar,且不影响主页面栈与路由地址(详见 docs/api/dialog-page.md)。uni-app 文档也明确说明:App 和 Web 平台的 actionSheet 从 4.52 起重构为使用 dialogPage 实现,重构后的版本支持暗黑主题、国际化、横屏宽屏适配。
关闭栈顶菜单:hideActionSheet 的实现原理
hideActionSheet 的实现同样位于 utssdk/index.uts,逻辑非常简洁:
- 通过
getCurrentPages()获取页面栈,取栈顶的当前主页面。 - 通过
currentPage.$getSystemDialogPages()获取挂载在该主页面上、由系统 API 打开的 dialogPage 列表。 - 遍历列表,凡是以
uni:actionSheet(常量SYSTEM_DIALOG_ACTION_SHEET_PAGE_PATH)开头的页面,就调用uni.closeDialogPage({ dialogPage: page })将其关闭。
因此 hideActionSheet 只能作用于当前页面栈顶所挂载的 actionSheet 弹窗,这也是其 API 文档描述为“关闭栈顶页面操作菜单”的原因。
菜单 UI 实现:actionSheet.uvue 页面解剖
菜单的视觉与交互完全由 pages/actionSheet/actionSheet.uvue 承载,它以一个 dialogPage 页面实现,从 onLoad 中解析 URL 里传入的四个事件名,并监听 _options 事件接收调用方传来的配置(itemList、title、各颜色、popover 等)(actionSheet.uvue)。
页面结构包含遮罩层 uni-action-sheet_dialog__mask、菜单容器 uni-action-sheet_dialog__container、菜单列表 uni-action-sheet_dialog__menu 与取消按钮 uni-action-sheet_dialog__action。核心交互逻辑:
- 点击菜单项
handleMenuItemClick(tapIndex):标记menuItemClicked为 true,执行关闭动画(show=false,250ms 后uni.closeDialogPage),再uni.$emit(successEventName, tapIndex)把序号传回调用方(actionSheet.uvue)。 - 点击遮罩或取消按钮
handleCancel:标记cancelButtonClicked为 true,同样关闭页面,并uni.$emit(failEventName, {})触发 fail 回调(actionSheet.uvue)。 - 非用户交互导致的关闭(如页面被 navigateBack):在
onBeforeUnmount中,若两个点击标记都未置位,则主动uni.$emit(failEventName, {})触发 fail 回调,并清理全部事件监听(actionSheet.uvue)。
同时,页面还实现了暗黑主题跟随(通过 uni.onAppThemeChange、uni.onHostThemeChange 监听应用/宿主主题变化)、取消按钮文案的国际化(内置 en/es/fr/zhHans/zhHant 五种语言,默认按 uni.getLocale() 返回的语言环境选择)、横屏适配(isLandscape 时菜单宽度固定为 300px 居中、隐藏取消按钮),以及 Web 宽屏(窗口宽高 ≥500px)下的 popover 定位与三角指示箭头计算(actionSheet.uvue)。
官方 API 规范对照:兼容性与平台差异
插件对应的官方 API 规范见 docs/api/action-sheet.md,其中明确了两套 API 的平台兼容性:
showActionSheet 兼容性
| Web | 微信小程序 | 支付宝小程序 | Android | iOS | HarmonyOS |
|---|---|---|---|---|---|
| 4.0 | 4.41 | 5.31 | 3.91 | 4.11 | 4.61 |
hideActionSheet 兼容性
| Web | 微信小程序 | 支付宝小程序 | Android | iOS | HarmonyOS |
|---|---|---|---|---|---|
| 4.0 | x | x | 3.91 | 4.11 | 4.61 |
注意 hideActionSheet 在微信/支付宝小程序端不被支持。另外从 interface.uts 中的 @uniPlatform 注释可以看出多个参数存在版本差异:例如 title 在各端均可用,但 titleColor、cancelText、cancelColor、backgroundColor 在微信小程序上标记为 x(不支持),popover 仅 Web 平台有效;微信小程序还额外支持 alertText 警示文案。此外,在 App 端“大量选项测试不能超过 6 个元素”的约束来自官方 uni-app 文档约定,示例页也专门针对超过 6 个 item 的情况做了测试用例。
实战示例:完整调用与回调处理
参考仓库中的 src/pages/API/action-sheet/action-sheet.uvue,一个完整的调用示例如下:
const options: ShowActionSheetOptions = {
title: '请选择操作',
itemList: ['item1', 'item2', 'item3', 'item4'],
success: (res) => {
// tapIndex 从 0 开始
console.log('选中了第' + (res.tapIndex + 1) + '个按钮');
uni.showToast({ title: '点击了第' + res.tapIndex + '个选项', icon: 'none' });
},
fail: (error) => {
console.log(error.errMsg); // 取消时为 showActionSheet:fail cancel
},
complete: (res) => {
// 成功、失败都会执行
}
};
// 按需设置可选参数
options.titleColor = '#007AFF';
options.itemColor = '#ff00ff';
options.cancelText = 'custom cancel';
options.cancelColor = '#007AFF';
options.backgroundColor = '#ccc';
uni.showActionSheet(options);
uni.hideActionSheet() 则直接调用即可,无需参数。示例页还演示了“在回调中再次 showActionSheet”的链式调用,以及“success 回调中 navigateBack”等场景。
自动化测试:验证行为与稳定性
该插件在仓库中有配套的自动化测试 src/pages/API/action-sheet/action-sheet.test.js,覆盖了有标题、无标题、超长标题、超过 6 个 item、自定义 itemColor、自定义 titleColor/cancelText/cancelColor/backgroundColor、hideActionSheet、回调中再次 showActionSheet、以及“onLoad 调用且非交互关闭应触发 fail 回调”等场景。测试中还针对 Android 13 设备专门验证了在 actionSheet 的 success 回调中执行 navigateBack 的行为。这些测试可以用于快速验证各平台上的弹出、点击、取消、关闭与回调链路是否正常。
小结
通过对 uni-actionSheet 插件的源码分析可以看到:它的本质是一个“事件总线调度 + dialogPage 承载 UI”的跨端方案——utssdk/index.uts 负责生成一次性事件名并通过 uni.$on/uni.$emit 与菜单页通信,pages/actionSheet/actionSheet.uvue 负责渲染菜单与处理点击/取消/非交互关闭,hideActionSheet 则通过系统 dialogPage 列表精准关闭栈顶菜单。理解这条链路后,开发者不仅能正确使用 uni.showActionSheet / uni.hideActionSheet 的全部参数与回调,也能为自定义弹窗类能力(如选择器、菜单)参考其事件总线与 dialogPage 结合的架构模式。