uni-app x uni-actionSheet UTS 插件源码解析:从 uni.showActionSheet 到原生操作菜单的实现原理
uni-app x uni-actionSheet UTS 插件源码解析:从 uni.showActionSheet 到原生操作菜单的实现原理
本文基于开源仓库 uni-app 中
src/uni_modules/uni-actionSheet目录下的 UTS 插件源码展开,全面解读uni.showActionSheet(弹出操作菜单)与uni.hideActionSheet(关闭操作菜单)在 uni-app x 中的实现方式、参数体系、事件桥接机制与页面渲染细节,并顺带说明 UTS 插件在 Android、iOS、鸿蒙与 Web 等多端上的组织与编译方式。读完本文,你将能够深入理解该插件的内部工作原理,并可在自己的 uni-app x 工程中直接引用、改造或二次封装这套操作菜单能力。
一、插件定位:uni-actionSheet 做了什么
uni-actionSheet 是一个以 UTS 语言编写的 uni_modules 扩展插件,核心目标是向 uni-app / uni-app x 开发者提供与官方 API 完全一致的"从底部向上弹出操作菜单"能力。插件 readme 明确写道:它实现弹出操作菜单(uni.showActionSheet)和关闭栈顶页面操作菜单(uni.hideActionSheet)两个功能,对应的 API 规范可参考仓库内文档 docs/api/action-sheet.md。
插件目录结构如下(见 src/uni_modules/uni-actionSheet):
| 目录/文件 | 作用 |
|---|---|
utssdk/index.uts |
插件主入口,导出 showActionSheet 与 hideActionSheet 两个 API 的 UTS 实现 |
utssdk/interface.uts |
类型定义层,声明 ShowActionSheetOptions、ShowActionSheetSuccess、ShowActionSheetFail、Popover 等完整类型体系 |
pages/actionSheet/actionSheet.uvue |
操作菜单的界面渲染页面(基于 uni.openDialogPage 打开的对话框页) |
package.json |
插件元信息:声明平台支持范围、依赖的 uni_modules 组件与 uni-ext-api 映射 |
readme.md / changelog.md |
插件说明与变更记录 |
从 package.json 中可以看到该插件的关键声明:
"type": "uts":这是一个标准 UTS 插件;uni-ext-api中将showActionSheet、hideActionSheet注册为uni对象的扩展 API,且 Android(kotlin)、iOS(swift)、鸿蒙(arkts)三端原生实现均标记为true;- 依赖链为
uni-framework、uni-theme、uni-getAppBaseInfo、uni-getDeviceInfo、uni-getSystemInfo、uni-dialogPage、uni-event等基础 uni_modules(见 src/uni_modules/uni-actionSheet/package.json),这从侧面说明操作菜单依赖对话框页、全局事件、主题与设备信息等基础设施。
二、前置知识:UTS 语言与 UTS 插件
readme 用较大篇幅介绍了 UTS(uni type script),它是 uni-app x 引入的一门跨平台、高性能、强类型的现代编程语言。关键事实如下:
- 它可以被编译为不同平台的编程语言:Android 平台编译为 Kotlin、iOS 平台编译为 Swift、鸿蒙 OS 平台编译为 ArkTS、Web 平台/小程序编译为 JavaScript;
- UTS 采用与 TypeScript 基本一致的语法规范,支持绝大部分 ES6 API;
- 为跨端考虑,UTS 做了一些约束和特定平台增补;
- 与 uni-app 的条件编译类似,UTS 也支持条件编译,写在条件编译块里的代码可以调用平台特有的扩展语法(本插件源码中大量使用
#ifdef APP-HARMONY、#ifdef WEB、#ifdef APP-ANDROID || APP-IOS等,正是这一机制的直观体现)。
UTS 插件则是一种特定的 uni_modules 插件,其核心目的是允许开发者使用 UTS 语法调用扩展 API(封装原生系统 API 或三方 SDK)。插件实现代码主要位于 utssdk 目录下,并按平台分离组织,readme 给出的目录约定如下:
| 目录/文件 | 目标平台 | 实现语言 | 作用描述 |
|---|---|---|---|
utssdk/app-android |
Android | UTS, Kotlin, Java | 存放 UTS 插件在 Android 平台上的具体实现源码 |
utssdk/app-ios |
iOS | UTS, Swift | 存放 UTS 插件在 iOS 平台上的具体实现源码 |
utssdk/app-harmony |
HarmonyOS (鸿蒙) | UTS, ArkTS | 存放 UTS 插件在 HarmonyOS 平台上的具体实现源码 |
utssdk/*.uts |
多平台共用 | UTS | 存放使用 UTS 语言编写的、可供所有平台共用的实现源码 |
uni-actionSheet 插件即属于最后一种形态:核心逻辑全部放在 utssdk 根目录下的 index.uts 与 interface.uts 中,属于多平台共用的纯 UTS 实现,无需针对各平台编写原生代码,因此也没有 app-android、app-ios、app-harmony 子目录。相关语言与插件开发细节可继续阅读仓库内文档 docs/uts/README.md、docs/uts/uts_diff_ts.md(UTS 与 TS 的差异)、docs/plugin/uts-plugin.md(UTS 插件开发)、docs/plugin/uts-plugin-hybrid.md(原生语言混编)、docs/plugin/uts-for-android.md、docs/plugin/uts-for-ios.md、docs/plugin/uts-for-harmony.md(各平台开发注意事项)。
三、API 参数体系:ShowActionSheetOptions 全量解析
interface.uts(src/uni_modules/uni-actionSheet/utssdk/interface.uts)中定义了完整的参数类型。showActionSheet 的签名是:
export type ShowActionSheet = (options: ShowActionSheetOptions) => void;
ShowActionSheetOptions 的字段如下(注释中标注了各字段的平台可用性,均为源码中 @uniPlatform 元数据的真实内容):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
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 等)指定弹出框指向的区域,包含四个数值字段:
export type Popover = {
top: number, // 指示区域坐标,使用原生 navigationBar 时一般需要加上 navigationBar 的高度
left: number, // 指示区域坐标
width: number, // 指示区域宽度
height: number // 指示区域高度
}
回调结果类型方面:
ShowActionSheetSuccess包含errMsg: string(错误信息,成功时为showActionSheet:ok)与tapIndex: number(用户点击的按钮序号,从上到下从 0 开始);ShowActionSheetFail extends IUniError,其errCode: ShowActionSheetErrorCode为字面量类型4,源码注释明确"错误码 4 表示框架内部异常";- 成功/失败实现类为
ShowActionSheetSuccessImpl(默认errMsg = 'showActionSheet:ok')与ShowActionSheetFailImpl(默认errMsg = 'showActionSheet:fail cancel'、errCode = 4),即取消操作默认按失败路径回调。
四、基本用法:在 uni-app x 中弹出操作菜单
interface.uts 中 Uni 接口扩展声明携带了官方使用示例,最简用法如下:
uni.showActionSheet({
itemList: ['A', 'B', 'C'],
success: function (res) {
console.log('选中了第' + (res.tapIndex + 1) + '个按钮');
},
fail: function (res) {
console.log(res.errMsg);
}
});
仓库自带的演示页 src/pages/API/action-sheet/action-sheet.uvue 提供了更完整的实战样例,覆盖了绝大多数配置项的组合使用:
const showActionSheet = () => {
const options: ShowActionSheetOptions = {
title: data.items[data.current].value,
itemList: ['item1', 'item2', 'item3', 'item4'],
success: (res) => {
console.log(res.tapIndex);
uni.showToast({
title: "点击了第" + res.tapIndex + "个选项",
icon: "none"
})
},
fail: (error) => {
console.log(error);
}
}
// 自定义颜色/文案示例
if (data.titleColorCustom) options.titleColor = '#007AFF'
if (data.itemColorCustom) options.itemColor = '#ff00ff'
if (data.cancelTextCustom) options.cancelText = 'custom cancel'
if (data.cancelColorCustom) options.cancelColor = '#007AFF'
if (data.backgroundColorCustom) options.backgroundColor = '#ccc'
uni.showActionSheet(options)
}
演示页还展示了几个值得注意的边界场景:
- 超长文本与空文本 item:将
itemList换成古诗长句与空字符串,验证文本溢出省略与空项渲染; - 超过 6 个 item:动态生成 10 个选项,验证列表滚动(
itemList上限为 6 是微信小程序端的限制,App 端无此约束,页面层会在 Web 端限制为可滚动容器); - 在回调中再次弹出:
complete回调里再次调用uni.showActionSheet,验证对话框栈的连续弹出能力; - 在 success 回调中
navigateBack:验证页面返回与对话框关闭的时序兼容性。
hideActionSheet 的调用则非常简单:
uni.hideActionSheet();
五、底层原理(一):事件桥接 + openDialogPage 的弹出机制
showActionSheet 的实现位于 src/uni_modules/uni-actionSheet/utssdk/index.uts,核心思路是通过 uni 全局事件桥接(uni.$on / uni.$emit)把调用方的参数与回调,跨页面传递到一个新建的对话框页面。完整调用链如下:
- 生成一个唯一事件前缀:
const uuid ={Math.floor(Math.random() * 1e7)}``,再拼出uni_action_sheet_${uuid}系列事件名(_ready、_options、_success、_fail),保证多次调用互不干扰; - 注册三个监听:
- 监听
readyEventName:对话框页面加载完成时发出 ready 信号,主线程随即uni.$emit(optionsEventName, ...)把序列化后的 options 回传给页面; - 监听
successEventName:页面点击菜单项后,把tapIndex传回,构造ShowActionSheetSuccessImpl(index)依次触发options.success与options.complete; - 监听
failEventName:页面取消或非交互关闭时,构造ShowActionSheetFailImpl()依次触发options.fail与options.complete;
- 监听
- 通过
uni.openDialogPage打开对话框页面,并在 URL 查询参数中传递四个事件名:
uni.openDialogPage({
url: `/uni_modules/uni-actionSheet/pages/actionSheet/actionSheet?readyEventName=${readyEventName}&optionsEventName=${optionsEventName}&successEventName=${successEventName}&failEventName=${failEventName}`,
fail(err) {
// 打开失败时直接走 fail 回调,并清理事件监听
const res = new ShowActionSheetFailImpl(`showActionSheet failed, ${err.errMsg}`)
options.fail?.(res)
options.complete?.(res)
uni.$off(readyEventName)
uni.$off(successEventName)
uni.$off(failEventName)
}
})
这里有一个值得注意的细节:fail(err) 内部对 err.errMsg 的取值做了条件编译——APP-HARMONY 平台使用 err['errMsg'] 下标访问,其余平台使用 err.errMsg,这正是 UTS 语言"条件编译抹平平台差异"的典型写法。
对话框页 actionSheet.uvue 的 onLoad 阶段(src/uni_modules/uni-actionSheet/pages/actionSheet/actionSheet.uvue)则完成事件对接:
- 从 URL 取出四个事件名并
uni.$on(optionsEventName, ...)接收 options 数据,逐项写入title、itemList、titleColor、itemColor、cancelColor、backgroundColor等响应式变量(Web 端额外接收popover); uni.$emit(readyEventName, {})通知主线程"页面已就绪,可以下发参数";- 页面就绪动画:
onReady中先根据safeAreaInsets.bottom计算底部导航占位高度,再延迟 10ms 置show = true触发上滑动画; - 用户点击菜单项
handleMenuItemClick(tapIndex):置位标记后执行 250ms 关闭动画(closeActionSheet调用uni.closeDialogPage关闭自身),再uni.$emit(successEventName, tapIndex); - 用户点击取消/遮罩
handleCancel:同样关闭后uni.$emit(failEventName, {})触发 fail 回调; - 非用户交互导致页面被关闭(如直接
navigateBack)时,onBeforeUnmount中通过menuItemClicked/cancelButtonClicked两个标记判断:若并非用户点击,则同样补发一次 fail 事件;最后统一uni.$off清理全部监听,避免事件泄漏。
六、底层原理(二):hideActionSheet 如何关闭系统对话框页
hideActionSheet 的实现体现了 uni-app x 对"系统对话框页面"的原生管理能力:
const SYSTEM_DIALOG_ACTION_SHEET_PAGE_PATH = 'uni:actionSheet'
export const hideActionSheet = () => {
const pages = getCurrentPages()
const currentPage = pages[pages.length - 1]
if (currentPage == null) return
const systemDialogPages = currentPage.$getSystemDialogPages();
systemDialogPages.forEach((page) => {
if (page.route.startsWith(SYSTEM_DIALOG_ACTION_SHEET_PAGE_PATH)) {
uni.closeDialogPage({
dialogPage: page
})
}
})
}
其原理可概括为三步:
- 通过
getCurrentPages()拿到当前页面栈,取栈顶页面; - 调用栈顶页面的
$getSystemDialogPages()获取其上的系统对话框页面列表; - 遍历列表,凡是
route以uni:actionSheet开头的对话框页,调用uni.closeDialogPage({ dialogPage: page })将其关闭。关闭动作会触发对话框页的卸载流程,进而由onBeforeUnmount补发 fail 回调(若此前没有用户交互),从而保证 API 语义完整。
七、界面细节:暗黑模式、横屏与 Web 宽屏适配
actionSheet.uvue 的模板与样式完整覆盖了三类适配场景,直接阅读源码可获取全部细节:
- 暗黑模式(dark mode):页面通过
uni.getDeviceInfo()、uni.getAppBaseInfo()获取appTheme/osTheme/hostTheme,并监听uni.onAppThemeChange(App 端)与uni.onHostThemeChange(Web 端)实现主题实时切换。样式层为每个元素都准备了uni-action-sheet_dark__mode变体,例如菜单背景#2C2C2B、标题文字#999999、正文#ffffff; - 横屏模式(landscape):根据
deviceInfo.deviceOrientation == 'landscape'判断,横屏时容器改为 300px 宽的居中弹窗(圆角 5px、带阴影),隐藏取消按钮,并降低内容区最大高度;onResize中也会实时刷新该状态; - Web 宽屏适配:当
windowHeight >= 500 && windowWidth >= 500判定为宽屏时,弹窗同样变为居中浮层;若传入popover,还会计算left/top/bottom让弹窗定位到指示区域附近,并用 CSS 三角(uni-action-sheet_dialog__triangle)绘制指向箭头,箭头方向根据指示区位于屏幕上半/下半自动翻转。
此外,取消按钮文案自带 i18n 支持:i18nCancelText 内置了 en(Cancel)、es(Cancelar)、fr(Annuler)、zhHans(取消)、zhHant(取消)五种语言,根据 appLanguage / osLanguage / uni.getLocale() 自动选择,未匹配时兜底为"取消";用户传入 cancelText 时优先使用自定义值。
八、质量保障:自动化测试覆盖
仓库在 src/pages/API/action-sheet/action-sheet.test.js 中提供了针对该 API 的端到端自动化测试(基于 uni 自动化测试框架),覆盖场景包括:
- onLoad 阶段直接调用:验证页面加载即弹窗,以及非交互关闭(
navigateBack)时 fail 回调与生命周期计数正确(getLifeCycleNum+ 2); - 有标题 / 无标题 / 超长标题:逐项截图对比快照;
- 长内容与超过 6 个 item:验证滚动容器表现;
- 自定义颜色与文案:
titleColor、itemColor、cancelText、cancelColor、backgroundColor组合截图; - 在回调中再次 showActionSheet:验证连续弹窗;
- hideActionSheet:验证程序化关闭;
- 另有一段针对 Android 13 设备的专项测试(
showActionSheetAndNavigateBackInSuccessCallback),用于回归"在 success 回调中 navigateBack"的时序问题。
测试中大量使用 toSaveImageSnapshot() 进行视觉回归,同时对非小程序平台单独放开自定义文案类用例,体现了各端能力的差异化管理。
九、平台支持矩阵与适用前提
依据 interface.uts 中 @uniPlatform 元数据,本插件的支持情况可归纳如下(版本号均为源码注释中的标注,代表该插件对应能力引入的最低版本):
- App-Android:
unixVer3.91 起;uniVer(uni-app 传统编译)标注 √; - App-iOS:
unixVer4.11 起(unixUtsPlugin4.11);uniVer标注 √; - App-Harmony:
uniVer4.23 起,unixVer4.61 起; - Web:
unixVer4.0 起(其中title自定义在 4.51 起); - 小程序(微信等):以
hostVer(宿主平台能力)与uniVer标注为主,其中unixVer在微信端标注 4.41(部分字段); popover字段在 App 三端均标注unixVer: x,仅 Web(4.0)与小程序宿主端可用,属于大屏 Web 场景专属能力。
需要说明的是:本插件是 uni-app x(unix)体系下的 UTS 实现,在传统 uni-app(vue 项目)中 uni.showActionSheet 由框架内置实现,不一定走本插件路径;具体以 docs/api/action-sheet.md 与 docs/plugin/uts-plugin.md 的说明为准。
十、小结与延伸阅读
通过上面的拆解可以看到,uni-actionSheet 是一个"小而完整"的 UTS 插件范本:它用事件桥接 + 对话框页实现了跨端统一的交互层,用条件编译抹平了平台差异,用 @uniPlatform 元数据精确声明了各端能力边界,并配套了完善的自动化视觉回归测试。开发者若要编写自己的 UTS 插件(尤其是需要弹层交互的 API),本插件的事件命名(uuid + _ready/_options/_success/_fail)、参数回传序列化、非交互关闭兜底回调等模式都极具参考价值。
进一步阅读建议:
- 插件类型定义与 API 签名:src/uni_modules/uni-actionSheet/utssdk/interface.uts
- 插件主实现:src/uni_modules/uni-actionSheet/utssdk/index.uts
- 对话框页面渲染:src/uni_modules/uni-actionSheet/pages/actionSheet/actionSheet.uvue
- 官方 API 规范:docs/api/action-sheet.md
- UTS 语言与插件开发:docs/uts/README.md、docs/plugin/uts-plugin.md
- 演示页与测试:src/pages/API/action-sheet/action-sheet.uvue、src/pages/API/action-sheet/action-sheet.test.js