Dialog Box Focus Policy

The focus strategy of ArkUI dialog boxes can be configured to determine whether to interrupt the user's current operation and shift focus to the newly opened dialog box. If the dialog box is set not to acquire focus, it will not interrupt the user's current operation when it appears. For example, when a user is entering text in a text box, a newly opened dialog box will not close the soft keyboard, and focus will remain on the text box.

Since API version 19, the focusable parameter can be used to control whether a dialog box acquires focus.

Constraints

The openCustomDialog and CustomDialog APIs support management focus acquisition through the focusable parameter.

NOTE

Only dialog boxes that are displayed on top of the current window can acquire focus.

Creating a Non-Focusable Dialog Box

NOTE

For details about the variables, see Example.

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

   @State dialogIdIndex: number = 0;
   // Configure the resource whose name is 'dialog_message' and value is a non-empty string in the resources\base\element\string.json file.
   private message: string =
     this.getUIContext().getHostContext()?.resourceManager.getStringByNameSync('dialog_message') as string;
   
   @Builder
   customDialogComponent() {
     Column({ space: 5 }) {
       Text(this.message + this.dialogIdIndex)
         .fontSize(30)
     }
     .height(200)
     .padding(5)
     .justifyContent(FlexAlign.SpaceBetween)
   }
   

   DialogFocusStrategy.ets

2. Create a TextInput component. In its onChange event function, obtain the PromptAction object by calling the getPromptAction API of UIContext. Then, use this object to call the openCustomDialog API and set the focusable parameter to false to create the dialog box.

   TextInput()
     .onChange(() => {
       this.dialogIdIndex++;
       this.getUIContext().getPromptAction().openCustomDialog({
         builder: () => {
           this.customDialogComponent();
         },
         focusable: false
       }).then((dialogId: number) => {
         setTimeout(() => {
           this.getUIContext().getPromptAction().closeCustomDialog(dialogId);
         }, 3000);
       });
     })
   

   DialogFocusStrategy.ets

Example

This example demonstrates how to achieve the following effect: When the user is entering text in the text box, the newly opened dialog box will not close the soft keyboard, and focus will remain on the text box.

@Entry
@Component
export struct Index {
  @State dialogIdIndex: number = 0;
  // Configure the resource whose name is 'dialog_message' and value is a non-empty string in the resources\base\element\string.json file.
  private message: string =
    this.getUIContext().getHostContext()?.resourceManager.getStringByNameSync('dialog_message') as string;

  @Builder
  customDialogComponent() {
    Column({ space: 5 }) {
      Text(this.message + this.dialogIdIndex)
        .fontSize(30)
    }
    .height(200)
    .padding(5)
    .justifyContent(FlexAlign.SpaceBetween)
  }


  build() {
    NavDestination() {
      Column({ space: 5 }) {
        TextInput()
          .onChange(() => {
            this.dialogIdIndex++;
            this.getUIContext().getPromptAction().openCustomDialog({
              builder: () => {
                this.customDialogComponent();
              },
              focusable: false
            }).then((dialogId: number) => {
              setTimeout(() => {
                this.getUIContext().getPromptAction().closeCustomDialog(dialogId);
              }, 3000);
            });
          })
      }.width('100%')
    }
  }
}