• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Dialog Box Focus Policy
2The 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.
3
4Since API version 19, the [focusable](../reference/apis-arkui/js-apis-promptAction.md#basedialogoptions11) parameter can be used to control whether a dialog box acquires focus.
5
6## Constraints
7
8The [openCustomDialog](arkts-uicontext-custom-dialog.md) and [CustomDialog](arkts-common-components-custom-dialog.md) APIs support management focus acquisition through the **focusable** parameter.
9
10> **NOTE**
11>
12> Only dialog boxes that are displayed on top of the current window can acquire focus.
13
14## Creating a Non-Focusable Dialog Box
15
16> **NOTE**
17>
18> For details about the variables, see [Example](#example).
19
201. Initialize a dialog box content area containing a **Text** component.
21
22  ```ts
23  private message = 'Dialog box'
24  @State dialogIdIndex: number = 0
25  @Builder customDialogComponent() {
26    Column({ space: 5 }) {
27      Text(this.message + this.dialogIdIndex)
28        .fontSize(30)
29    }
30    .height(200)
31    .padding(5)
32    .justifyContent(FlexAlign.SpaceBetween)
33  }
34  ```
35
362. Create a **TextInput** component. In its **onChange** event function, obtain the [PromptAction](../reference/apis-arkui/js-apis-arkui-UIContext.md#promptaction) object by calling the [getPromptAction](../reference/apis-arkui/js-apis-arkui-UIContext.md#getpromptaction) API of [UIContext](../reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext). Then, use this object to call the [openCustomDialog](../reference/apis-arkui/js-apis-arkui-UIContext.md#opencustomdialog12) API and set the [focusable](../reference/apis-arkui/js-apis-promptAction.md#basedialogoptions11) parameter to **false** to create the dialog box.
37
38  ```ts
39  TextInput()
40    .onChange(() => {
41      this.dialogIdIndex++
42      this.getUIContext().getPromptAction().openCustomDialog({
43        builder: () => {
44          this.customDialogComponent()
45        },
46        focusable: false
47      }).then((dialogId: number) => {
48        setTimeout(() => {
49          this.getUIContext().getPromptAction().closeCustomDialog(dialogId);
50        }, 3000)
51      })
52    })
53  ```
54
55## Example
56This 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.
57  ```ts
58  @Entry
59  @Component
60  export struct Index {
61    private message = 'Dialog box'
62    @State dialogIdIndex: number = 0
63    @Builder customDialogComponent() {
64      Column({ space: 5 }) {
65        Text(this.message + this.dialogIdIndex)
66          .fontSize(30)
67      }
68      .height(200)
69      .padding(5)
70      .justifyContent(FlexAlign.SpaceBetween)
71    }
72
73    build() {
74      Column({ space: 5 }) {
75        TextInput()
76          .onChange(() => {
77            this.dialogIdIndex++
78            this.getUIContext().getPromptAction().openCustomDialog({
79              builder: () => {
80                this.customDialogComponent()
81              },
82              focusable: false
83            }).then((dialogId: number) => {
84              setTimeout(() => {
85                this.getUIContext().getPromptAction().closeCustomDialog(dialogId);
86              }, 3000)
87            })
88          })
89      }.width('100%')
90    }
91  }
92  ```
93![dialog-focusable-demo1](figures/dialog-focusable-demo1.gif)
94