Dialog Box Layer Management

In ArkUI, dialog boxes are directly mounted to the root node in ascending order of their levels. Under the root node, a dialog box on the right is displayed on top of a dialog box on the left. The newly created dialog box is inserted into the corresponding position based on its level. Dialog boxes with the same level are mounted in the order they were created.

Since API version 18, you can set the levelOrder parameter to manage the display sequence of dialog boxes. This lets you control which dialog box appears on top of others.

Constraints

Using levelOrder to manage the display sequence of dialog boxes is only supported for dialog boxes created using the following APIs: openCustomDialog, CustomDialog, AlertDialog, ActionSheet, and showDialog.

NOTE

Dialog box layer management does not support subwindow scenarios. If showInSubWindow is set to true, the levelOrder parameter has no effect, and the display sequence of dialog boxes cannot be dynamically updated.

Creating Dialog Boxes at Different Levels

NOTE

For details about the variables, see Sample Code.

1. Initialize a dialog box content area with a Text component.

   @Builder
   normalCustomDialog(index: number) {
     Column() {
       // Configure the resource whose name is 'open_normal_dialog' and value is a non-empty string in the resources\base\element\string.json file.
       Text(this.getUIContext().getHostContext()?.resourceManager.getStringByNameSync('open_normal_dialog') as string +
         index).fontSize(30)
     }.height(400).padding(5).justifyContent(FlexAlign.SpaceBetween)
   }
   

   DialogBoxLayer.ets

2. Initialize another dialog box content area with a button to open a common dialog box: In the click event, call the getPromptAction API in UIContext to obtain a PromptAction object. Then, use this object to call the openCustomDialog API and set the levelOrder parameter to 0 to create a normal-level dialog box.

   @Builder
   topCustomDialog() {
     Column() {
       // Replace $r('app.string.top_dialog') with the actual resource file. In this example, the value in the resource file is "I am a top-level dialog box."
       Text($r('app.string.top_dialog')).fontSize(30)
       Row({ space: 50 }) {
         // Replace $r('app.string.open_dialog') with the actual resource file. In this example, the value in the resource file is "Open Normal Dialog Box."
         Button($r('app.string.open_dialog'))
           .onClick(() => {
             this.getUIContext().getPromptAction().openCustomDialog({
               builder: () => {
                 this.normalCustomDialog(this.dialogIndex);
               },
               levelOrder: LevelOrder.clamp(0),
             })
               .catch((err: BusinessError) => {
                 hilog.error(DOMAIN, 'dialogBoxLayer', 'openCustomDialog error: ' + err.code + '' + err.message);
               });
             this.dialogIndex++;
           })
       }
     }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween)
   }
   

   DialogBoxLayer.ets

3. Create a top-level dialog box: In the click event, call the getPromptAction API in UIContext to obtain a PromptAction object. Then, use this object to call the openCustomDialog API and set the levelOrder parameter to 100000 to create a top-level dialog box.

   this.getUIContext().getPromptAction().openCustomDialog({
     builder: () => {
       this.topCustomDialog();
     },
     levelOrder: LevelOrder.clamp(100000)
   }).catch((err: BusinessError) => {
     hilog.error(DOMAIN, 'dialogBoxLayer', 'openCustomDialog error: ' + err.code + ' ' + err.message);
   });
   

   DialogBoxLayer.ets

Sample Code

import { LevelOrder } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const INDEX: number = 0;
const DOMAIN = 0x0000;

@Entry
@Component
export struct DialogBoxLayer {
  @StorageLink('dialogIndex') dialogIndex: number = INDEX;

  @Builder
  normalCustomDialog(index: number) {
    Column() {
      // Configure the resource whose name is 'open_normal_dialog' and value is a non-empty string in the resources\base\element\string.json file.
      Text(this.getUIContext().getHostContext()?.resourceManager.getStringByNameSync('open_normal_dialog') as string +
        index).fontSize(30)
    }.height(400).padding(5).justifyContent(FlexAlign.SpaceBetween)
  }


  @Builder
  topCustomDialog() {
    Column() {
      // Replace $r('app.string.top_dialog') with the actual resource file. In this example, the value in the resource file is "I am a top-level dialog box."
      Text($r('app.string.top_dialog')).fontSize(30)
      Row({ space: 50 }) {
        // Replace $r('app.string.open_dialog') with the actual resource file. In this example, the value in the resource file is "Open Normal Dialog Box."
        Button($r('app.string.open_dialog'))
          .onClick(() => {
            this.getUIContext().getPromptAction().openCustomDialog({
              builder: () => {
                this.normalCustomDialog(this.dialogIndex);
              },
              levelOrder: LevelOrder.clamp(0),
            })
              .catch((err: BusinessError) => {
                hilog.error(DOMAIN, 'dialogBoxLayer', 'openCustomDialog error: ' + err.code + '' + err.message);
              });
            this.dialogIndex++;
          })
      }
    }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween)
  }


  build() {
    NavDestination() {
      Row() {
        Column({ space: 5 }) {
          // Replace $r('app.string.click_dialog') with the actual resource file. In this example, the value in the resource file is "Show Dialog Box."
          Button($r('app.string.click_dialog'))
            .fontSize(20)
            .onClick(() => {
              this.getUIContext().getPromptAction().openCustomDialog({
                builder: () => {
                  this.topCustomDialog();
                },
                levelOrder: LevelOrder.clamp(100000)
              }).catch((err: BusinessError) => {
                hilog.error(DOMAIN, 'dialogBoxLayer', 'openCustomDialog error: ' + err.code + ' ' + err.message);
              });
            })
        }.width('100%')
      }
    }
  }
}