示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载导读本文以开源仓库 uni-app 中src/uni_modules/uni-dialogPage这一 UTS 插件为核心系统讲解 uni-app x 中 dialogPage模态弹窗页面的诞生背景、核心机制、openDialogPage/closeDialogPage两个 API 的完整参数语义、动画类型体系以及该插件在 Android / iOS / Web / 小程序多端下的实现原理与示例用法。读完本文你将掌握如何用 dialogPage 制作可覆盖导航栏与 tabbar、可拦截系统返回键、可多实例层叠的原生级弹窗页面并理解其底层 UTS 插件如何按平台拆分实现。一、什么是 uni-dialogPageuni-dialogPage是 uni-app x 生态中的一个 UTS 插件uni_modules 插件其核心使命是实现弹窗页面模态框功能。在开源仓库中它位于 src/uni_modules/uni-dialogPage目录内包含完整的类型定义、错误封装与双端实现源码。在了解插件本身之前需要先理解它背后的平台能力dialogPage。根据仓库中的官方 API 文档 docs/api/dialog-page.mddialogPage 是 HBuilderX 4.31 新增的一种特殊页面专用于制作弹框和内置界面其诞生源于一系列真实痛点uni.showModal、actionsheet等内置弹框自定义性不足通过前端组件实现的弹框无法覆盖 pages.json 中配置的导航栏和 tabbar前端实现的弹框无法拦截 back 按键用户一按返回键整个页面就被关闭组件方式实现弹框需要每个页面都引入组件写法繁琐chooseLocation、previewImage等部分内置 API 涉及界面但缺少统一管理。dialogPage 的解决方案是它是一类背景透明、铺满应用的页面可以覆盖 pages.json 中的导航栏与 tabbar原本的页面被称为主 pageparentPage而 dialogPage 必须挂载在某个主 page 之上。1.1 dialogPage 与主 page 的异同dialogPage 是一种特殊的 page它和主 page 有很多相同之处需要注册dialogPage 同样需在 pages.json 中注册有生命周期dialogPage 拥有页面生命周期onLoad里可以拿到各种参数组件归属dialogPage 内引用的组件其 page 就是 dialogPage。组合式组件中监听onPageShow监听的是 dialogPage 本身而不是 dialogPage 的 parentPage通信能力可以通过uni.$on等 eventBus 方案进行页面级通信。同时dialogPage 与主 page 有本质区别dialogPage背景固定为透明、大小铺满应用蒙层由页面内部实现——蒙层颜色、是否响应点击均由页面内部处理。如果是模态蒙层不应允许点击如果是非模态点击蒙层应关闭 dialogPagedialogPage不使用uni.navigatorTo等路由 API而是单独提供了openDialogPage和closeDialogPagedialogPage不影响页面栈和路由地址在getCurrentPages()里不能直接得到 dialogPage需要通过 UniPage 对象的getDialogPages()获取由于 dialogPage 不进入主页面栈uni.getElementById无法获取 dialogPage 内的元素。如需获取指定页面的元素需拿到该页面的 UniPage 对象后在其上调用.getElementById()如需获取当前 dialogPage 页面的元素应使用this.$page.getElementById()Options API或getCurrentInstance()?.proxy?.$page.getElementById()Composition API在 Android 上dialogPage并不是一个 Activity而是一个全屏 View与主 page 属于同一个 ActivitydialogPage默认不响应 iOS 侧滑返回即disableSwipeBack默认值为 true可在 pages.json 中配置Android 和 Harmony 的 back 键与 back 手势默认响应可通过 dialogPage 的onBackPress生命周期控制是否阻止关闭dialogPage默认不影响调用页面或其 parentPage 的 show / hide 生命周期如需影响例如弹出全屏界面需手动设置triggerParentHidedialogPage 中可以调用普通路由 API如uni.navigateTo、navigateBack但它们并不作用于 dialogPage而是作用于其 parentPage——即旧的路由 API 一律只作用于主 Page在 Web 平台dialogPage 显示时不影响 URL 变化dialogPage默认没有窗体动画。半屏内容建议在页面内通过 css 或 uts 操作页面元素做动画灵活度更高全屏界面可以使用窗体动画但没有pop-in这种与上一个页面联动的动画。1.2 dialogPage 的绑定与多实例规则dialogPage 需绑定在某个主页面parentPage上parentPage 关闭时会自动销毁其挂载的相关 dialogPage在 App 的onLaunch中调用openDialogPage时默认绑定到首页openDialogPage时可通过parentPage参数指定所属页面不指定时默认为当前页面一个主页面可以挂载多个 dialogPage通过UniPage.getDialogPages()获取多个 dialogPage层叠时可以通过 close API 任意关闭某一个当前 dialogPage 打开时会触发前一个 dialogPage 的 onHide生命周期关闭时触发前一个 dialogPage 的onShow生命周期uni.showActionSheet、uni.showModal、uni.showLoading打开的弹框同样由 dialogPage 实现因此调用这些 API 也会触发前一个 dialogPage 的 onHide / onShow。调用时机上需要注意最早调用时机是 App 的onLaunch不支持在main.uts中调用openDialogPage。二、插件源码结构UTS 插件如何按平台组织实现uni-dialogPage是一个典型的UTS 插件。UTS 插件是一种特定的 uni_modules 插件其核心目的是允许 uni-app / uni-app x 开发者使用 UTS 语法来调用扩展 API封装原生系统 API 或三方 SDK。在仓库中该插件的目录结构如下src/uni_modules/uni-dialogPage/ ├── utssdk/ │ ├── app-android/ │ │ └── index.uts # Android 平台实现 │ ├── app-ios/ │ │ ├── index.uts # iOS 平台实现 │ │ └── native.swift # iOS 原生 Swift 代码 │ ├── constants.uts # 动画常量与默认值多平台共用 │ ├── interface.uts # API 类型定义多平台共用 │ └── unierror.uts # 成功/失败结果封装多平台共用 ├── changelog.md ├── package.json └── readme.md这正是 UTS 插件的标准组织方式——实现代码主要位于utssdk目录下并按平台进行分离和组织。原文档中的目录说明可概括为下表| 目录/文件 | 目标平台 | 实现语言 | 作用描述 | | -- | -- | -- | -- | |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 语言编写的、可供所有平台共用的实现源码 |从 package.json 可以看到该插件在 App 端的能力声明openDialogPage与closeDialogPage在 App 平台中kotlin: dom2、swift: true即 Android 端经由 Kotlin/dom2 渲染层实现iOS 端经由 Swift 实现treeShaking: false表示插件默认整体打包。同时在engines中声明了对 HBuilderX^3.6.8的版本要求。三、UTS实现该插件的跨端语言底座uni-dialogPage之所以能同时覆盖 Android / iOS / HarmonyOS / Web / 小程序底层依赖的是utsuni type script语言。这是 uni-app x 引入的一门跨平台、高性能、强类型的现代编程语言它采用与 TypeScript 基本一致的语法规范支持绝大部分 ES6 API但可以被编译为不同平台的编程语言| 目标平台 | 编译产物 | | -- | -- | | Android | Kotlin | | iOS | Swift | | HarmonyOS鸿蒙 | ArkTS | | Web / 小程序 | JavaScript |uts 为了跨端做了两类处理约束一些无法在 Kotlin / Swift / ArkTS 之间平滑映射的 JS 特性会被限制平台增补针对特定平台提供扩展语法。过去在 JS 引擎下运行的语法大部分在 uts 的处理下可以平滑地迁移到 Kotlin 和 Swift 中但有一些无法抹平的差异需要借助条件编译。与 uni-app 的条件编译类似uts 也支持条件编译写在条件编译块里的代码可以调用平台特有的扩展语法。以该插件在 utssdk/app-android/index.uts 中的实现为例可以直观看到条件编译与平台分化的写法// #ifdef VUE3-VAPOR分支Vapor 蒸汽模式调用nativeOpenDialogPage/nativeCloseDialogPage等原生侧 API直接通过回调返回成功/失败// #ifndef VUE3-VAPOR分支则走框架侧路由逻辑从dcloudio/uni-runtime引入navigateDialogPage、getCurrentPage、normalizeRouteOptions等运行时能力。同一份 uts 源码中通过条件编译同时维护两套实现路径这是 uts 跨端约束与平台增补能力在真实插件中的典型体现。四、API 详解openDialogPage 与 closeDialogPage4.1 uni.openDialogPage(options)openDialogPage用于打开模态弹窗页面。其类型定义位于 utssdk/interface.utsopenDialogPage(options: OpenDialogPageOptions): UniPage | null调用成功时返回打开的UniPage实例null表示打开失败。OpenDialogPageOptions的完整参数如下| 名称 | 类型 | 必填 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | url | stringstring.PageURIString | 是 | - | 需要跳转的应用内非 tabBar 页面的路径路径后可以带参数 | | animationType | string | 否 | none | 窗口显示的动画类型 | | animationDuration | number | 否 | 300 | 窗口动画的持续时间单位为 ms | | disableEscBack | boolean | 否 | false | 是否禁用按键盘 ESC 时关闭 | | parentPage | UniPage | 否 | 当前页面 | 要绑定的父级页面实例 | | triggerParentHide | boolean | 否 | false | 是否触发父页面的 onHide 生命周期 | | success | (result: OpenDialogPageSuccess) void | 否 | - | 接口调用成功的回调函数 | | fail | (result: OpenDialogPageFail) void | 否 | - | 接口调用失败的回调函数 | | complete | (result: OpenDialogPageComplete) void | 否 | - | 接口调用结束的回调函数成功、失败都会执行 |其中animationType的合法值及其语义如下在 interface.uts 的联合类型注释中逐一给出| 合法值 | 描述 | | :- | :- | | auto | 自动选择动画效果 | | none | 无动画效果 | | slide-in-right | 从右侧横向滑动效果 | | slide-in-left | 从左侧横向滑动效果 | | slide-in-top | 从上侧竖向滑动效果 | | slide-in-bottom | 从下侧竖向滑动效果 | | fade-in | 从透明到不透明逐渐显示效果 | | zoom-out | 从小到大逐渐放大显示效果 | | zoom-fade-out | 从小到大逐渐放大并且从透明到不透明逐渐显示效果 |在 utssdk/constants.uts 中可以看到这些常量与默认值的实际定义export const DEFAULT_ANIMATION_IN none // 打开动画默认值 export const DEFAULT_ANIMATION_OUT auto // 关闭动画默认值 export const DEFAULT_ANIMATION_DURATION 300 // 动画时长默认 300ms export const DEFAULT_ANIMATION_NAVIGATE_BACK auto export const ANIMATION_IN [ slide-in-right, slide-in-left, slide-in-top, slide-in-bottom, fade-in, zoom-out, // zoom-fade-out, // pop-in, none, ]从源码可以推断zoom-fade-out、pop-in等动画虽然在类型上被允许但在打开动画的实际生效集合中已被注释掉说明当前版本部分动画处于保留/预留状态而关闭动画ANIMATION_OUT则定义了slide-out-right、slide-out-left、slide-out-top、slide-out-bottom、fade-out、zoom-in、none等对称的退出效果。4.2 uni.closeDialogPage(options)closeDialogPage用于关闭模态弹窗页面closeDialogPage(options?: CloseDialogPageOptions | null) : null其参数CloseDialogPageOptions包括| 名称 | 类型 | 默认值 | 描述 | | :- | :- | :- | :- | | dialogPage | UniPage | 当前页面 | 要关闭的 dialogPage 实例 | | animationType | string | auto | 窗口关闭的动画类型slide-out-right、slide-out-left、slide-out-top、slide-out-bottom、fade-out、zoom-in、zoom-fade-in、none、auto | | animationDuration | number | 300 | 窗口关闭动画的持续时间单位为 ms | | success / fail / complete | callback | - | 与 openDialogPage 一致的回调体系 |当不传dialogPage时或传null时Android 实现中会走“关闭当前页面全部 dialogPage”的逻辑通过getCurrentPage()取当前页面再遍历其getDialogPages()逐一执行$close。当显式传入dialogPage时则会校验该页面是否仍然有效——具体校验逻辑可参考 utssdk/app-android/index.uts若dialogPage.$vm.$dialogOptions为空、getParentPage()返回 null、parentPage 不在当前页面栈中且非 tabPage或该 dialogPage 不在 parentPage 的 dialogPages 列表中则判定为dialogPage is not a valid page走fail回调否则执行$close并触发success/complete。4.3 回调结果与错误码插件在 utssdk/unierror.uts 中封装了统一的成功 / 失败结果对象OpenDialogPageSuccessImplerrMsg默认openDialogPage: okOpenDialogPageFailImpl继承UniError默认errCode 4路由错误码4表示框架内部异常errMsg默认为空字符串CloseDialogPageSuccessImplerrMsg默认closeDialogPage: okCloseDialogPageFailImpl继承UniErrorerrCode同样为4。RouteErrorCode类型在 utssdk/interface.uts 中定义为4并在OpenDialogPageFail/CloseDialogPageFail接口中作为errCode的类型说明当前版本下弹窗页面的失败场景统一归类为框架内部异常。五、打开流程的底层调用链以 Android 非 Vapor 模式为例openDialogPage的调用链依次为源码见 utssdk/app-android/index.uts记录navigationStart Date.now()用于路由耗时统计调用normalizeRouteOptions(NAVIGATE_TO, options.url)规范化路由地址处理相对路径、补齐前缀等若返回的errMsg非空则直接失败若指定了parentPage校验其是否存在于getCurrentPages()中不在则报parentPage is not a valid page将规范化后的 url 回写到options.url若animationType pop-in则降级为none调用navigateDialogPage(url, {ANIMATION_TYPE, ANIMATION_DURATION}, NAVIGATE_TO, navigationStart, {disableEscBack, parentPage, triggerParentHide}, successCallback)完成页面跳转回调延迟执行源码注释明确指出“调整回调在 callback 中执行避免时机太早showToast 异常”即success/complete在导航回调中触发而不是跳转瞬间立即触发返回UniPage实例失败返回null。这一调用链印证了 dialogPage 与普通路由的本质差异它经由navigateDialogPage挂载到 parentPage 上不进入主页面栈因而getCurrentPages()无法直接获取。而在Vapor 蒸汽模式下Android 实现直接走nativeOpenDialogPage/nativeCloseDialogPage原生 API以回调方式返回Mapstring, any形式的错误信息由 uts 侧转换为OpenDialogPageFailImpl等结果对象——两个分支共享同一套interface.uts类型与unierror.uts结果封装体现了插件“一份类型定义、多套平台实现”的设计。六、实战示例在页面中使用 dialogPage仓库自带完整的可运行示例位于 src/pages/API/dialog-page/dialog-page.uvue。该示例页演示了 pageBody、safeAreaInsets、窗口尺寸等页面信息的获取以及通过按钮打开各类 dialog 示例含错误路径、triggerParentHide、页面样式、setNavigationBarColor、textarea/input 输入等场景。打开 dialog 的核心代码模式如下基于示例页脚本逻辑const openDialog () { const page uni.openDialogPage({ url: /pages/API/dialog-page/dialog-1, // 非 tabBar 页面路径可带参数 animationType: slide-in-bottom, animationDuration: 300, parentPage: getCurrentPages()[getCurrentPages().length - 1], triggerParentHide: false, success: (res) { console.log(openDialogPage success, res.errMsg) }, fail: (res) { console.error(openDialogPage fail, res.errCode, res.errMsg) }, complete: (res) { console.log(openDialogPage complete) } }) // 返回的 UniPage 实例可用于后续关闭 // uni.closeDialogPage({ dialogPage: page }) }示例页还通过radio-group让用户动态选择打开动画类型auto/none/slide-in-right/slide-in-left/slide-in-top/slide-in-bottom/fade-in/zoom-out/zoom-fade-out对应源码中的openAnimationTypeList与插件 constants.uts 中的ANIMATION_IN枚举保持一致。示例中的其他 dialog 页面还包括 dialog-1.uvue、dialog-2.uvue、dialog-3.uvue页面样式、dialog-4.uvuetriggerParentHide等测试用例见 dialog-page.test.js可作为验证 dialogPage 行为生命周期、蒙层、多实例层叠的参考。使用建议半屏弹窗页面内通过 css 或 uts 操作元素做动画灵活性更高全屏界面可配合窗体动画如slide-in-bottom模态拦截需要阻止用户点击蒙层时在 dialogPage 内部自行处理蒙层点击事件返回键控制通过 dialogPage 的onBackPress生命周期决定是否阻止 Android / Harmony 的 back 键与手势关闭页面通信利用uni.$on/uni.$emit事件总线或openDialogPage返回的UniPage实例进行跨页面操作。七、平台兼容性与版本要求根据仓库 API 文档 docs/api/dialog-page.md 与插件源码中的uniPlatform注解openDialogPage/closeDialogPage的兼容性如下| 平台 | 支持情况 | | :- | :- | | Web | HBuilderX 4.31 | | 微信小程序 | 待支持x | | Android | 4.31Vapor 模式 5.21 | | iOS | 4.31Vapor 模式 5.11 | | HarmonyOS | 4.61Vapor 模式 5.0 |其中triggerParentHide参数要求 4.41Android / iOS / WebHarmonyOS 为 4.61。插件自身在 package.json 中声明 HBuilderX^3.6.8起步具体 API 能力以实际 HBuilderX 版本为准。八、延伸阅读若希望深入了解 uts 语言与 UTS 插件开发仓库内提供了完整的配套文档docs/api/dialog-page.mddialogPage 官方 API 详解参数表、动画合法值、回调结果、兼容性docs/api/unipage.mdUniPage 对象说明getDialogPages()、getElementById()等docs/uts/README.mduts 语言总览docs/uts/uts_diff_ts.mduts 与 TypeScript 的差异docs/plugin/uts-plugin.mdUTS 插件开发指南docs/plugin/uts-for-android.md、docs/plugin/uts-for-ios.md、docs/plugin/uts-for-harmony.md各端开发注意事项docs/plugin/uts-plugin-hybrid.md原生语言混编开发。结语uni-dialogPage以极小的插件体积为 uni-app x 提供了可覆盖导航栏与 tabbar、可拦截系统返回、可多实例层叠的原生级弹窗页面能力。其源码清晰展示了 UTS 插件“类型定义与平台实现分离、条件编译按需分化、回调结果统一封装”的标准范式一份interface.uts定义 API 契约一份constants.uts收敛动画常量一份unierror.uts统一成功失败语义再以app-android/index.uts、app-ios/index.uts等按平台落地执行逻辑。理解这个插件既能帮助你直接上手 dialogPage 弹窗开发也能作为学习 UTS 插件工程化组织的参考范本。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-app x dialogPage 实战指南覆盖导航栏与 tabBar 的透明模态页面及 openDialogPage / closeDialogPage 实现原理uni app x dialogPage 实战指南覆盖导航栏与 tabBar 的透明模态页面及 openDialogPage / closeDialogPag示例工程前端移动开发跨平台uni-app x 模态弹窗 uni-modal 深度解析基于 UTS 插件实现 showModal 与 hideModal 的跨端方案uni app x 模态弹窗 uni modal 深度解析基于 UTS 插件实现 showModal 与 hideModal 的跨端方案 模态弹窗Modal示例工程前端移动开发跨平台uni-app x uni-pageScrollTo UTS 插件源码解析页面滚动 API 的跨端实现与使用指南uni app x uni pageScrollTo UTS 插件源码解析页面滚动 API 的跨端实现与使用指南 uni pageScrollTo 是 uni示例工程前端移动开发跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考