Custom Dialog Selection and Development-Using Popup Windows-UI Development (ArkTS-based Declarative Development Paradigm)-ArkUI-Application Framework

Overview

When developing dialogs, you need to select the appropriate implementation scheme based on the dialog type. Common dialog types include text prompt dialogs, confirmation dialogs, menus, and action sheets. This section delves into the fundamental types of dialogs and their features, incorporating currently recommended dialog types, supported capabilities, and practical usage suggestions to introduce the selection and development process for dialogs, to help you address common issues encountered when using dialogs (for example, implementing swipe interception and ensuring dialog persist after returning from page navigation).

Dialog Capabilities

This section introduces dialog capabilities from three aspects:

Key characteristics: introduces common requirements that you may have for dialogs from the perspective of interaction.
Capability support: describes the specific capabilities and functions supported by the recommended dialog solutions.
Usage suggestions: compares the differences among the recommended dialog solutions and provides suggestions for dialog selection.

Key Characteristics of Dialogs

In addition to the content and style of dialogs, there are several common interaction demands from the perspective of user interaction.

Expand

Interaction Demand	Display Effect	Interaction Demand	Display Effect	Interaction Demand	Display Effect
Swipe-to-close: Decide whether the dialog should close on swipe gestures. This is often interaction-driven to prevent users from exiting too easily.		Tap-outside-to-close: When the dialog content is critical, disallow closing the dialog by tapping outside to ensure user engagement and processing.		Custom animations: Determine whether you need to configure custom entry and exit animations and their types.
Content retention upon navigation: Decide whether the dialog content should remain on the previous page after navigation, such as with privacy dialogs.		Focus capture: Some custom dialogs implemented with dialog components grab focus on display, which can cause the keyboard to retract and then reappear.	)	Keyboard avoidance: Ensure that the dialog and its content are not obscured when the keyboard is up, though there are scenarios where this is not necessary, like with comment reply dialogs.

Capability Support

Currently, the system provides a variety of custom dialog capabilities, detailed as follows:

Recommended dialogs
1. UIContext based custom dialogs: UIContext dialogs are a context-based dialog management mechanism. By encapsulating content with ComponentContent, they decouple from the UI, offering flexible invocation that meets your encapsulation needs. These dialogs provide high flexibility with fully customizable styles. When the associated UIContext is destroyed (for example, when a page is closed), the dialog automatically closes without manual management. Additionally, dialog hierarchy is managed by the UIContext, decoupled from page routing, making it suitable for complex scenarios. Currently, the main APIs for implementing dialogs include UIContext.openBindSheet(), UIContext.getPromptAction().openCustomDialog(), and UIContext.getOverlayManager().
2. Custom dialog box implemented based on Navigation.Dialog: NavDestination.Dialog is a dialog box effect implemented based on the Navigation component. It is essentially a route page and exists in the route stack. It can be used to implement modal and semi-modal forms and is applicable to scenarios such as transparent pages and pages where the dialog box does not disappear during page switching.
  
  These dialogs offer good flexibility and extensibility in their technical implementation, with strong support for page decoupling and custom dialog styling. For details about their capabilities, see Capability support.
Not recommended dialogs
1. Basic Custom Dialog (\CustomDialog): CustomDialogController has many restrictions on usage. It does not support dynamic creation or refresh and can only be used within custom components decorated with @Component. This means that dialog creation and management are tightly coupled with specific components, increasing code complexity and maintenance costs. Moreover, when a single page needs to display multiple custom dialogs, each dialog must have its own CustomDialogController declared, leading to redundant UI layer code and making it difficult to decouple dialog logic from page logic.
2. @ohos.promptAction (prompt): @ohos.promptAction is a global method that can cause issues when executed without a UIContext. You may also face problems if you cannot specify a UIContext, potentially causing the prompt to appear in an unintended window. For these reasons, it is not recommended. Additionally, it uses the system's default dialog style, which does not allow for extensive custom styling. It is suitable for simple alert-type dialogs that need to maintain a consistent system look and feel but has a limited scope of application.

Due to the differences in dialog types, there are certain limitations in terms of functionality, interaction experience, and applicable scenarios. The recommended dialog capabilities are summarized in the following table for reference.

Expand

Description	UIContext.openBindSheet()	UIContext.getPromptAction().openCustomDialog()	UIContext.getOverlayManager()	NavDestination.Dialog
Swipe-to-close response	√	√	√	√
Tap-outside-to-close	√	√	×	×
Custom entry and exit animations	×	√	Partially supported (Animations are not supported by default. You can customize an animation.)	Partially supported (System transition animations are supported since API version 13.)
Dialog persistence across page switches	√	√	√	√
Focus handling	√	√	√	√
Keyboard avoidance mode	×	√	⍻ (Set it based on the window.)	⍻ (Set it based on the window.)

In addition to the six scenarios mentioned above, which correspond to common interaction demands, there are other capability support situations, such as whether the dialog supports decoupling from the page and custom dialog styling, as detailed below.

Expand

Description	UIContext.openBindSheet()	UIContext.getPromptAction().openCustomDialog()	UIContext.getOverlayManager()	NavDestination.Dialog
Page decoupling	√	√	√	√
Custom dialog styling (background, rounded corners, and more)	√	√	√	√
Dialog overlay	√	√	√	√
Layer management	√	√	√	√
Route decoupling	√	√	√	×
Event dispatch to page	×	×	√	√

Usage Suggestions of Dialogs

Currently, UIContext dialogs and Navigation dialogs are the main recommended dialog types. They differ in terms of position and presentation, as well as applicable scenarios. You are advised to choose based on development needs and specific scenarios.

Expand

Dialog Type	Position and Presentation	Scenario
UIContext.openBindSheet()	Such a dialog typically slides up from the bottom. It is semi-modal and occupies part of the screen height.	Suitable for displaying a list of bottom operation options, such as bottom operations and list options.
UIContext.getPromptAction().openCustomDialog()	Such a dialog is centrally displayed by default. It can be set to modal or non-modal through the isModal parameter.	Suitable for various scenarios requiring highly customizable dialog content and styles, such as operation confirmation prompts and form input dialogs.
UIContext.getOverlayManager()	Such a dialog can be displayed at any position on the screen. It is independent of page layout and overlays all components beneath the dialog.	Used for implementing global floating tips or operation buttons, such as customer service entry balls, event icon entries, and guide prompts.
NavDestination.Dialog	Such a dialog is based on Navigation. It exists in the route stack as a Component page and is transparent by default.	Suitable for all forms of dialogs. Note that this dialog is actually implemented as a page and occupies the page stack.

Implementation of Common Dialog Scenarios

Based on different service requirements, there are various types of dialogs to choose from. This section selects several common dialog implementation cases and introduces them in combination with their corresponding capability features.

Implementing an Image-Text Prompt Dialog (Similar to Toast)

Image-text prompt dialogs are commonly used to display the results of user operations, such as success or failure messages, and can also show loading animations while waiting for system responses.

Implementation

showToast supports only text s and cannot implement dialogs that contain both images and text. In such scenarios, you can use UIContext.getPromptAction().openCustomDialog().

Sample Code

Use @Builder to customize the buildText() function to encapsulate the content and style of the image-text prompt dialog and add an image and text to the dialog.

Collapse
Word wrap
Dark theme
Copy code
@Builder
function buildText(params: Params) {
  Row() {
    Image($r('app.media.checkmark_circle'))
      .width(24)
      .height(24)
      .margin({ right: 16 })
    Text(params.text)
      .fontSize(16)
  }
  .justifyContent(FlexAlign.Center)
  .backgroundColor(Color.White)
  .padding({ left: 24, right: 24 })
  .height(50)
  .borderRadius(24)
}

Use UIContext.getPromptAction().openCustomDialog() to open a dialog and use BaseDialogOptions to configure the dialog style.

Collapse
Word wrap
Dark theme
Copy code
let uiContext = this.getUIContext();
PromptActionClass.setContext(uiContext);
imageTipsContentNode = new ComponentContent(getUIContext, wrapBuilder(buildText), new Params(this.message));
PromptActionClass.setContentNode(imageTipsContentNode);
PromptActionClass.setOptions({
  isModal: false,
  alignment: DialogAlignment.Bottom,
  offset: { dx: 0, dy: -80 },
  focusable: false
});
PromptActionClass.openDialog();
setTimeout(() => {
  PromptActionClass.closeDialog(imageTipsContentNode);
}, 3000)

Note that dialogs will preempt focus when they display. If there is a text input box currently in use, this will cause the keyboard to retract. In scenarios where the original UI usability needs to be maintained, users may want the dialog to not proactively obtain focus to avoid interrupting their current operations. In this case, you can set the focusable attribute of the promptAction.BaseDialogOptions to false, which means that the dialog is not allowed to obtain focus.

Collapse
Word wrap
Dark theme
Copy code
PromptActionClass.setOptions({
  isModal: false,
  alignment: DialogAlignment.Bottom,
  offset: { dx: 0, dy: -80 },
  focusable: false
});

Implementing a Privacy Dialog

Privacy dialogs are primarily used to ensure legal compliance, requiring applications to obtain user consent before collecting user data. When users open a privacy dialog, they can tap hyperlinks within the dialog to navigate to detailed privacy policy pages. Upon returning, the privacy dialog remains visible, ensuring that users can make informed decisions based on the information provided.

In the privacy page, there are two main points to consider:

When users tap the privacy policy link within the privacy dialog and navigate to a new page, the dialog should remain beneath the new page, and its state should be preserved when returning to the original page.
When users perform a swipe gesture, you can set up an interception to prevent the swipe operation, requiring users to exit the dialog by clicking Accept or Decline.

Implementation

Since API version 16, you can use UIContext.getPromptAction().openCustomDialog() to implement this feature. It allows you to configure page-level dialogs using levelMode and levelUniqueId.

Dialog persistence across page switches

Import the custom dialog wrapper class PromptActionClass, which defines the methods for opening and closing the dialog and setting options.

Collapse
Word wrap
Dark theme
Copy code
import { PromptActionClass } from '../utils/PromptActionClass';

Use levelMode and levelUniqueId in BaseDialogOptions to set up the dialog to appear within a specific page. The two parameters task a node ID within the page. After the parameters are set, the dialog will automatically query the Navigation page corresponding to this ID and mount itself under that page. As shown in the following code example, the Button node is the node of the specified page. After the custom ID is set, the getFrameNodeById() method is used to obtain the node, and then the getUniqueId method is used to obtain the internal ID of the node and pass it as the value of levelUniqueId.

Collapse
Word wrap
Dark theme
Copy code
Column() {
  Row() {
    Image($r('app.media.chevron_left'))
      .width(16)
      .height(16)
      .margin({ left: 12 })
  }
  .width(40)
  .height(40)
  .borderRadius(48)
  .margin({ top: 42 })
  .backgroundColor('#e6eaeb')
  .onClick(() => {
    this.pageStack.pop();
  })

  Row() {
    Button('OPEN')
      .id('privacyDialog')
      .fontSize(16)
      .width('100%')
      .borderRadius(20)
      .margin({ bottom: 16 })
      .backgroundColor('#0A59F7')
      .onClick(() => {
        const node: FrameNode | null = this.getUIContext().getFrameNodeById('privacyDialog');
        let uiContext = this.getUIContext();
        PromptActionClass.setContext(uiContext);
        PromptActionClass.setContentNode(privacyContentNode);
        PromptActionClass.setOptions({
          levelMode: LevelMode.EMBEDDED,
          levelUniqueId: node?.getUniqueId(),
          onWillDismiss: (dismissDialogAction: DismissDialogAction) => {
            hilog.info(0xFF00, 'TAG', JSON.stringify(dismissDialogAction.reason));
          }
        })
        PromptActionClass.openDialog();
      })
  }
  .width('100%')
  .alignItems(VerticalAlign.Center)
}
.width('100%')
.height('100%')
.padding({
  left: 16,
  right: 16,
  bottom: 32
})
.justifyContent(FlexAlign.SpaceBetween)
.alignItems(HorizontalAlign.Start)

Swipe interception

Swipe interception is implemented through the onWillDismiss callback function of UIContext.getPromptAction(). When users perform operations such as tapping outside the dialog, swiping from the edge, pressing the Back button, or pressing the ESC key on the keyboard, registering this callback prevents the dialog from closing immediately. Within the callback, you can use the enum DismissReason to determine the reason for the closure and decide whether to close the dialog.
Collapse
Word wrap
Dark theme
Copy code
```
PromptActionClass.setOptions({
  levelMode: LevelMode.EMBEDDED,
  levelUniqueId: node?.getUniqueId(),
  onWillDismiss: (dismissDialogAction: DismissDialogAction) => {
    hilog.info(0xFF00, 'TAG', JSON.stringify(dismissDialogAction.reason));
  }
})
```

For API versions prior to 16, you can implement the dialog using NavDestinationMode.DIALOG. Essentially, this approach retains the dialog by managing it as a route page within the navigation stack.

Implementation using NavDestinationMode.DIALOG

Dialog persistence across page switches

If you implement the dialog using NavDestinationMode.DIALOG, you need to set the display mode (specified by mode) of NavDestination to NavDestinationMode.DIALOG.
Collapse
Word wrap
Dark theme
Copy code
```
NavDestination() {
  // ... Dialog content.
}
.mode(NavDestinationMode.DIALOG)
```
Swipe interception

Implement swipe interception using the onBackPressed() callback of NavDestination. When the physical back button is tapped or a swipe gesture is used, this callback is triggered. If the return value is true, the back button logic is overridden, thereby implementing swipe interception.
Collapse
Word wrap
Dark theme
Copy code
```
NavDestination() {
  // ...
}
.hideTitleBar(true)
.mode(NavDestinationMode.DIALOG)
.onBackPressed((): boolean => {
  return true;
})
```

Implementing a Progress Bar Dialog

Progress bar dialogs are a common type of dialog used to provide user feedback on task progress during time-consuming operations. The key feature of these dialogs is the data interaction between the dialog and the page, which involves refreshing the dialog content.

Implementation

Updating dialog content in the page

The content of the custom component in the dialog can be updated using the update() method provided by ComponentContent. That is, the contentNode.update() updates the data in the dialog and synchronizes the data to the UI for display.

Collapse
Word wrap
Dark theme
Copy code
Text(isProgressRunning ? $r('app.string.pause') : $r('app.string.start'))
  .fontSize(16)
  .fontColor('#0A59F7')
  .margin({ top: 8 })
  .onClick(() => {
    isProgressRunning = !isProgressRunning;
    if (isProgressRunning) {
      timer = setInterval(() => {
        if (value === 100) {
          value = 0;
        }
        value += 10;
        progressContentNode.update(new ProgressParams($r('app.string.progress'), value, isProgressRunning));
      }, 1000)
    } else {
      clearInterval(timer);
    }
    progressContentNode.update(new ProgressParams($r('app.string.progress'), value, isProgressRunning));
  })

Preventing dialog closure on outside tapping

To ensure that the task continues running even after the progress bar dialog is closed, configure the dialog to not auto-cancel by setting autoCancel to true. This way, tapping outside the dialog does not interrupt the task flow. When the dialog is reopened, the progress bar continues updating based on the current task status.

Collapse
Word wrap
Dark theme
Copy code
let uiContext = this.getUIContext();
PromptActionClass.setContext(uiContext);
progressContentNode = new ComponentContent(getUIContext, wrapBuilder(buildProgress),
  new ProgressParams($r('app.string.progress'), value, false));
PromptActionClass.setContentNode(progressContentNode);
PromptActionClass.setOptions({
  autoCancel: true,
  transition: TransitionEffect.asymmetric(
    TransitionEffect.OPACITY.animation({ duration: 1000 }),
    TransitionEffect.OPACITY.animation({ delay: 500, duration: 1000 })
  )
})
PromptActionClass.openDialog();
Index.ets

Customizing entry and exit animations

In application development, the default system dialog animations often do not meet specific needs. To implement custom dialog entry and exit animations, you can use the following methods: fade in and fade out; slide in from the left and slide out to the right; slide up from the bottom and slide down to close. The following uses the fade-in/fade-out effect as an example to introduce custom dialog entry and exit animations.

You can use the transition parameter of BaseDialogOptions to set the transition effect for displaying and exiting a dialog, thereby implementing the fade-in and fade-out effect for the display and exit animations of a custom dialog.
Collapse
Word wrap
Dark theme
Copy code
```
transition: TransitionEffect.asymmetric(
  TransitionEffect.OPACITY.animation({ duration: 1000 }),
  TransitionEffect.OPACITY.animation({ delay: 500, duration: 1000 })
)
```
Index.ets

Implementing a Bottom Operation Dialog

Bottom operation dialogs typically refer to the semi-modal menus triggered by tapping on the operation bar (such as the More button in the top-right corner) in an application screen. These dialogs usually feature functions like sharing, adding, deleting, modifying, and querying. The main content of the operation dialog is a list, which can be of fixed or variable height.

Implementation

Use openBindsheet to encapsulate the component content displayed on the semi-modal page through ComponentContent, and use SheetOptions to set the style of the semi-modal page.

Fixed-height operation dialog

Set the height to SheetSize.MEDIUM for a fixed-height dialog that cannot be dragged by the user.

Collapse
Word wrap
Dark theme
Copy code
Text($r('app.string.operation_list'))
  .onClick(() => {
    let contentNode =
      new ComponentContent(this.getUIContext(), wrapBuilder(buildActionList));
    let uiContext = this.getUIContext();
    let uniqueId = this.getUniqueId();
    let frameNode: FrameNode | null = uiContext.getFrameNodeByUniqueId(uniqueId);
    let targetId = frameNode?.getFirstChild()?.getUniqueId();
    uiContext.openBindSheet(contentNode, {
      title: { title: $r('app.string.more') },
      height: SheetSize.MEDIUM,
      backgroundColor: '#F1F3F5',
      preferType: SheetType.BOTTOM
    }, targetId)
      .then(() => {
        hilog.info(0xFF00, 'TAG', 'openBindSheet success');
      })
      .catch((err: BusinessError) => {
        hilog.info(0xFF00, 'TAG', 'openBindSheet error: ' + err.code + ' ' + err.message);
      })
  })
  .width('100%')
Index.ets

Variable-height operation dialog

You can set the height to be variable by using the detents parameter of SheetOptions.

Collapse
Word wrap
Dark theme
Copy code
uiContext.openBindSheet(contentNode, {
  title: { title: $r('app.string.more') },
  height: SheetSize.MEDIUM,
  backgroundColor: '#F1F3F5',
  preferType: SheetType.BOTTOM,
  detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200]
}, targetId)
  .then(() => {
    hilog.info(0xFF00, 'TAG', 'openBindSheet success');
  })
  .catch((err: BusinessError) => {
    hilog.info(0xFF00, 'TAG', 'openBindSheet error: ' + err.code + ' ' + err.message);
  })
Index.ets

Implementing a Comment Reply Dialog

The comment reply module is widely used in text and video applications. It includes an editing area, a friends list, a list of frequently used emojis, and an emoji panel (as shown in the figure below). It allows users to input text, emojis, tag friends, and select images. For details about the implementation solution, see Comment Dialog Box.

Sample Code

Custom Dialog Selection and Development