uni-app x uni-actionSheet UTS 插件源码解析:从 uni.showActionSheet 到原生操作菜单的实现原理

原创2026-09-19 23:57:552,339 阅读
文章标签:示例工程前端移动开发

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)把调用方的参数与回调,跨页面传递到一个新建的对话框页面。完整调用链如下:

  1. 生成一个唯一事件前缀:const uuid = Date.now(){Date.now()}{Math.floor(Math.random() * 1e7)}``,再拼出 uni_action_sheet_${uuid} 系列事件名(_ready、_options、_success、_fail),保证多次调用互不干扰;
  2. 注册三个监听:
    • 监听 readyEventName:对话框页面加载完成时发出 ready 信号,主线程随即 uni.$emit(optionsEventName, ...) 把序列化后的 options 回传给页面;
    • 监听 successEventName:页面点击菜单项后,把 tapIndex 传回,构造 ShowActionSheetSuccessImpl(index) 依次触发 options.success 与 options.complete;
    • 监听 failEventName:页面取消或非交互关闭时,构造 ShowActionSheetFailImpl() 依次触发 options.fail 与 options.complete;
  3. 通过 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)则完成事件对接:

  1. 从 URL 取出四个事件名并 uni.$on(optionsEventName, ...) 接收 options 数据,逐项写入 title、itemList、titleColor、itemColor、cancelColor、backgroundColor 等响应式变量(Web 端额外接收 popover);
  2. uni.$emit(readyEventName, {}) 通知主线程"页面已就绪,可以下发参数";
  3. 页面就绪动画:onReady 中先根据 safeAreaInsets.bottom 计算底部导航占位高度,再延迟 10ms 置 show = true 触发上滑动画;
  4. 用户点击菜单项 handleMenuItemClick(tapIndex):置位标记后执行 250ms 关闭动画(closeActionSheet 调用 uni.closeDialogPage 关闭自身),再 uni.$emit(successEventName, tapIndex);
  5. 用户点击取消/遮罩 handleCancel:同样关闭后 uni.$emit(failEventName, {}) 触发 fail 回调;
  6. 非用户交互导致页面被关闭(如直接 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
      })
    }
  })
}

其原理可概括为三步:

  1. 通过 getCurrentPages() 拿到当前页面栈,取栈顶页面;
  2. 调用栈顶页面的 $getSystemDialogPages() 获取其上的系统对话框页面列表;
  3. 遍历列表,凡是 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:unixVer 3.91 起;uniVer(uni-app 传统编译)标注 √;
  • App-iOS:unixVer 4.11 起(unixUtsPlugin 4.11);uniVer 标注 √;
  • App-Harmony:uniVer 4.23 起,unixVer 4.61 起;
  • Web:unixVer 4.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)、参数回传序列化、非交互关闭兜底回调等模式都极具参考价值。

进一步阅读建议:

登录后查看全文
uni-app