1# Using the UI Context API for UI Operations (UIContext)
2
3## Overview
4
5With the support of the stage model in OpenHarmony, there is a scenario where multiple ArkUI instances run within a single ArkTS engine. In this case, an ArkTS engine may have multiple abilities, each of which may have multiple windows. Each window loads a page through **loadContent**, generating a UIContent (ArkUI instance).
6
7**Figure 1** Multi-instance relationship
8
9![multi-instance](figures/multi-instance.png)
10
11By default, the FA model supports only one ArkUI instance and does not involve multi-instance scenarios. After ArkUI is switched to the stage model, the ArkUI global APIs opened under the FA model cannot clearly determine which instance they are running in when called, leading to ambiguous semantics. In addition, these APIs rely on information related to the ArkUI instance. If the instance is not clear, unexpected behavior at runtime may occur.
12
13To address these issues in multi-instance scenarios, ArkUI has introduced substitute APIs for the stage model. You can use the [getUIContext](../reference/apis-arkui/js-apis-window.md#getuicontext10) API provided by the **Window** module or use the component built-in API [getUIContext](../reference/apis-arkui/arkui-ts/ts-custom-component-api.md#getuicontext) to obtain the **UIContext** instance where the current component is located, and use the corresponding APIs in [UIContext](../reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext) to obtain objects bound to the instance.
14
15## Substitute APIs
16
17The table below lists some of the alternative APIs to replace in multi-instance scenarios. The full range of APIs supported is described in [UIContext](../reference/apis-arkui/js-apis-arkui-UIContext.md).
18
19|               Global API               |               Substitute API               |            Description           |
20| :-----------------------------------: | :-----------------------------------: | :------------------------: |
21|            @ohos.animator             |            createAnimator             |      Custom animation controller.     |
22|     @ohos.arkui.componentSnapshot     |         getComponentSnapshot          |          Component snapshot.         |
23|      @ohos.arkui.componentUtils       |           getComponentUtils           |         Component utility class.        |
24|      @ohos.arkui.dragController       |           getDragController           |         Drag controller.        |
25|         @ohos.arkui.inspector         |            getUIInspector             |        Component layout callback.       |
26|         @ohos.arkui.observer          |             getUIObserver             |          Observer.         |
27|              @ohos.font               |                getFont                |         Custom font registration.        |
28|             @ohos.measure             |            getMeasureUtil             |          Text measurement.         |
29|           @ohos.mediaquery            |             getMediaQuery             |          Media query.         |
30|          @ohos.promptAction           |            getPromptAction            |            Popup.           |
31|             @ohos.router              |               getRouter               |          Page routing.         |
32|              AlertDialog              |            showAlertDialog            |          Alert dialog box.         |
33|              ActionSheet              |            showActionSheet            |        Action sheet.       |
34|         CalendarPickerDialog          |                Not supported                |       Calendar picker dialog box.      |
35|           DatePickerDialog            |         showDatePickerDialog          |      Date picker dialog box.     |
36|           TimePickerDialog            |         showTimePickerDialog          |     Time picker dialog box.    |
37|           TextPickerDialog            |         showTextPickerDialog          |     Text picker dialog box.    |
38|              ContextMenu              |       getContextMenuController        |          Menu control.         |
39| vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx | vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx |        Pixel unit conversion.       |
40|             focusControl              |            getFocusControl            |          Focus control.         |
41|             cursorControl             |           getCursorControl            |          Cursor control.         |
42|              getContext               |            getHostContext             | Obtains the context of the current ability.|
43|        LocalStorage.getShared         |         getSharedLocalStorage         |  Obtains the storage passed by the current ability. |
44|               animateTo               |               animateTo               |          Explicit animation.         |
45|         animateToImmediately          |                Not supported                |        Explicit instant animation.       |
46
47## How to Switch to Substitute APIs
48
49In the following example, a toast is displayed in a specific window. ArkUI can detect that the API is called on the current page and find the corresponding UI instance. In some complex scenarios, however, the API is not initially called on the current page and has been asynchronously called. In this case, the behavior of the instance may become ambiguous.
50
51```ts
52import { promptAction } from '@kit.ArkUI'
53
54@Entry
55@Component
56struct Index {
57  build() {
58    Row() {
59      Button()
60        .onClick(() => {
61          promptAction.showToast({
62            message: 'Message Info',
63            duration: 2000
64          });
65        })
66    }
67  }
68}
69```
70In the following example, **callNative** is a Node-API method. If it is asynchronously triggered by the C side, the current page information cannot be detected at execution, and the UI instance that responds cannot be determined.
71
72```ts
73import { promptAction } from '@kit.ArkUI'
74
75@Entry
76@Component
77struct Index {
78  build() {
79    Row() {
80      Button()
81        .onClick(() => {
82          bridge.callNative("xxxx", ()=> {
83            promptAction.showToast({
84              message: 'Message Info',
85              duration: 2000
86            });
87          })
88        })
89    }
90  }
91}
92```
93
94To address the above issue, you can use the component built-in API [getUIContext](../reference/apis-arkui/arkui-ts/ts-custom-component-api.md#getuicontext) to directly obtain the **UIContext** instance where the current component is located, and then use the **getPromptAction** API in [UIContext](../reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext) to obtain objects bound to the instance. This way, the toast is bound to a specific instance.
95```ts
96@Entry
97@Component
98struct Index {
99  build() {
100    Row() {
101      Button()
102        .onClick(() => {
103          let uiContext = this.getUIContext();
104          let prompt = uiContext.getPromptAction();
105          bridge.callNative("xxxx", ()=> {
106            prompt.showToast({
107              message: 'Message Info',
108              duration: 2000
109            });
110          })
111        })
112    }
113  }
114}
115```
116
117If you are using APIs in [UIContext](../reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext) that do not have substitutes (such as **CalendarPickerDialog** and **animateToImmediately**), or if you are implementing custom service logic that's tied to specific instances, you can use the **runScopedTask** API in **UIContext** to encapsulate these APIs or code snippets.
118
119| API in UIContext| Description                |
120| ------------- | -------------------- |
121| runScopedTask | Executes the closure of the bound instance.|
122
123The above example can also be implemented using the following method.
124
125```ts
126// Execute the closure of the bound instance.
127import { promptAction } from '@kit.ArkUI'
128
129@Entry
130@Component
131struct Index {
132  build() {
133    Row() {
134      Button()
135        .onClick(() => {
136          let uiContext = this.getUIContext();
137          uiContext.runScopedTask(() => {
138            promptAction.showToast({
139              message: 'Message Info',
140              duration: 2000
141            });
142          })
143        })
144    }
145  }
146}
147```
148