弹窗的定义可参考官方文档:弹窗概述,常见弹窗实现方式可以分为以下几种:
路由跳转方式:
出现该问题的根本原因是弹窗不是页面的一个组件或者与页面不是一个显示层级,弹窗显示层级在所有的页面之上。其中自定义弹窗(CustomDialog)、默认模式下的@ohos.promptAction(弹窗)、模态窗口等都是显示在Page页面层级之上。导致在不关闭弹窗的情况下,新打开的页面都在弹窗下面。
通过Navigation导航跳转时,由于Navigation页面为根页面,与NavDestination页面为父子组件关系,在一个Page内,所以相比较router跳转,当实现弹窗的方式是和Page同级显示时,依旧会显示在NavDestination页面上方。
例如,将Navigation页面的mode()属性参数NavigationMode.Stack改为NavigationMode.Auto,并采用平板展示时,通过@ohos.window(窗口)实现弹窗效果,能直观的复现上述问题。弹窗在NavDestination子页面创建,弹窗显示在根页面之上,也会导致在不关闭弹窗的情况下,新打开的NavDestination页面都在弹窗下面。
可以通过通用属性bindSheet,实现半模态弹窗的方式,实现页面级弹窗。需要在SheetOptions内设置其mode属性为SheetMode.EMBEDDED,表示其为页面级弹出框。以Navigation为例,示例代码如下:
@Entry
@Component
struct Index {
@Provide('pathStack') pathStack: NavPathStack = new NavPathStack();
build() {
Navigation(this.pathStack) {
Column() {
Button('Navigation页')
.onClick(() => {
this.pathStack.pushPathByName('IndexTwo', null);
});
}
.justifyContent(FlexAlign.Center)
.width('100%')
.height('100%');
}
.mode(NavigationMode.Auto)
.width('100%')
.height('100%');
}
} @Builder
export function IndexTwoBuilder() {
IndexTwo();
}
@Component
struct IndexTwo {
@State isShow: boolean = false;
@Consume('pathStack') pathStack: NavPathStack;
@Builder
myBuilder() {
Column() {
Text('我是半模态弹窗');
Button('jump')
.margin({ top: 10 })
.onClick(() => {
this.pathStack.pushPathByName('IndexThree', null);
});
}
.margin({ top: 22 })
.justifyContent(FlexAlign.SpaceEvenly);
}
build() {
NavDestination() {
Stack() {
Row() {
Column() {
Button('点击打开弹窗')
.onClick(() => {
this.isShow = true;
});
}
.width('100%');
}
.height('100%');
};
}
.bindSheet($$this.isShow, this.myBuilder(), {
height: 400,
mode: SheetMode.EMBEDDED, // 设置显示层级Navigation导航挂载在NavDestination节点上,若是Router路由挂载在Page节点上。
backgroundColor: Color.White,
onWillAppear: () => {
console.info('BindSheet onWillAppear.');
},
onAppear: () => {
console.info('BindSheet onAppear.');
},
onWillDisappear: () => {
console.info('BindSheet onWillDisappear.');
},
onDisappear: () => {
console.info('BindSheet onDisappear.');
}
})
.title('IndexTwo');
}
} @Builder
export function IndexThreeBuilder() {
IndexThree();
}
@Component
struct IndexThree {
@Consume('pathStack') pathStack: NavPathStack;
build() {
NavDestination() {
Column() {
Text('IndexThree')
.height('100%');
}
.width('100%')
.height('100%');
}
.title('IndexThree');
}
} 方案一实现效果如下:

当采用@ohos.router(页面路由)方式跳转NavDestinationMode.DIALOG页面时不适用,会导致弹窗蒙层不透明。
NavDestinationMode.DIALOG实现自定义弹窗方案,示例代码如下:
@Entry
@Component
struct Index {
@Provide('pathStack') pathStack: NavPathStack = new NavPathStack();
build() {
Navigation(this.pathStack) {
Column() {
Button('Navigation页')
.onClick(() => {
this.pathStack.pushPathByName('IndexTwo', null);
});
}
.justifyContent(FlexAlign.Center)
.width('100%')
.height('100%');
}
.mode(NavigationMode.Auto)
.width('100%')
.height('100%');
}
} // 自定义弹窗组件
@Builder
export function IndexTwoBuilder() {
IndexTwo();
}
@Component
export struct IndexTwo {
@Consume('pathStack') pathStack: NavPathStack;
build() {
NavDestination() {
Row() {
Column() {
Button('点击打开弹窗')
.onClick(() => {
this.pathStack.pushPathByName('CustomDialog', '', false); // 推送弹窗页面
});
}
.width('100%');
}
.height('100%');
}
.title('IndexTwo');
}
} @Builder
export function CustomDialogBuilder() {
CustomDialog();
}
@Component
export struct CustomDialog {
@Consume('pathStack') pathStack: NavPathStack;
build() {
NavDestination() {
Stack({ alignContent: Alignment.Center }) {
Text('') // 弹窗遮罩
.onClick(() => {
this.pathStack.pop(); // 点击遮罩退出该页面,达到关闭弹窗效果
})
.width('100%')
.height('100%')
.opacity(0) // 遮罩透明度调节
.backgroundColor(0x000000);
Column() {
Text('我是弹窗');
Button('jump')
.onClick(() => {
this.pathStack.pushPathByName('IndexThree', ''); // 弹窗内推送IndexThree页面
});
}
.justifyContent(FlexAlign.SpaceAround)
.backgroundColor(Color.White)
.borderRadius(30)
.height('126vp')
.width('90%');
}.height('100%').width('100%');
}
.backgroundColor('rgba(0,0,0,0.5)')
.hideTitleBar(true)
.mode(NavDestinationMode.DIALOG);
}
} @Builder
export function IndexThreeBuilder() {
IndexThree();
}
@Component
struct IndexThree {
@Consume('pathStack') pathStack: NavPathStack;
build() {
NavDestination() {
Column() {
Text('IndexThree')
.height('100%');
}
.width('100%')
.height('100%');
}
.title('IndexThree');
}
} 方案二实现效果如下:

在API15的版本中新提供了页面级弹出框参考示例。当弹出框的options入参中设置levelMode属性,值为LevelMode.EMBEDDED时表示开启页面级弹出框能力。该levelMode属性不仅适用于PromptAction弹窗,也适用于CustomDialog弹窗,详见CustomDialogControllerOptions对象说明。
@Entry
@Component
struct Index {
@Provide('pathStack') pathStack: NavPathStack = new NavPathStack();
build() {
Navigation(this.pathStack) {
Column() {
Button('Navigation页')
.onClick(() => {
this.pathStack.pushPathByName('IndexTwo', null);
});
}
.justifyContent(FlexAlign.Center)
.width('100%')
.height('100%');
}
.mode(NavigationMode.Auto)
.width('100%')
.height('100%');
}
} import { LevelMode, ImmersiveMode } from '@kit.ArkUI';
@Builder
function customDialogBuilder(pathStack: NavPathStack) {
Column() {
Text('我是弹窗');
Button('jump')
.onClick(() => {
// 在弹窗内部进行路由跳转
pathStack.pushPathByName('IndexThree', null);
});
}
.justifyContent(FlexAlign.SpaceAround)
.backgroundColor(Color.White)
.borderRadius(10)
.height('126vp')
.width('100%');
}
@Builder
export function IndexTwoBuilder() {
IndexTwo();
}
@Component
struct IndexTwo {
private uiContext: UIContext = this.getUIContext();
@Consume('pathStack') pathStack: NavPathStack;
@Builder
customDialogComponent() {
customDialogBuilder(this.pathStack);
}
build() {
NavDestination() {
Row() {
Column() {
Button('点击打开弹窗')
.id('test_text')
.onClick(() => {
const node: FrameNode | null = this.getUIContext().getFrameNodeById('test_text') || null;
this.uiContext.getPromptAction().openCustomDialog({
builder: () => {
this.customDialogComponent();
},
levelMode: LevelMode.EMBEDDED, // 启用页面级弹出框
levelUniqueId: node?.getUniqueId(), // 设置页面级弹出框所在页面的任意节点ID
immersiveMode: ImmersiveMode.EXTEND, // 设置页面级弹出框蒙层的显示模式
});
});
}
.width('100%');
}
.height('100%');
}
.title('IndexTwo');
}
} @Builder
export function IndexThreeBuilder() {
IndexThree();
}
@Component
struct IndexThree {
@Consume('pathStack') pathStack: NavPathStack;
build() {
NavDestination() {
Column() {
Text('IndexThree')
.height('100%');
}
.width('100%')
.height('100%');
}
.title('IndexThree');
}
} 方案三Navigation导航实现效果如下:

onWindowStageCreate(windowStage: window.WindowStage): void {
// Main window is created, set main page for this ability
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/PageA', (err) => {
if (err.code) {
hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
return;
}
// 全局使用
AppStorage.setOrCreate('windowStage', windowStage);
hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
});
} // PageA.ets页面
import window from '@ohos.window';
import { Context } from '@kit.AbilityKit';
import * as subWin from './subWindow'; // 导入命名路由页面(子窗口)
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
// 全局使用
@State windowStage: window.WindowStage = AppStorage.get('windowStage') as window.WindowStage;
@State context: Context = this.getUIContext().getHostContext() as Context;
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Text('这是 page A')
.fontSize(20)
.margin({ bottom: 10 });
Button('点击打开子窗口')
.onClick(() => {
this.windowStage.createSubWindow('mySubWindow', (err, windowClass) => {
if (err.code) {
console.error(`Failed. Cause code: ${err.code}, message: ${err.message}`);
}
try {
windowClass.loadContentByName(subWin.entryName, (err: BusinessError) => {
const errCode: number = err.code;
if (errCode) {
console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in loading the content.');
// 设置子窗口左上角坐标
windowClass.moveWindowTo(0, 0);
// 展示子窗口
windowClass.showWindow();
// 设置子窗口全屏化布局避让安全区
windowClass.setWindowLayoutFullScreen(false);
windowClass.setWindowBackgroundColor('#63727272');
});
} catch (exception) {
console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
;
});
});
}
.backgroundColor(Color.White)
.width('100%')
.height('100%');
}
} // subWindow.ets页面
import { window } from '@kit.ArkUI';
export const entryName: string = 'subWindow';
@Entry({ routeName: entryName })
@Component
export struct subWindow {
@StorageProp('pageInfos') pageInfos: NavPathStack = new NavPathStack();
onBackPress(): boolean | void {
window.findWindow('mySubWindow').destroyWindow(); // 销毁子窗口
}
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Stack({ alignContent: Alignment.Center }) {
Text('') // 弹窗遮罩
.onClick(() => {
window.findWindow('mySubWindow').destroyWindow(); // 销毁子窗口
})
.width('100%')
.height('100%')
.opacity(0) // 遮罩透明度调节
.backgroundColor(0x000000);
Column() {
Text('我是弹窗');
Button('jump')
.onClick(() => {
this.getUIContext().getRouter().pushUrl({
url: 'pages/PageB'
});
});
}
.justifyContent(FlexAlign.SpaceAround)
.backgroundColor(Color.White)
.borderRadius(30)
.height('126vp')
.width('90%');
}.height('100%').width('100%');
}
.width('100%')
.height('100%');
}
} // PageB.ets页面
@Entry
@Component
struct PageB {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Text('这是 Page B')
.fontSize(20)
.margin({ bottom: 10 });
}
.backgroundColor(Color.White)
.width('100%')
.height('100%')
.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]);
}
} 方案四实现效果如下:

Q:除以上方案外,是否还有其他方式可以实现页面级弹窗?
A:通过组件的通用zIndex/visibility属性以及if/else语法控制组件的显隐,模拟实现自定义弹窗效果,但是该方案并不推荐,系统已经封装有各种弹窗,层级、动效都有接口可控制,通过该方式实现弹窗过于复杂且不方便维护。
Q:怎样实现多层弹窗效果?
A:弹窗嵌套即可。可以使用官方弹窗组件CustomDialog嵌套CustomDialog;也可以在CustomDialog官方弹窗内采用本文方案混合使用,遵循谁后打开,谁显示在上层的原则。
Q:设置zIndex属性层级最高的情况下,为什么没效果?
A:zIndex是设置同层组件之间的渲染优先级权重,但不支持跨层比较权重。
Q:Navigation页面中,在弹出框的options入参中设置levelMode属性,页面级弹出框不生效?
A:弹窗层级控制本质上是弹窗所挂载的父节点不同,默认弹窗挂在Root节点下,所以层级最高,页面级弹窗中router路由需要挂载在Page节点下,而Navigation路由需要挂载在NavDestination节点下。所以页面级弹出框只能在NavDestination页面下,设置页面级弹框才会生效,即:在Navigation中嵌套NavDestination,然后在弹出框的options入参中设置levelMode属性,页面级弹出框就会生效。
Q:openCustomDialog的levelMode的属性在API15以下会程序报错。
A:在API15及以上版本中才支持的levelMode属性,当运行在低版本系统(API15以下)时会导致兼容性问题,可能直接触发异常或者存在闪退风险 (不能识别等问题)。