uni-app 中 uni-actionSheet 插件源码解析:uni.showActionSheet 与 uni.hideActionSheet 的完整实现

原创2026-10-10 13:45:221,812 阅读
文章标签:示例工程前端移动开发

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 位于该目录根部,属于插件的版本变更记录),其模块内文件结构如下:

从 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”的完整链路:

  1. 生成事件名:先用 Date.now() 加随机数拼出唯一的 baseEventName(形如 uni_action_sheet_16800000000001234567),再派生出 _ready、_options、_success、_fail 四个事件名,用于页面与调用方之间的通信,避免多弹窗并发时的命名冲突。
  2. 注册监听回调:通过 uni.$on 监听 ready 事件(菜单页就绪后把 options 发回去)、success 事件(用户点了第几个按钮,触发 options.success 与 options.complete)、fail 事件(取消或关闭,触发 options.fail 与 options.complete)。
  3. 打开 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,逻辑非常简洁:

  1. 通过 getCurrentPages() 获取页面栈,取栈顶的当前主页面。
  2. 通过 currentPage.$getSystemDialogPages() 获取挂载在该主页面上、由系统 API 打开的 dialogPage 列表。
  3. 遍历列表,凡是以 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 结合的架构模式。

登录后查看全文
uni-app