 与 UniPage 对象的完整解析)
uni-app x 页面栈管理指南getCurrentPages() 与 UniPage 对象的完整解析【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app在 uni-app x 中getCurrentPages()是获取当前页面栈实例的核心 API它以数组形式按栈的顺序返回页面实例第一个元素为首页最后一个元素为当前页面。自 HBuilderX 4.31 起该 API 的返回值升级为UniPage对象数组开发者可以借此动态读取/修改页面样式pageStyle、获取页面原生视图与安全区信息、甚至管理 dialogPage 子弹窗页面栈。本文将结合当前仓库的官方文档与 hello uni-app x 示例工程源码系统讲解页面栈模型、UniPage 的完整能力、两种 API 风格下的取页面写法以及基于仓库自动化测试可以验证的实战用法。getCurrentPages() 与页面栈模型getCurrentPages()函数用于获取当前页面栈的实例返回值是一个数组数组中的元素为页面实例第一个元素是首页最后一个元素是当前页面const pages getCurrentPages() // pages[0] - 首页 // pages[pages.length - 1] - 当前页面在 uni-app x 中页面栈是一个先进后出的结构uni.navigateTo压入新页面、uni.navigateBack弹出页面、uni.switchTab切换 tab 页。通过遍历返回值可以拿到整个路由链路。需要特别注意的是getCurrentPages()获取的是主页面栈不能直接获取 dialogPage 页面拿到主页面UniPage对象后可以通过getDialogPages()方法获取这个主页面的子弹窗页面栈dialogPage 栈详见下文「dialogPage 与主页面栈的关系」选项式 vue 中通过this.$page是另一种快速获取当前页面对象的方式它得到的不是一个页面数组而是一个具体的当前页面且同时支持主页面与 dialogPage。兼容性| Web | 微信小程序 | Android | iOS | iOS(VDOM) UTS 插件 | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.9 | 4.11 | 4.31 | 4.61 |从兼容性表格可以看出Web、微信小程序、Android、iOS、HarmonyOS 均有完整支持其中getCurrentPages()返回UniPage对象数组的能力UniPage 强化自 HBuilderX 4.31 起在各端逐步就位。返回值| 类型 | | :- | | ArrayUniPage |getCurrentPages()返回的是UniPage对象数组。每个页面是一个UniPage对象这个对象上有较多方法比如获取/修改 pageStyle、获取页面高宽与安全区等完整说明见 UniPage 文档。UniPage 对象页面能力的统一入口在 uni-app x 中每个页面都对应一个UniPage对象。通过它既可以读取/修改页面的 pageStyle让 pages.json 中的静态页面配置可以动态修改也可以继续获取原生页面对象如 Android 的View、iOS 的UIView还可以通过vm属性拿到页面的 vue 实例。UniPage 在 App 与 Web 平台较完善在小程序端受小程序平台开放度限制很多能力无法实现具体以 UniPage 属性兼容性表 为准。核心属性| 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :- | :- | | route | string | Web 4.31 / Android 4.31 / iOS 4.31 / HarmonyOS 4.61 | 页面的路由地址 | | options | UTSJSONObject | Web 4.31 / Android 4.31 / iOS 4.31 | 页面的路由参数信息 | | vm | VueComponent | Web 4.31 / Android 4.31 / iOS 4.31 / HarmonyOS 4.61 | UniPage 的 vue 实例对象 | | pageBody | UniPageBody | Web 4.51 / Android 4.51 / iOS 4.51 / HarmonyOS 4.61 | 页面可使用区域信息单位为 px | | safeAreaInsets | UniSafeAreaInsets | Web 4.51 / Android 4.51 / iOS 4.51 / HarmonyOS 4.61 | 页面安全区域插入位置与屏幕边界的距离信息 | | fullscreenElement | UniElement | Android 4.61 / iOS 4.61 / HarmonyOS 4.61 | 已经进入全屏状态的元素 | | width / height | number | Web 4.63 / Android 4.61 / HarmonyOS 4.63 | 页面窗口宽度 / 高度 | | statusBarHeight | number | Web 4.63 / Android 4.61 / HarmonyOS 4.63 | 页面状态栏高度 | |$vm| VueComponent | 已废弃 | 旧版 vue 实例入口建议改用vm|其中pageBodyleft/right/top/bottom/width/height均为 number描述了页面内容可使用区域safeAreaInsetsleft/right/top/bottom描述页面安全区域与屏幕边界的距离二者均从 Android/iOS 4.51 起支持。vm 属性与 $pagevm是页面 vue 实例对象其属性包括$data、$props、$attrs、$slots、$refs、$parent、$root、$options、$el类型为 UniElement以及$page类型为 UniPage。也就是说在页面内this.$page选项式或getCurrentInstance()?.proxy?.$page组合式拿到的正是当前页面的UniPage实例。提示4.31 前仅 Web 与 iOS非 uts 插件端支持通过page.$vm获取 vue 实例4.31 仅 iOS uts 插件环境不支持通过page.vm获取 vue 实例。直接获取当前页面的 UniPageHBuilderX 4.32 起新增了两种直接获取当前页面UniPage实例的快捷方式无需再手动从数组末尾取值// 选项式 API const curPage this.$page // 组合式 API const currentInstance getCurrentInstance() const curPage currentInstance?.proxy?.$page这种写法得到的不是页面数组而是一个具体的当前页面对象它既适用于主页面也适用于 dialogPage。仓库中的 get-current-pages.uvue 示例对$page与getCurrentPages()的等价性做了校验const check$page () : boolean { const pages getCurrentPages() const page pages[pages.length - 1] const $page currentInstance?.proxy?.$page const res $page page console.log(check $page, res) uni.showToast(res ? { title: check success } : { title: check fail, icon: error }) return res }如果$page与getCurrentPages()栈顶元素严格相等说明二者指向同一UniPage实例。配套的 component-check-page.uvue 还演示了在组件内通过getCurrentInstance()同样可以拿到所属页面的$page。dialogPage 与主页面栈的关系dialogPage 是 HBuilderX 4.31 新增的「背景透明页面」用于制作能覆盖 pages.json 导航栏和 tabBar 的弹框与内置界面uni.showModal、uni.showActionSheet、uni.showLoading等底层均由此实现。它与主页面parentPage的核心区别在于dialogPage 需要挂在某个主页面上且不进入主页面栈、不影响路由地址因此getCurrentPages()不能直接获取 dialogPage若想获取 dialogPage需要先拿到其所属主页面parentPage的UniPage再调用getDialogPages()获取挂载在该主页面上的所有 dialogPage 集合dialogPage 在 Android 上不是独立 activity而是与主页面共用同一个 activity 的全屏 view。// 获取当前主页面的 UniPage const pages getCurrentPages() const currentPage pages[pages.length - 1] // 获取该主页面挂载的所有 dialogPage const dialogPages currentPage.getDialogPages()getDialogPages()返回ArrayUniPage兼容性为 Web 4.31 / Android 4.31 / iOS 4.31 / HarmonyOS 4.61微信小程序不支持x。与之配套的getParentPage(): UniPage | null则用于 dialogPage 反向获取所属父页面。dialogPage 的完整机制uni.openDialogPage/uni.closeDialogPage、生命周期、蒙层处理等见 dialogPage 文档。UniPage 的核心方法除属性外UniPage提供了一组面向页面管理的实例方法按用途可分为以下几类。页面样式getPageStyle / setPageStylegetPageStyle(): UTSJSONObject获取当前页面样式setPageStyle(style: UTSJSONObject): void动态设置页面样式。pages.json 中的page下style节点内容可通过这两个 API 读取与修改但要注意getPageStyle()获取的是UniPage 上最终生效的值不是 pages.json 里的原始配置pages.json 里的内容是静态的setPageStyle可以动态设置但并非所有页面样式都支持动态配置4.31 起$getPageStyle/$setPageStyle已废弃仅为向下兼容保留不再需要前缀$使用选项式 API 时不可创建route、options同名响应式变量否则会覆盖当前 page 实例的同名属性。示例组合式 utsconst getPageStyle () : UTSJSONObject { const pages: UniPage[] getCurrentPages() const currentPage pages[pages.length - 1] return currentPage.getPageStyle() } const setPageStyle (style : UTSJSONObject) { const pages getCurrentPages() const currentPage pages[pages.length - 1] currentPage.setPageStyle(style) }可动态配置的 PageStyle 属性来自 unipage.md注意并非所有 pages.json 的 pageStyle 都可以动态修改| 属性 | 类型 | Android | iOS | HarmonyOS | web | 默认值 | | :- | :- | :- | :- | :- | :- | :- | | enablePullDownRefresh | Boolean | 4.13 | 4.13 | 4.61 | 4.13 | false | | backgroundColorContent | String | 4.15 | 4.15 | 4.61 | 4.18 | #ffffff | | navigationBarBackgroundColor | String | 4.18 | 4.18 | 4.61 | 4.18 | #007AFF | | navigationBarTextStyle | String | 4.18 | 4.18 | 4.61 | 4.18 | white | | navigationBarTitleText | String | 4.18 | 4.18 | 4.61 | 4.18 | | | navigationStyle | String | x | x | 4.61 | 4.18 | default | | backgroundColor | String | 4.18 | 4.18 | 4.61 | x | #ffffff | | backgroundTextStyle | String | 4.31 | 4.31 | x | x | dark | | onReachBottomDistance | Number | x | x | 4.61 | 4.18 | 50 | | pageOrientation | String | 4.18 | 4.25 | x | x | auto | | disableSwipeBack | Boolean | x | 4.18 | x | x | false | | hideStatusBar | Boolean | 4.31 | x | x | x | false | | hideBottomNavigationIndicator | Boolean | 4.31 | x | x | x | false |注意事项web 端会自动摇树优化未使用的特性如果整个项目从未使用过下拉刷新enablePullDownRefresh下拉刷新功能会被摇掉此时动态开启将无效app-android 平台的页面是 activity不支持将backgroundColorContent设为透明4.15 版本前app-ios 平台在 pages.json 中将enablePullDownRefresh设为false时无法通过setPageStyle动态开启新版已修复。仓库中的 page-style.uts 定义了可供示例页遍历渲染的PageStyleArray枚举了可动态配置的键与其可选值例如navigationBarBackgroundColor#007AFF / #FFFFFF / #000000、navigationBarTextStylewhite / black、navigationStyledefault / custom、enablePullDownRefreshtrue / false、onReachBottomDistance50 / 100、pageOrientationauto / portrait / landscape、Android 三键导航相关androidThreeButtonNavigationTranslucent、androidThreeButtonNavigationBackgroundColor、androidThreeButtonNavigationStyle等可直接作为可动态修改属性的权威清单参考。针对「动态开关下拉刷新」这一典型场景仓库提供了独立的演示页 set-page-style-disable-pull-down-refresh.uvuefunction setPageStyle(enable : boolean) { // 目前仅支持 enablePullDownRefresh const pages getCurrentPages(); const currentPage pages[pages.length - 1]; currentPage.setPageStyle({ enablePullDownRefresh: enable }); data.enablePullDownRefreshStatus enable }原生视图与 ActivitygetAndroidView / getAndroidActivity / getIOSView / getHTMLElement| 方法 | 返回类型 | 兼容性 | 描述 | | :- | :- | :- | :- | | getAndroidView() | View | null | Android 4.31 | 返回 Android 平台页面根 view | | getAndroidActivity() | Activity | null | Android 4.61 | 返回 Android 平台加载页面内容的 Activity | | getIOSView() | UIView | null | iOS(VDOM) UTS 插件 4.33 | 返回 iOS 平台页面根 view | | getHTMLElement() | UniElement | null | Web 4.31 | 返回页面 HTML Element 对象 |这些方法主要用于 uts 插件场景下与原生层交互例如在 Android 端拿到页面根 view 或 Activity 后注入原生能力。DOM 查询getElementById / querySelector / querySelectorAll| 方法 | 返回类型 | 兼容性 | 描述 | | :- | :- | :- | :- | | getElementById(id: string.IDString | string) | UniElement | null | Web/Android/iOS 4.31HarmonyOS 4.61 | 返回匹配特定 ID 的元素不存在返回 nullID 区分大小写且应唯一 | | querySelector(selector: string.cssSelectorString) | UniElement | null | Web/Android/iOS/HarmonyOS 5.0 | 返回页面中与选择器匹配的第一个元素找不到返回 null | | querySelectorAll(selector: string.cssSelectorString) | UniElement[] | Android/iOS/HarmonyOS 5.0iOS(VDOM) UTS 插件 5.21 | 返回页面中与选择器匹配的元素列表 |getElementById如果需要获取指定的节点类型需要使用as进行类型转换。这一组方法让页面级 DOM 查询成为可能与全局的uni.getElementById仅获取栈顶元素相比它们可以在指定页面的UniPage对象上操作因而也适用于 dialogPage 内部元素。截图与全屏takeSnapshot / exitFullscreentakeSnapshot(options: TakeSnapshotOptions): void对当前页面内容进行截图5.02 起支持 Android/iOS/HarmonyOS。注意只针对页面内容截图不包含状态栏、软键盘等系统 UI 元素也不包含 pages.json 中定义的导航栏与 tabBar。截图行为随页面内容大小、根节点类型与平台不同而有所差异| 页面内容 | 根节点类型 | 截图高度 | | :- | :- | :- | | 超过一屏 | scroll-view 滚动容器 | 长图完整内容 | | 超过一屏 | 非 scroll-view 容器 | 长图完整内容iOS 例外为屏幕高度 | | 不超过一屏 | scroll-view 滚动容器 | 内容高度内容多高截图就多高 | | 不超过一屏 | 非 scroll-view 容器 | 屏幕高度固定一屏高 |options 参数type默认file目前仅支持保存到临时文件目录、format默认png、success返回tempFilePath临时文件路径、fail、complete回调。exitFullscreen(options: ExitFullscreenOptions): voidAndroid/iOS/HarmonyOS 4.61用于逆转此前 UniElement.requestFullscreen 的全屏效果其fail回调中的errCode取值包括106600当前页面已有 element 处于全屏状态、106601当前 element 不支持全屏、106602当前页面没有 element 处于全屏状态、106603页面已销毁或尚未就绪、106604组件未就绪。监听类方法HarmonyOS Vapor 5.0UniPage 还提供一组以on/off配对的事件监听方法返回 number 类型的监听 id可用于取消监听onLayoutChange/offLayoutChange监听/取消页面布局变化回调参数UniPagePerformanceTimingduration单位 msonRenderChange/offRenderChange监听/取消页面渲染变化回调参数UniPagePerformanceRenderTimingupdateDuration、duration单位 msonTouchStart/offTouchStart、onTouchEnd/offTouchEnd监听/取消页面触摸开始、结束事件回调参数为 UniTouchEvent。此外还有createElement(tagName: string): UniElementHarmonyOS(VDOM) 4.63创建组件它们共同构成页面的低层能力集合。仓库示例与自动化测试验证getCurrentPages的完整可运行示例位于 src/pages/API/get-current-pages/get-current-pages.uvue该页面在 pages.json 中注册并通过group: 1,0,1携带测试参数set-page-style-disable-pull-down-refresh演示页则在 pages.json 中注册enablePullDownRefresh默认配置为false。示例页的核心逻辑节选const _getCurrentPages () { data.pages.length 0 const pages getCurrentPages() data.pages.push(pages[0].route) // 首页 route for (let i 1; i pages.length; i) { data.pages.push(pages[i].route) // 逐层输出页面栈 } }自动化测试 get-current-pages.test.js 以 jest 自动化驱动的方式在 Android / iOS / HarmonyOS / Web / 小程序多端对本文介绍的能力逐项断言可作为「哪些能力真实可用」的直接证据getCurrentPages跳转到pages/API/get-current-pages/get-current-pages?test123后调用_getCurrentPages断言首页 route 命中 tabBar 首页验证页面栈顺序$page通过page.callMethod(check$page)断言$page getCurrentPages()栈顶并验证组件内$page同样等价page-style调用setPageStyle({ enablePullDownRefresh: false })后getPageStyle()断言生效值翻转并配合startPullDownRefresh截图比对随后验证 Android 三键导航androidThreeButtonNavigationBackgroundColor/androidThreeButtonNavigationStyle/androidThreeButtonNavigationTranslucent与hideStatusBar、hideBottomNavigationIndicator的动态设置getParentPage/getDialogPages在主页面栈场景断言getParentPage()为 null、getDialogPages()为空数组弹窗场景下的取值见 dialog-page 文档getElementById/querySelector/querySelectorAll断言#check-get-element-by-id-btn可查、#does-not-exist不可查querySelectorAll(.uni-common-mt)数量大于 1 且不存在的类返回空列表getAndroidView仅 Android 端返回非空getHTMLElement仅 Web 端返回非空getAndroidActivity仅 Android 端断言成功takeSnapshotApp 端调用后断言 success/complete 回调计数验证截图链路。这套测试同时印证了各方法的平台适用性边界例如getAndroidView仅在 Android 断言通过getIOSView在非 iOS(VDOM) UTS 插件环境断言为 falsegetHTMLElement仅在 Web 为 true——与上文的兼容性表格完全对应。实战要点与最佳实践取当前页面组合式 API 优先使用getCurrentInstance()?.proxy?.$page选项式使用this.$page若在页面脚本中需要遍历整条链路再使用getCurrentPages()并从末尾取当前页。读取路由参数UniPage.optionsUTSJSONObject携带页面路由参数例如get-current-pages.test.js中通过?test123传入的参数可在page.options[test]读取。动态样式setPageStyle只对表格中列出的属性生效且各平台版本门槛不同设置前可先getPageStyle()读取当前最终生效值再按需合并修改避免覆盖其他属性。dialogPage 场景getCurrentPages()拿不到 dialogPage必须先从主页面UniPage的getDialogPages()获取在 dialogPage 内部取自身页面实例应使用this.$page/$page。原生能力uts 插件开发中通过getAndroidView()/getAndroidActivity()/getIOSView()获取原生根视图与容器是连接 uni-app x 页面与原生 SDK 的常用入口注意getIOSView仅限 iOS(VDOM) UTS 插件环境。Web 摇树提醒在 web 端使用setPageStyle({ enablePullDownRefresh: true })前需确保项目某处真正使用过下拉刷新能力否则相关代码会被摇树优化移除导致动态开启无效。参见UniPage 完整属性与方法文档dialogPage 概述与 openDialogPage / closeDialogPageUTSJSONObject 内置对象文档UniElement DOM 元素文档示例页源码自动化测试用例【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/20 11:10:56 · 阅读 1.2k uni-app x 页面栈管理指南：getCurrentPages() 与 UniPage 对象的完整解析
uni-app x 页面栈管理指南getCurrentPages() 与 UniPage 对象的完整解析【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app在 uni-app x 中getCurrentPages()是获取当前页面栈实例的核心 API它以数组形式按栈的顺序返回页面实例第一个元素为首页最后一个元素为当前页面。自 HBuilderX 4.31 起该 API 的返回值升级为UniPage对象数组开发者可以借此动态读取/修改页面样式pageStyle、获取页面原生视图与安全区信息、甚至管理 dialogPage 子弹窗页面栈。本文将结合当前仓库的官方文档与 hello uni-app x 示例工程源码系统讲解页面栈模型、UniPage 的完整能力、两种 API 风格下的取页面写法以及基于仓库自动化测试可以验证的实战用法。getCurrentPages() 与页面栈模型getCurrentPages()函数用于获取当前页面栈的实例返回值是一个数组数组中的元素为页面实例第一个元素是首页最后一个元素是当前页面const pages getCurrentPages() // pages[0] - 首页 // pages[pages.length - 1] - 当前页面在 uni-app x 中页面栈是一个先进后出的结构uni.navigateTo压入新页面、uni.navigateBack弹出页面、uni.switchTab切换 tab 页。通过遍历返回值可以拿到整个路由链路。需要特别注意的是getCurrentPages()获取的是主页面栈不能直接获取 dialogPage 页面拿到主页面UniPage对象后可以通过getDialogPages()方法获取这个主页面的子弹窗页面栈dialogPage 栈详见下文「dialogPage 与主页面栈的关系」选项式 vue 中通过this.$page是另一种快速获取当前页面对象的方式它得到的不是一个页面数组而是一个具体的当前页面且同时支持主页面与 dialogPage。兼容性| Web | 微信小程序 | Android | iOS | iOS(VDOM) UTS 插件 | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.9 | 4.11 | 4.31 | 4.61 |从兼容性表格可以看出Web、微信小程序、Android、iOS、HarmonyOS 均有完整支持其中getCurrentPages()返回UniPage对象数组的能力UniPage 强化自 HBuilderX 4.31 起在各端逐步就位。返回值| 类型 | | :- | | ArrayUniPage |getCurrentPages()返回的是UniPage对象数组。每个页面是一个UniPage对象这个对象上有较多方法比如获取/修改 pageStyle、获取页面高宽与安全区等完整说明见 UniPage 文档。UniPage 对象页面能力的统一入口在 uni-app x 中每个页面都对应一个UniPage对象。通过它既可以读取/修改页面的 pageStyle让 pages.json 中的静态页面配置可以动态修改也可以继续获取原生页面对象如 Android 的View、iOS 的UIView还可以通过vm属性拿到页面的 vue 实例。UniPage 在 App 与 Web 平台较完善在小程序端受小程序平台开放度限制很多能力无法实现具体以 UniPage 属性兼容性表 为准。核心属性| 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :- | :- | | route | string | Web 4.31 / Android 4.31 / iOS 4.31 / HarmonyOS 4.61 | 页面的路由地址 | | options | UTSJSONObject | Web 4.31 / Android 4.31 / iOS 4.31 | 页面的路由参数信息 | | vm | VueComponent | Web 4.31 / Android 4.31 / iOS 4.31 / HarmonyOS 4.61 | UniPage 的 vue 实例对象 | | pageBody | UniPageBody | Web 4.51 / Android 4.51 / iOS 4.51 / HarmonyOS 4.61 | 页面可使用区域信息单位为 px | | safeAreaInsets | UniSafeAreaInsets | Web 4.51 / Android 4.51 / iOS 4.51 / HarmonyOS 4.61 | 页面安全区域插入位置与屏幕边界的距离信息 | | fullscreenElement | UniElement | Android 4.61 / iOS 4.61 / HarmonyOS 4.61 | 已经进入全屏状态的元素 | | width / height | number | Web 4.63 / Android 4.61 / HarmonyOS 4.63 | 页面窗口宽度 / 高度 | | statusBarHeight | number | Web 4.63 / Android 4.61 / HarmonyOS 4.63 | 页面状态栏高度 | |$vm| VueComponent | 已废弃 | 旧版 vue 实例入口建议改用vm|其中pageBodyleft/right/top/bottom/width/height均为 number描述了页面内容可使用区域safeAreaInsetsleft/right/top/bottom描述页面安全区域与屏幕边界的距离二者均从 Android/iOS 4.51 起支持。vm 属性与 $pagevm是页面 vue 实例对象其属性包括$data、$props、$attrs、$slots、$refs、$parent、$root、$options、$el类型为 UniElement以及$page类型为 UniPage。也就是说在页面内this.$page选项式或getCurrentInstance()?.proxy?.$page组合式拿到的正是当前页面的UniPage实例。提示4.31 前仅 Web 与 iOS非 uts 插件端支持通过page.$vm获取 vue 实例4.31 仅 iOS uts 插件环境不支持通过page.vm获取 vue 实例。直接获取当前页面的 UniPageHBuilderX 4.32 起新增了两种直接获取当前页面UniPage实例的快捷方式无需再手动从数组末尾取值// 选项式 API const curPage this.$page // 组合式 API const currentInstance getCurrentInstance() const curPage currentInstance?.proxy?.$page这种写法得到的不是页面数组而是一个具体的当前页面对象它既适用于主页面也适用于 dialogPage。仓库中的 get-current-pages.uvue 示例对$page与getCurrentPages()的等价性做了校验const check$page () : boolean { const pages getCurrentPages() const page pages[pages.length - 1] const $page currentInstance?.proxy?.$page const res $page page console.log(check $page, res) uni.showToast(res ? { title: check success } : { title: check fail, icon: error }) return res }如果$page与getCurrentPages()栈顶元素严格相等说明二者指向同一UniPage实例。配套的 component-check-page.uvue 还演示了在组件内通过getCurrentInstance()同样可以拿到所属页面的$page。dialogPage 与主页面栈的关系dialogPage 是 HBuilderX 4.31 新增的「背景透明页面」用于制作能覆盖 pages.json 导航栏和 tabBar 的弹框与内置界面uni.showModal、uni.showActionSheet、uni.showLoading等底层均由此实现。它与主页面parentPage的核心区别在于dialogPage 需要挂在某个主页面上且不进入主页面栈、不影响路由地址因此getCurrentPages()不能直接获取 dialogPage若想获取 dialogPage需要先拿到其所属主页面parentPage的UniPage再调用getDialogPages()获取挂载在该主页面上的所有 dialogPage 集合dialogPage 在 Android 上不是独立 activity而是与主页面共用同一个 activity 的全屏 view。// 获取当前主页面的 UniPage const pages getCurrentPages() const currentPage pages[pages.length - 1] // 获取该主页面挂载的所有 dialogPage const dialogPages currentPage.getDialogPages()getDialogPages()返回ArrayUniPage兼容性为 Web 4.31 / Android 4.31 / iOS 4.31 / HarmonyOS 4.61微信小程序不支持x。与之配套的getParentPage(): UniPage | null则用于 dialogPage 反向获取所属父页面。dialogPage 的完整机制uni.openDialogPage/uni.closeDialogPage、生命周期、蒙层处理等见 dialogPage 文档。UniPage 的核心方法除属性外UniPage提供了一组面向页面管理的实例方法按用途可分为以下几类。页面样式getPageStyle / setPageStylegetPageStyle(): UTSJSONObject获取当前页面样式setPageStyle(style: UTSJSONObject): void动态设置页面样式。pages.json 中的page下style节点内容可通过这两个 API 读取与修改但要注意getPageStyle()获取的是UniPage 上最终生效的值不是 pages.json 里的原始配置pages.json 里的内容是静态的setPageStyle可以动态设置但并非所有页面样式都支持动态配置4.31 起$getPageStyle/$setPageStyle已废弃仅为向下兼容保留不再需要前缀$使用选项式 API 时不可创建route、options同名响应式变量否则会覆盖当前 page 实例的同名属性。示例组合式 utsconst getPageStyle () : UTSJSONObject { const pages: UniPage[] getCurrentPages() const currentPage pages[pages.length - 1] return currentPage.getPageStyle() } const setPageStyle (style : UTSJSONObject) { const pages getCurrentPages() const currentPage pages[pages.length - 1] currentPage.setPageStyle(style) }可动态配置的 PageStyle 属性来自 unipage.md注意并非所有 pages.json 的 pageStyle 都可以动态修改| 属性 | 类型 | Android | iOS | HarmonyOS | web | 默认值 | | :- | :- | :- | :- | :- | :- | :- | | enablePullDownRefresh | Boolean | 4.13 | 4.13 | 4.61 | 4.13 | false | | backgroundColorContent | String | 4.15 | 4.15 | 4.61 | 4.18 | #ffffff | | navigationBarBackgroundColor | String | 4.18 | 4.18 | 4.61 | 4.18 | #007AFF | | navigationBarTextStyle | String | 4.18 | 4.18 | 4.61 | 4.18 | white | | navigationBarTitleText | String | 4.18 | 4.18 | 4.61 | 4.18 | | | navigationStyle | String | x | x | 4.61 | 4.18 | default | | backgroundColor | String | 4.18 | 4.18 | 4.61 | x | #ffffff | | backgroundTextStyle | String | 4.31 | 4.31 | x | x | dark | | onReachBottomDistance | Number | x | x | 4.61 | 4.18 | 50 | | pageOrientation | String | 4.18 | 4.25 | x | x | auto | | disableSwipeBack | Boolean | x | 4.18 | x | x | false | | hideStatusBar | Boolean | 4.31 | x | x | x | false | | hideBottomNavigationIndicator | Boolean | 4.31 | x | x | x | false |注意事项web 端会自动摇树优化未使用的特性如果整个项目从未使用过下拉刷新enablePullDownRefresh下拉刷新功能会被摇掉此时动态开启将无效app-android 平台的页面是 activity不支持将backgroundColorContent设为透明4.15 版本前app-ios 平台在 pages.json 中将enablePullDownRefresh设为false时无法通过setPageStyle动态开启新版已修复。仓库中的 page-style.uts 定义了可供示例页遍历渲染的PageStyleArray枚举了可动态配置的键与其可选值例如navigationBarBackgroundColor#007AFF / #FFFFFF / #000000、navigationBarTextStylewhite / black、navigationStyledefault / custom、enablePullDownRefreshtrue / false、onReachBottomDistance50 / 100、pageOrientationauto / portrait / landscape、Android 三键导航相关androidThreeButtonNavigationTranslucent、androidThreeButtonNavigationBackgroundColor、androidThreeButtonNavigationStyle等可直接作为可动态修改属性的权威清单参考。针对「动态开关下拉刷新」这一典型场景仓库提供了独立的演示页 set-page-style-disable-pull-down-refresh.uvuefunction setPageStyle(enable : boolean) { // 目前仅支持 enablePullDownRefresh const pages getCurrentPages(); const currentPage pages[pages.length - 1]; currentPage.setPageStyle({ enablePullDownRefresh: enable }); data.enablePullDownRefreshStatus enable }原生视图与 ActivitygetAndroidView / getAndroidActivity / getIOSView / getHTMLElement| 方法 | 返回类型 | 兼容性 | 描述 | | :- | :- | :- | :- | | getAndroidView() | View | null | Android 4.31 | 返回 Android 平台页面根 view | | getAndroidActivity() | Activity | null | Android 4.61 | 返回 Android 平台加载页面内容的 Activity | | getIOSView() | UIView | null | iOS(VDOM) UTS 插件 4.33 | 返回 iOS 平台页面根 view | | getHTMLElement() | UniElement | null | Web 4.31 | 返回页面 HTML Element 对象 |这些方法主要用于 uts 插件场景下与原生层交互例如在 Android 端拿到页面根 view 或 Activity 后注入原生能力。DOM 查询getElementById / querySelector / querySelectorAll| 方法 | 返回类型 | 兼容性 | 描述 | | :- | :- | :- | :- | | getElementById(id: string.IDString | string) | UniElement | null | Web/Android/iOS 4.31HarmonyOS 4.61 | 返回匹配特定 ID 的元素不存在返回 nullID 区分大小写且应唯一 | | querySelector(selector: string.cssSelectorString) | UniElement | null | Web/Android/iOS/HarmonyOS 5.0 | 返回页面中与选择器匹配的第一个元素找不到返回 null | | querySelectorAll(selector: string.cssSelectorString) | UniElement[] | Android/iOS/HarmonyOS 5.0iOS(VDOM) UTS 插件 5.21 | 返回页面中与选择器匹配的元素列表 |getElementById如果需要获取指定的节点类型需要使用as进行类型转换。这一组方法让页面级 DOM 查询成为可能与全局的uni.getElementById仅获取栈顶元素相比它们可以在指定页面的UniPage对象上操作因而也适用于 dialogPage 内部元素。截图与全屏takeSnapshot / exitFullscreentakeSnapshot(options: TakeSnapshotOptions): void对当前页面内容进行截图5.02 起支持 Android/iOS/HarmonyOS。注意只针对页面内容截图不包含状态栏、软键盘等系统 UI 元素也不包含 pages.json 中定义的导航栏与 tabBar。截图行为随页面内容大小、根节点类型与平台不同而有所差异| 页面内容 | 根节点类型 | 截图高度 | | :- | :- | :- | | 超过一屏 | scroll-view 滚动容器 | 长图完整内容 | | 超过一屏 | 非 scroll-view 容器 | 长图完整内容iOS 例外为屏幕高度 | | 不超过一屏 | scroll-view 滚动容器 | 内容高度内容多高截图就多高 | | 不超过一屏 | 非 scroll-view 容器 | 屏幕高度固定一屏高 |options 参数type默认file目前仅支持保存到临时文件目录、format默认png、success返回tempFilePath临时文件路径、fail、complete回调。exitFullscreen(options: ExitFullscreenOptions): voidAndroid/iOS/HarmonyOS 4.61用于逆转此前 UniElement.requestFullscreen 的全屏效果其fail回调中的errCode取值包括106600当前页面已有 element 处于全屏状态、106601当前 element 不支持全屏、106602当前页面没有 element 处于全屏状态、106603页面已销毁或尚未就绪、106604组件未就绪。监听类方法HarmonyOS Vapor 5.0UniPage 还提供一组以on/off配对的事件监听方法返回 number 类型的监听 id可用于取消监听onLayoutChange/offLayoutChange监听/取消页面布局变化回调参数UniPagePerformanceTimingduration单位 msonRenderChange/offRenderChange监听/取消页面渲染变化回调参数UniPagePerformanceRenderTimingupdateDuration、duration单位 msonTouchStart/offTouchStart、onTouchEnd/offTouchEnd监听/取消页面触摸开始、结束事件回调参数为 UniTouchEvent。此外还有createElement(tagName: string): UniElementHarmonyOS(VDOM) 4.63创建组件它们共同构成页面的低层能力集合。仓库示例与自动化测试验证getCurrentPages的完整可运行示例位于 src/pages/API/get-current-pages/get-current-pages.uvue该页面在 pages.json 中注册并通过group: 1,0,1携带测试参数set-page-style-disable-pull-down-refresh演示页则在 pages.json 中注册enablePullDownRefresh默认配置为false。示例页的核心逻辑节选const _getCurrentPages () { data.pages.length 0 const pages getCurrentPages() data.pages.push(pages[0].route) // 首页 route for (let i 1; i pages.length; i) { data.pages.push(pages[i].route) // 逐层输出页面栈 } }自动化测试 get-current-pages.test.js 以 jest 自动化驱动的方式在 Android / iOS / HarmonyOS / Web / 小程序多端对本文介绍的能力逐项断言可作为「哪些能力真实可用」的直接证据getCurrentPages跳转到pages/API/get-current-pages/get-current-pages?test123后调用_getCurrentPages断言首页 route 命中 tabBar 首页验证页面栈顺序$page通过page.callMethod(check$page)断言$page getCurrentPages()栈顶并验证组件内$page同样等价page-style调用setPageStyle({ enablePullDownRefresh: false })后getPageStyle()断言生效值翻转并配合startPullDownRefresh截图比对随后验证 Android 三键导航androidThreeButtonNavigationBackgroundColor/androidThreeButtonNavigationStyle/androidThreeButtonNavigationTranslucent与hideStatusBar、hideBottomNavigationIndicator的动态设置getParentPage/getDialogPages在主页面栈场景断言getParentPage()为 null、getDialogPages()为空数组弹窗场景下的取值见 dialog-page 文档getElementById/querySelector/querySelectorAll断言#check-get-element-by-id-btn可查、#does-not-exist不可查querySelectorAll(.uni-common-mt)数量大于 1 且不存在的类返回空列表getAndroidView仅 Android 端返回非空getHTMLElement仅 Web 端返回非空getAndroidActivity仅 Android 端断言成功takeSnapshotApp 端调用后断言 success/complete 回调计数验证截图链路。这套测试同时印证了各方法的平台适用性边界例如getAndroidView仅在 Android 断言通过getIOSView在非 iOS(VDOM) UTS 插件环境断言为 falsegetHTMLElement仅在 Web 为 true——与上文的兼容性表格完全对应。实战要点与最佳实践取当前页面组合式 API 优先使用getCurrentInstance()?.proxy?.$page选项式使用this.$page若在页面脚本中需要遍历整条链路再使用getCurrentPages()并从末尾取当前页。读取路由参数UniPage.optionsUTSJSONObject携带页面路由参数例如get-current-pages.test.js中通过?test123传入的参数可在page.options[test]读取。动态样式setPageStyle只对表格中列出的属性生效且各平台版本门槛不同设置前可先getPageStyle()读取当前最终生效值再按需合并修改避免覆盖其他属性。dialogPage 场景getCurrentPages()拿不到 dialogPage必须先从主页面UniPage的getDialogPages()获取在 dialogPage 内部取自身页面实例应使用this.$page/$page。原生能力uts 插件开发中通过getAndroidView()/getAndroidActivity()/getIOSView()获取原生根视图与容器是连接 uni-app x 页面与原生 SDK 的常用入口注意getIOSView仅限 iOS(VDOM) UTS 插件环境。Web 摇树提醒在 web 端使用setPageStyle({ enablePullDownRefresh: true })前需确保项目某处真正使用过下拉刷新能力否则相关代码会被摇树优化移除导致动态开启无效。参见UniPage 完整属性与方法文档dialogPage 概述与 openDialogPage / closeDialogPageUTSJSONObject 内置对象文档UniElement DOM 元素文档示例页源码自动化测试用例【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考