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 an ArkUI instance. 6 7**Figure 1** Multi-instance relationship 8 9 10## Ambiguous UI Context 11 12Ambiguous UI context refers to the issue where the calling point cannot clearly identify the target UI instance when invoking ArkUI global APIs. ArkUI global APIs were designed for the FA model, which inherently supports only a single ArkUI instance and does not account for multiple instances. When the framework switches to the stage model, these global APIs, originally exposed in the FA model, cannot determine the specific instance being used. The APIs can only identify a valid UI instance based on the call chain. If the UI instance cannot be traced, this results in ambiguous UI context. Since the implementation of these APIs relies on information from the ArkUI instance, ambiguous UI context can lead to unexpected runtime behavior. 13 14To address this issue, ArkUI has introduced alternative APIs for the stage model to meet needs in multi-ArkUI instance scenarios. You can obtain a [UIContext](../reference/apis-arkui/arkts-apis-uicontext-uicontext.md) object to call the corresponding multi-instance alternative APIs, thereby resolving the UI context ambiguity in multi-instance scenarios. The UIContext is the context of an ArkUI instance, an object created by a window to manage all UIs, which is held and managed by the creating window. 15 16## Substitute APIs 17 18The 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/arkts-apis-uicontext-uicontext.md). 19 20| Global API | Substitute API | Description | 21| :-----------------------------------: | :-----------------------------------: | :------------------------: | 22| @ohos.animator | createAnimator | Custom animation controller. | 23| @ohos.arkui.componentSnapshot | getComponentSnapshot | Component snapshot. | 24| @ohos.arkui.componentUtils | getComponentUtils | Component utility class. | 25| @ohos.arkui.dragController | getDragController | Drag controller. | 26| @ohos.arkui.inspector | getUIInspector | Component layout callback. | 27| @ohos.arkui.observer | getUIObserver | Observer. | 28| @ohos.font | getFont | Custom font registration. | 29| @ohos.measure | getMeasureUtil | Text measurement. | 30| @ohos.mediaquery | getMediaQuery | Media query. | 31| @ohos.promptAction | getPromptAction | Popup. | 32| @ohos.router | getRouter | Page routing. | 33| AlertDialog | showAlertDialog | Alert dialog box. | 34| ActionSheet | showActionSheet | Action sheet. | 35| CalendarPickerDialog | Not supported | Calendar picker dialog box. | 36| DatePickerDialog | showDatePickerDialog | Date picker dialog box. | 37| TimePickerDialog | showTimePickerDialog | Time picker dialog box. | 38| TextPickerDialog | showTextPickerDialog | Text picker dialog box. | 39| ContextMenu | getContextMenuController | Menu control. | 40| vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx | vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx | Pixel unit conversion. | 41| focusControl | getFocusControl | Focus control. | 42| cursorControl | getCursorControl | Cursor control. | 43| getContext | getHostContext | Obtains the context of the current ability.| 44| LocalStorage.getShared | getSharedLocalStorage | Obtains the storage passed by the current ability. | 45| animateTo | animateTo | Explicit animation. | 46| animateToImmediately | Not supported | Explicit instant animation. | 47 48## How to Switch to Substitute APIs 49 50In 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. 51 52<!--deprecated_code_no_check--> 53```ts 54import { promptAction } from '@kit.ArkUI' 55 56@Entry 57@Component 58struct Index { 59 build() { 60 Row() { 61 Button() 62 .onClick(() => { 63 promptAction.showToast({ 64 message: 'Message Info', 65 duration: 2000 66 }); 67 }) 68 } 69 } 70} 71``` 72In 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. 73 74<!--deprecated_code_no_check--> 75```ts 76import { promptAction } from '@kit.ArkUI' 77// xxx.so is not system provided. You must provide it. 78import bridge from xxx.so 79 80@Entry 81@Component 82struct Index { 83 build() { 84 Row() { 85 Button() 86 .onClick(() => { 87 bridge.callNative("xxxx", ()=> { 88 promptAction.showToast({ 89 message: 'Message Info', 90 duration: 2000 91 }); 92 }) 93 }) 94 } 95 } 96} 97``` 98 99To 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/arkts-apis-uicontext-uicontext.md) to obtain objects bound to the instance. This way, the toast is bound to a specific instance. 100```ts 101// xxx.so is not system provided. You must provide it. 102import bridge from xxx.so 103 104@Entry 105@Component 106struct Index { 107 build() { 108 Row() { 109 Button() 110 .onClick(() => { 111 let uiContext = this.getUIContext(); 112 let prompt = uiContext.getPromptAction(); 113 bridge.callNative("xxxx", ()=> { 114 prompt.showToast({ 115 message: 'Message Info', 116 duration: 2000 117 }); 118 }) 119 }) 120 } 121 } 122} 123``` 124 125If you are using APIs in [UIContext](../reference/apis-arkui/arkts-apis-uicontext-uicontext.md) 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. 126 127| API in UIContext| Description | 128| ------------- | -------------------- | 129| runScopedTask | Executes the closure of the bound instance.| 130 131The above example can also be implemented using the following method. 132 133<!--deprecated_code_no_check--> 134```ts 135// Execute the closure of the bound instance. 136import { promptAction } from '@kit.ArkUI' 137 138@Entry 139@Component 140struct Index { 141 build() { 142 Row() { 143 Button() 144 .onClick(() => { 145 let uiContext = this.getUIContext(); 146 uiContext.runScopedTask(() => { 147 promptAction.showToast({ 148 message: 'Message Info', 149 duration: 2000 150 }); 151 }) 152 }) 153 } 154 } 155} 156``` 157
