dialogPage概述

展示全部

# dialogPage概述

HBuilderX 4.31+新增了dialogPage，适用于制作弹框。

# 需求背景

uni.showModal、actionsheet，自定义性不足
通过前端组件实现的弹框，无法覆盖pages.json的导航栏和tabbar
前端实现的弹框，无法拦截back按键，一点back整页关了
组件方式实现弹框，需要每个页面都引入组件，写法较麻烦

# dialogPage方案

dialogPage是一种背景透明的页面，可以覆盖pages.json中的导航栏和tabbar。之前的page被称为主page或parentPage。dialogPage需要挂在主page上。

dialogPage是一种特殊的page，它和主page有很多相同之处：

dialogPage需在pages.json注册
dialogPage有页面生命周期，onLoad里也可以拿到各种参数
dialogPage里如果引用了组件，对于组件而言，其page就是dialogPage。组合式组件中监听onPageShow，是监听dialogPage，而不是dialogPage的parentPage。
dialogPage可以通过uni.$on等eventbus方案进行页面级通信

dialogPage和主page的区别：

dialogPage的背景固定为透明、大小为铺满应用。蒙层由页面内部实现，蒙层颜色、是否响应点击，均由页面内部处理。如果是模态，蒙层不应该允许点击；非模态，则点击蒙层应关闭dialogPage
dialogPage不使用uni.navigatorTo等路由API，而是单独提供了openDialogPage和closeDialogPage
dialogPage不影响页面栈和路由地址，在getCurrentPages里不能直接得到dialogPage（需在UniPage对象通过getDialogPages获取）
dialogPage在Android上并不是一个activity，而是一个全屏view，它和主page所属同一个activity。
dialogPage不响应iOS侧滑返回，即disableSwipeBack默认值为true。响应Android的back键和back手势，可通过dialogPage onBackPress生命周期控制是否阻止Android的back键和back手势关闭dialogPage。
dialogPage不影响调用页面或其parentPage的show、hide生命周期。
dialogPage中可以调用普通路由api，比如uni.navigateTo、navigateBack，但并不作用于dialogPage，而是作用于其parentPage。即，之前的路由API均只作用于主Page。
在web平台，dialogPage显示时，不影响URL的变化。
dialogPage默认没有窗体动画，建议在页面内通过css或uts操作页面元素进行动画。

dialogPage的绑定：

dialogPage需绑定在某个主页面上，即parentPage。parentPage页面关闭时，自动销毁相关dialogPage。
在app的onLaunch调用openDialogPage，绑定到首页。
openDialogPage 时可通过 parentPage 参数指定所属页面，不指定时默认为当前页面。

多dialogPage注意事项：

dialogPage可以有多个，通过UniPage对象的getDialogPages()可以获取主页面挂载的所有dialogPage。
多个dialogPage层叠时，可以通过close api任意关闭某个dialogPage。
当前 dialogPage 关闭会触发前一个 dialogPage onShow 生命周期

app-android平台注意事项：

dialogPage不会创建Android原生Activity，复用parentPage的Android原生Activity。

# uni.openDialogPage(options)

打开模态弹窗页面

# openDialogPage 兼容性

Web	Android	Android uni-app x UTS 插件	Android uni-app UTS 插件	iOS	iOS uni-app x UTS 插件	iOS uni-app UTS 插件
4.31	4.31	4.31	x	4.31	4.31	x

# 参数

名称

类型

必填

默认值

兼容性

描述

options

OpenDialogPageOptions

是

名称

类型

必备

默认值

兼容性

描述

url

string (string.PageURIString)

是

需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数

animationType

string

否

窗口显示的动画类型

合法值	兼容性	描述
auto	-	自动选择动画效果
none	-	无动画效果
slide-in-right	-	从右侧横向滑动效果
slide-in-left	-	左侧横向滑动效果
slide-in-top	-	从上侧竖向滑动效果
slide-in-bottom	-	从下侧竖向滑动效果
fade-in	-	从透明到不透明逐渐显示效果
zoom-out	-	从小到大逐渐放大显示效果
zoom-fade-out	-	从小到大逐渐放大并且从透明到不透明逐渐显示效果

animationDuration

number

否

窗口关闭动画的持续时间，单位为 ms

disableEscBack

boolean

否

是否禁用按键盘 ESC 时关闭

parentPage

UniPage

否

要绑定的父级页面实例

名称

类型

必备

默认值

兼容性

描述

route

string

是

页面的路由地址

options

UTSJSONObject

是

页面的路由参数信息

ComponentPublicInstance

否

UniPage vue 实例对象

~~$vm~~

ComponentPublicInstance

否

UniPage vue 实例对象 已废弃，仅为了向下兼容保留

success

(result: AsyncApiSuccessResult) => void

否

接口调用成功的回调函数

fail

(result: OpenDialogPageFail) => void

否

接口调用失败的回调函数

complete

(result: AsyncApiResult) => void

否

接口调用结束的回调函数（调用成功、失败都会执行）

# UniPage 的方法

# getPageStyle(): UTSJSONObject

获取当前页面样式。详细属性配置请参考PageStyle

# getPageStyle 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
4.31	4.31	4.31	4.31

# 返回值

类型
UTSJSONObject

# setPageStyle(style: UTSJSONObject): void

设置当前页面样式。详细属性配置请参考PageStyle

# setPageStyle 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
4.31	4.31	4.31	4.31

# 参数

名称	类型	必填	默认值	兼容性	描述
style	UTSJSONObject	是	-	-	-

# getParentPage(): UniPage | null

用于 dialogPage 获取所属父页面

# getParentPage 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
4.31	4.31	4.31	4.31

# 返回值

类型	必备
UniPage	否

# getDialogPages(): UniPage[]

获取当前页面的 dialog 子页面集合

# getDialogPages 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
4.31	4.31	4.31	4.31

# 返回值

类型
Array<UniPage>

# getElementById(id: string.IDString | string): UniElement | null

返回一个匹配特定 ID 的元素，如果不存在，返回 null。
如果需要获取指定的节点类型，需要使用 as 进行类型转换。
ID 区分大小写，且应该是唯一的。如果存在多个匹配的元素，则返回第一个匹配的元素。

# getElementById 兼容性

Web	Android	iOS
4.31	4.31	4.31

# 参数

名称	类型	必填	默认值	兼容性	描述
id	string.IDString \| string	是	-	-	-

# 返回值

类型	必备
UniElement	否

# getAndroidView(): View | null

返回 android 平台页面根 view

# getAndroidView 兼容性

Web	Android	iOS
x	4.31	x

# 返回值

类型	必备
View	否

# getIOSView(): UIView | null

返回 ios 平台页面根 view

# getIOSView 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
x	x	x	4.33

# 返回值

类型	必备
UIView	否

# getHTMLElement(): UniElement | null

返回页面 HTML Element 对象

# getHTMLElement 兼容性

Web	Android	iOS
4.31	x	x

# 返回值

类型	必备
UniElement	否

# $setPageStyle(style: UTSJSONObject): void

设置当前页面样式。详细属性配置请参考PageStyle 已废弃，仅为了向下兼容保留

# $setPageStyle 兼容性

Web	Android	iOS
4.13	4.13	4.13

# 参数

名称	类型	必填	默认值	兼容性	描述
style	UTSJSONObject	是	-	-	-

# $getPageStyle(): UTSJSONObject

获取当前页面样式。详细属性配置请参考PageStyle 已废弃，仅为了向下兼容保留

# $getPageStyle 兼容性

Web	Android	iOS
4.13	4.13	4.13

# 返回值

类型
UTSJSONObject

# OpenDialogPageFail 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是	-	-	路由错误码 - 4: 框架内部异常
errSubject	string	是	-	-	统一错误主题（模块）名称
data	any	否	-	-	错误信息中包含的数据
cause	Error	否	-	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	-	-

# AsyncApiResult 的属性值

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	-

# 返回值

类型

必备

UniPage

否

名称

类型

必备

默认值

兼容性

描述

route

string

是

页面的路由地址

options

UTSJSONObject

是

页面的路由参数信息

ComponentPublicInstance

否

UniPage vue 实例对象

~~$vm~~

ComponentPublicInstance

否

UniPage vue 实例对象 已废弃，仅为了向下兼容保留

# UniPage 的方法

# getPageStyle(): UTSJSONObject

获取当前页面样式。详细属性配置请参考PageStyle

# getPageStyle 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
4.31	4.31	4.31	4.31

# 返回值

类型
UTSJSONObject

# setPageStyle(style: UTSJSONObject): void

设置当前页面样式。详细属性配置请参考PageStyle

# setPageStyle 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
4.31	4.31	4.31	4.31

# 参数

名称	类型	必填	默认值	兼容性	描述
style	UTSJSONObject	是	-	-	-

# getParentPage(): UniPage | null

用于 dialogPage 获取所属父页面

# getParentPage 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
4.31	4.31	4.31	4.31

# 返回值

类型	必备
UniPage	否

# getDialogPages(): UniPage[]

获取当前页面的 dialog 子页面集合

# getDialogPages 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
4.31	4.31	4.31	4.31

# 返回值

类型
Array<UniPage>

# getElementById(id: string.IDString | string): UniElement | null

# getElementById 兼容性

Web	Android	iOS
4.31	4.31	4.31

# 参数

名称	类型	必填	默认值	兼容性	描述
id	string.IDString \| string	是	-	-	-

# 返回值

类型	必备
UniElement	否

# getAndroidView(): View | null

返回 android 平台页面根 view

# getAndroidView 兼容性

Web	Android	iOS
x	4.31	x

# 返回值

类型	必备
View	否

# getIOSView(): UIView | null

返回 ios 平台页面根 view

# getIOSView 兼容性

Web	Android	iOS	iOS uni-app x UTS 插件
x	x	x	4.33

# 返回值

类型	必备
UIView	否

# getHTMLElement(): UniElement | null

返回页面 HTML Element 对象

# getHTMLElement 兼容性

Web	Android	iOS
4.31	x	x

# 返回值

类型	必备
UniElement	否

# $setPageStyle(style: UTSJSONObject): void

设置当前页面样式。详细属性配置请参考PageStyle 已废弃，仅为了向下兼容保留

# $setPageStyle 兼容性

Web	Android	iOS
4.13	4.13	4.13

# 参数

名称	类型	必填	默认值	兼容性	描述
style	UTSJSONObject	是	-	-	-

# $getPageStyle(): UTSJSONObject

获取当前页面样式。详细属性配置请参考PageStyle 已废弃，仅为了向下兼容保留

# $getPageStyle 兼容性

Web	Android	iOS
4.13	4.13	4.13

# 返回值

类型
UTSJSONObject

# 参见

# uni.closeDialogPage(options?)

关闭模态弹窗页面

closeDialogPage 可通过 dialogPage 参数指定要关闭的 dialogPage, 不指定时默认关闭当前页面的所有 dialogPage。

# closeDialogPage 兼容性

Web	Android	Android uni-app x UTS 插件	Android uni-app UTS 插件	iOS	iOS uni-app x UTS 插件	iOS uni-app UTS 插件
4.31	4.31	4.31	x	4.31	4.31	x

# 参数

名称

类型

必填

默认值

兼容性

描述

options

CloseDialogPageOptions

否

名称

类型

必备

默认值

兼容性

描述

dialogPage

UniPage

否

要关闭的 dialogPage 实例

animationType

string

否

窗口关闭的动画类型
- auto: 自动选择动画效果
- none: 无动画效果
- slide-out-right: 横向向右侧滑出屏幕动画
- slide-out-left: 横向向左侧滑出屏幕动画
- slide-out-top: 竖向向上侧滑出屏幕动画
- slide-out-bottom: 竖向向下侧滑出屏幕动画
- fade-out: 从不透明到透明逐渐隐藏动画
- zoom-in: 从大逐渐缩小关闭动画
- zoom-fade-in: 从大逐渐缩小并且从不透明到透明逐渐隐藏关闭动画

合法值	兼容性	描述
auto	-	自动选择动画效果
none	-	无动画效果
slide-out-right	-	横向向右侧滑出屏幕动画
slide-out-left	-	横向向左侧滑出屏幕动画
slide-out-top	-	竖向向上侧滑出屏幕动画
slide-out-bottom	-	竖向向下侧滑出屏幕动画
fade-out	-	从不透明到透明逐渐隐藏动画
zoom-in	-	从大逐渐缩小关闭动画
zoom-fade-in	-	从大逐渐缩小并且从不透明到透明逐渐隐藏关闭动画

animationDuration

number

否

窗口关闭动画的持续时间，单位为 ms

success

(result: AsyncApiSuccessResult) => void

否

接口调用成功的回调函数

fail

(result: CloseDialogPageFail) => void

否

接口调用失败的回调函数

complete

(result: AsyncApiResult) => void

否

接口调用结束的回调函数（调用成功、失败都会执行）

# AsyncApiSuccessResult 的属性值

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	-

# CloseDialogPageFail 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是	-	-	路由错误码 - 4: 框架内部异常
errSubject	string	是	-	-	统一错误主题（模块）名称
data	any	否	-	-	错误信息中包含的数据
cause	Error	否	-	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	-	-

# AsyncApiResult 的属性值

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	-

# 返回值

类型
null

# 参见

# 示例

hello uni-app x

Template

Script

<template>
  <view class="uni-padding-wrap">
    <button class="uni-common-mt" id="go-next-page" @click="goNextPage">go next page</button>
    <button class="uni-common-mt" id="open-dialog1" @click="openDialog1">open dialog 1</button>
    <button class="uni-common-mt" id="open-dialog1-wrong-path" @click="openDialog1WrongPath">open dialog page 1 with
      wrong path</button>
    <button class="uni-common-mt" id="go-next-page-open-dialog1" @click="goNextPageOpenDialog1">go next page & open
      dialog1</button>
  </view>
</template>

# 通用类型

# GeneralCallbackResult

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	错误信息

# Tips

可通过如下方式获取 dialogPage。

// 1. 通过 parentPage 获取 dialogPage 集合
const pages = getCurrentPages()
// 获取当前页面
const page = pages[pages.length-1]
// 获取当前页面的 `dialogPage` 集合
const dialogPages = page.getDialogPages()

// 2. 在 dialogPage 中通过 this.$page 获取 dialogPage 实例
// 选项式 API
const dialogPage = this.$page
// 组合式 API
const currentInstance = getCurrentInstance()
const dialogPage = instance?.proxy?.$page

UniDialogPage 实例的 getElementById 方法仅 Android 端支持，其他端返回 null。
tabBar 页面中的 dialogPage，在 App 端不会随 tabBar 页面切换而隐藏，在 Web 端会随 tabBar 页面切换而隐藏。
即：在 tabA 页面打开 dialogPage 后 switchTab 到 tabB 页面在 App 端 dialogPage 仍会显示,
在 Web 端 dialogPage 会隐藏，再次 switchTab 到 tabA 页面 dialogPage 会显示。

运营产品

uni-ad uni统计 uni发行 uni安全专题

开发者服务

问答社区开发者后台

技术文档

uni-app文档 uniCloud文档原生开发者支持文档 HBuilder文档

生态服务

插件市场 OAuth用户开放平台

关于我们： DCloud官网案例需求墙许可协议加入我们赞助我们

联系我们：商务合作：bd@dcloud.io 广告合作：uniad@dcloud.io

DCloud.io 数字天堂（北京）网络技术有限公司是

HTML5中国产业联盟发起单位

京公网安备：11010802035340号

国家信息安全等级保护三级，证书编号：11010813802-20001