# @ohos.arkui.UIContext (UIContext)
In the stage model, a window stage or window can use the [loadContent](./js-apis-window.md#loadcontent9) API to load pages, create a UI instance, and render page content to the associated window. Naturally, UI instances and windows are associated on a one-by-one basis. Some global UI APIs are executed in the context of certain UI instances. When calling these APIs, you must identify the UI context, and consequently UI instance, by tracing the call chain. If these APIs are called on a non-UI page or in some asynchronous callback, the current UI context may fail to be identified, resulting in API execution errors.
**@ohos.window** adds the [getUIContext](./js-apis-window.md#getuicontext10) API in API version 10 for obtaining the **UIContext** object of a UI instance. The API provided by the **UIContext** object can be directly applied to the corresponding UI instance.
> **NOTE**
>
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> You can preview how this component looks on a real device, but not in DevEco Studio Previewer.
## UIContext
In the following API examples, you must first use [getUIContext()](./js-apis-window.md#getuicontext10) in **@ohos.window** to obtain a **UIContext** instance, and then call the APIs using the obtained instance. Alternatively, you can obtain a **UIContext** instance through the built-in method [getUIContext()](../arkui-ts/ts-custom-component-api.md#getuicontext) of the custom component. In this document, the **UIContext** instance is represented by **uiContext**.
### getFont
getFont(): Font
Obtains a **Font** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ------------- | ----------- |
| [Font](#font) | **Font** object.|
**Example**
```ts
uiContext.getFont();
```
### getComponentUtils
getComponentUtils(): ComponentUtils
Obtains the **ComponentUtils** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| --------------------------------- | --------------------- |
| [ComponentUtils](#componentutils) | **ComponentUtils** object.|
**Example**
```ts
uiContext.getComponentUtils();
```
### getUIInspector
getUIInspector(): UIInspector
Obtains the **UIInspector** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| --------------------------- | ------------------ |
| [UIInspector](#uiinspector) | **UIInspector** object.|
**Example**
```ts
uiContext.getUIInspector();
```
### getUIObserver11+
getUIObserver(): UIObserver
Obtains the **UIObserver** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| --------------------------- | ------------------ |
| [UIObserver](#uiobserver11) | **UIObserver** object.|
**Example**
```ts
uiContext.getUIObserver();
```
### getMediaQuery
getMediaQuery(): MediaQuery
Obtains a **MediaQuery** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ------------------------- | ----------------- |
| [MediaQuery](#mediaquery) | **MediaQuery** object.|
**Example**
```ts
uiContext.getMediaQuery();
```
### getRouter
getRouter(): Router
Obtains a **Router** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ----------------- | ------------- |
| [Router](#router) | **Router** object.|
**Example**
```ts
uiContext.getRouter();
```
### getPromptAction
getPromptAction(): PromptAction
Obtains a **PromptAction** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ----------------------------- | ------------------- |
| [PromptAction](#promptaction) | **PromptAction** object.|
**Example**
```ts
uiContext.getPromptAction();
```
### animateTo
animateTo(value: AnimateParam, event: () => void): void
Applies a transition animation for state changes.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ---------------------------------------- | ---- | ------------------------------------- |
| value | [AnimateParam](../arkui-ts/ts-explicit-animation.md#animateparam) | Yes | Animation settings. |
| event | () => void | Yes | Closure function that displays the dynamic effect. The system automatically inserts the transition animation if the state changes in the closure function.|
**Example**
```ts
// xxx.ets
@Entry
@Component
struct AnimateToExample {
@State widthSize: number = 250
@State heightSize: number = 100
@State rotateAngle: number = 0
private flag: boolean = true
build() {
Column() {
Button('change size')
.width(this.widthSize)
.height(this.heightSize)
.margin(30)
.onClick(() => {
if (this.flag) {
uiContext.animateTo({
duration: 2000,
curve: Curve.EaseOut,
iterations: 3,
playMode: PlayMode.Normal,
onFinish: () => {
console.info('play end')
}
}, () => {
this.widthSize = 150
this.heightSize = 60
})
} else {
uiContext.animateTo({}, () => {
this.widthSize = 250
this.heightSize = 100
})
}
this.flag = !this.flag
})
Button('change rotate angle')
.margin(50)
.rotate({ x: 0, y: 0, z: 1, angle: this.rotateAngle })
.onClick(() => {
uiContext.animateTo({
duration: 1200,
curve: Curve.Friction,
delay: 500,
iterations: -1, // The value -1 indicates that the animation is played for an unlimited number of times.
playMode: PlayMode.Alternate,
onFinish: () => {
console.info('play end')
}
}, () => {
this.rotateAngle = 90
})
})
}.width('100%').margin({ top: 5 })
}
}
```
### showAlertDialog
showAlertDialog(options: AlertDialogParamWithConfirm | AlertDialogParamWithButtons | AlertDialogParamWithOptions): void
Shows an alert dialog box.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ------------------- |
| options | [AlertDialogParamWithConfirm](../arkui-ts/ts-methods-alert-dialog-box.md#alertdialogparamwithconfirm) \| [AlertDialogParamWithButtons](../arkui-ts/ts-methods-alert-dialog-box.md#alertdialogparamwithbuttons) \| [AlertDialogParamWithOptions](../arkui-ts/ts-methods-alert-dialog-box.md#alertdialogparamwithoptions10) | Yes | Parameters of the **\** component.|
**Example**
```ts
uiContext.showAlertDialog(
{
title: 'title',
message: 'text',
autoCancel: true,
alignment: DialogAlignment.Bottom,
offset: { dx: 0, dy: -20 },
gridCount: 3,
confirm: {
value: 'button',
action: () => {
console.info('Button-clicking callback')
}
},
cancel: () => {
console.info('Closed callbacks')
}
}
)
```
### showActionSheet
showActionSheet(value: ActionSheetOptions): void
Shows an action sheet in the given settings.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------------------------------------ | ---- | -------------------- |
| value | [ActionSheetOptions](../arkui-ts/ts-methods-action-sheet.md#actionsheetoptions) | Yes | Parameters of the action sheet.|
**Example**
```ts
uiContext.showActionSheet({
title: 'ActionSheet title',
message: 'message',
autoCancel: true,
confirm: {
value: 'Confirm button',
action: () => {
console.log('Get Alert Dialog handled')
}
},
cancel: () => {
console.log('actionSheet canceled')
},
alignment: DialogAlignment.Bottom,
offset: { dx: 0, dy: -10 },
sheets: [
{
title: 'apples',
action: () => {
console.log('apples')
}
},
{
title: 'bananas',
action: () => {
console.log('bananas')
}
},
{
title: 'pears',
action: () => {
console.log('pears')
}
}
]
})
```
### showDatePickerDialog
showDatePickerDialog(options: DatePickerDialogOptions): void
Shows a date picker dialog box in the given settings.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------------------------------ | ---- | ------------------------------ |
| options | [DatePickerDialogOptions](../arkui-ts/ts-methods-datepicker-dialog.md#datepickerdialogoptions) | Yes | Parameters of the date picker dialog box.|
**Example**
```ts
let selectedDate: Date = new Date("2010-1-1")
uiContext.showDatePickerDialog({
start: new Date("2000-1-1"),
end: new Date("2100-12-31"),
selected: selectedDate,
onAccept: (value: DatePickerResult) => {
// Use the setFullYear method to set the date when the OK button is touched. In this way, when the date picker dialog box is displayed again, the selected date is the date last confirmed.
selectedDate.setFullYear(Number(value.year), Number(value.month), Number(value.day))
console.info("DatePickerDialog:onAccept()" + JSON.stringify(value))
},
onCancel: () => {
console.info("DatePickerDialog:onCancel()")
},
onChange: (value: DatePickerResult) => {
console.info("DatePickerDialog:onChange()" + JSON.stringify(value))
}
})
```
### showTimePickerDialog
showTimePickerDialog(options: TimePickerDialogOptions): void
Shows a time picker dialog box in the given settings.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------------------------------ | ---- | ------------------------------ |
| options | [TimePickerDialogOptions](../arkui-ts/ts-methods-timepicker-dialog.md#timepickerdialogoptions) | Yes | Parameters of the time picker dialog box.|
**Example**
```ts
// xxx.ets
class SelectTime{
selectTime: Date = new Date('2020-12-25T08:30:00')
hours(h:number,m:number){
this.selectTime.setHours(h,m)
}
}
@Entry
@Component
struct TimePickerDialogExample {
@State selectTime: Date = new Date('2023-12-25T08:30:00');
build() {
Column() {
Button('showTimePickerDialog')
.margin(30)
.onClick(() => {
uiContext.showTimePickerDialog({
selected: this.selectTime,
onAccept: (value: TimePickerResult) => {
// Set selectTime to the time when the OK button is clicked. In this way, when the dialog box is displayed again, the selected time is the time when the operation was confirmed last time.
let time = new SelectTime()
if(value.hour&&value.minute){
time.hours(value.hour, value.minute)
}
console.info("TimePickerDialog:onAccept()" + JSON.stringify(value))
},
onCancel: () => {
console.info("TimePickerDialog:onCancel()")
},
onChange: (value: TimePickerResult) => {
console.info("TimePickerDialog:onChange()" + JSON.stringify(value))
}
})
})
}.width('100%').margin({ top: 5 })
}
}
```
### showTextPickerDialog
showTextPickerDialog(options: TextPickerDialogOptions): void
Shows a text picker dialog box in the given settings.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------------------------------ | ---- | ------------------------------ |
| options | [TextPickerDialogOptions](../arkui-ts/ts-methods-textpicker-dialog.md#textpickerdialogoptions) | Yes | Parameters of the text picker dialog box.|
**Example**
```ts
// xxx.ets
class SelectedValue{
select: number = 2
set(val:number){
this.select = val
}
}
class SelectedArray{
select: number[] = []
set(val:number[]){
this.select = val
}
}
@Entry
@Component
struct TextPickerDialogExample {
@State selectTime: Date = new Date('2023-12-25T08:30:00');
private fruits: string[] = ['apple1', 'orange2', 'peach3', 'grape4', 'banana5']
private select : number = 0;
build() {
Column() {
Button('showTextPickerDialog')
.margin(30)
.onClick(() => {
uiContext.showTextPickerDialog({
range: this.fruits,
selected: this.select,
onAccept: (value: TextPickerResult) => {
// Set select to the index of the item selected when the OK button is touched. In this way, when the text picker dialog box is displayed again, the selected item is the one last confirmed.
let selectedVal = new SelectedValue()
let selectedArr = new SelectedArray()
if(value.index){
value.index instanceof Array?selectedArr.set(value.index) : selectedVal.set(value.index)
}
console.info("TextPickerDialog:onAccept()" + JSON.stringify(value))
},
onCancel: () => {
console.info("TextPickerDialog:onCancel()")
},
onChange: (value: TextPickerResult) => {
console.info("TextPickerDialog:onChange()" + JSON.stringify(value))
}
})
})
}.width('100%').margin({ top: 5 })
}
}
```
### createAnimator
createAnimator(options: AnimatorOptions): AnimatorResult
Creates an **Animator** object.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ------- |
| options | [AnimatorOptions](./js-apis-animator.md#animatoroptions) | Yes | Animator options.|
**Return value**
| Type | Description |
| ---------------------------------------- | ------------- |
| [AnimatorResult](./js-apis-animator.md#animatorresult) | Animator result.|
**Example**
```ts
import { AnimatorOptions } from '@ohos.animator';
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
if (err.code) {
hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
return;
}
hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
let uiContext = windowStage.getMainWindowSync().getUIContext();
let options:AnimatorOptions = {
duration: 1500,
easing: "friction",
delay: 0,
fill: "forwards",
direction: "normal",
iterations: 3,
begin: 200.0,
end: 400.0
};
uiContext.createAnimator(options);
});
}
```
### runScopedTask
runScopedTask(callback: () => void): void
Executes the specified callback in this UI context.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------- | ---- | ---- |
| callback | () => void | Yes | Callback used to return the result.|
**Example**
```ts
uiContext.runScopedTask(
() => {
console.log('Succeeded in runScopedTask');
}
);
```
### setKeyboardAvoidMode11+
setKeyboardAvoidMode(value: KeyboardAvoidMode): void
Sets the avoidance mode for the virtual keyboard.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------- | ---- | ---- |
| value | [KeyboardAvoidMode](../apis/js-apis-arkui-UIContext.md#keyboardavoidmode11)| Yes | Avoidance mode for the virtual keyboard.
Default value: **KeyboardAvoidMode.OFFSET**|
**Example**
```ts
import { KeyboardAvoidMode, UIContext } from '@ohos.arkui.UIContext';
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
let uiContext :UIContext = windowStage.getMainWindowSync().getUIContext();
uiContext.setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
if (err.code) {
hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
return;
}
hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
});
}
```
### getKeyboardAvoidMode11+
getKeyboardAvoidMode(): KeyboardAvoidMode
Obtains the avoidance mode for the virtual keyboard.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ---------- | ---- |
| [KeyboardAvoidMode](../apis/js-apis-arkui-UIContext.md#keyboardavoidmode11)| Avoidance mode for the virtual keyboard.|
**Example**
```ts
import { KeyboardAvoidMode, UIContext } from '@ohos.arkui.UIContext';
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
let uiContext :UIContext = windowStage.getMainWindowSync().getUIContext();
let KeyboardAvoidMode = uiContext.getKeyboardAvoidMode();
console.log("KeyboardAvoidMode:", JSON.stringify(KeyboardAvoidMode));
if (err.code) {
hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
return;
}
hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
});
}
```
### getAtomicServiceBar11+
getAtomicServiceBar(): Nullable\
Obtains an **AtomicServiceBar** object, which can be used to set the properties of the atomic service menu bar.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ------------------------------------------------- | ------------------------------------------------------------ |
| Nullable<[AtomicServiceBar](#atomicservicebar11)> | Returns the **AtomicServerBar** type if the service is an atomic service; returns **undefined** type otherwise.|
**Example**
```ts
import {UIContext, AtomicServiceBar} from '@ohos.arkui.UIContext';
import hilog from '@ohos.hilog';
import window from "@ohos.window";
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
let uiContext: UIContext = windowStage.getMainWindowSync().getUIContext();
let atomicServiceBar: Nullable = uiContext.getAtomicServiceBar();
if (atomicServiceBar != undefined) {
hilog.info(0x0000, 'testTag', 'Get AtomServiceBar Successfully.');
} else {
hilog.error(0x0000, 'testTag', 'Get AtomicServiceBar failed.');
}
});
}
```
### getDragController11+
getDragController(): DragController
Obtains the **DragController** object, which can be used to create and initiate dragging.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
|Type|Description|
|----|----|
|[DragController](js-apis-arkui-dragController.md#dragController)| **DragController** object.|
**Example**
```ts
uiContext.getDragController();
```
### getDragPreview11+
getDragPreview(): dragController.DragPreview
Obtains the **DragPreview** object, which represents the preview displayed during a drag.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| [dragController.DragPreview](js-apis-arkui-dragController.md#dragpreview11) | **DragPreview** object. It provides the API for setting the preview style. It does not work in the **OnDrop** and **OnDragEnd** callbacks.|
**Error codes**: For details about universal error codes, see [Universal Error Codes](../errorcodes/errorcode-universal.md).
**Example**
For details, see [animate](js-apis-arkui-dragController.md#animate11).
### keyframeAnimateTo11+
keyframeAnimateTo(param: KeyframeAnimateParam, keyframes: Array<KeyframeState>): void
Generates a key frame animation. For details about how to use this API, see [keyframeAnimateTo](../arkui-ts/ts-keyframeAnimateTo.md).
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name| Type | Mandatory| Description |
| ------------ | ---------------------------------------------------- | ------- | ---------------------------- |
| param | [KeyframeAnimateParam](../arkui-ts/ts-keyframeAnimateTo.md#keyframeanimateparam) | Yes | Overall animation parameter of the keyframe animation. |
| keyframes | Array<[KeyframeState](../arkui-ts/ts-keyframeAnimateTo.md#keyframestate)> | Yes | States of all keyframes. |
## Font
In the following API examples, you must first use [getFont()](#getfont) in **UIContext** to obtain a **Font** instance, and then call the APIs using the obtained instance.
### registerFont
registerFont(options: font.FontOptions): void
Registers a custom font with the font manager.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ----------- |
| options | [font.FontOptions](js-apis-font.md#fontoptions) | Yes | Information about the custom font to register.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
let font:Font = uiContext.getFont();
font.registerFont({
familyName: 'medium',
familySrc: '/font/medium.ttf'
});
```
### getSystemFontList
getSystemFontList(): Array\
Obtains the list of supported fonts.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| -------------- | --------- |
| Array\ | List of supported fonts.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
let font:Font|undefined = uiContext.getFont();
if(font){
font.getSystemFontList()
}
```
### getFontByName
getFontByName(fontName: string): font.FontInfo
Obtains information about a system font based on the font name.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------ | ---- | ------- |
| fontName | string | Yes | System font name.|
**Return value**
| Type | Description |
| ----------------------------------------- | -------------- |
| [font.FontInfo](js-apis-font.md#fontinfo) | Information about the system font.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
let font:Font|undefined = uiContext.getFont();
if(font){
font.getFontByName('Sans Italic')
}
```
## ComponentUtils
In the following API examples, you must first use [getComponentUtils()](#getcomponentutils) in **UIContext** to obtain a **ComponentUtils** instance, and then call the APIs using the obtained instance.
### getRectangleById
getRectangleById(id: string): componentUtils.ComponentInfo
Obtains the size, position, translation, scaling, rotation, and affine matrix information of the specified component.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ---- | ------ | ---- | --------- |
| id | string | Yes | Unique component ID.|
**Return value**
| Type | Description |
| ---------------------------------------- | ------------------------ |
| [ComponentInfo](js-apis-arkui-componentUtils.md#componentinfo) | Size, position, translation, scaling, rotation, and affine matrix information of the component.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
let componentUtils:ComponentUtils = uiContext.getComponentUtils();
let modePosition = componentUtils.getRectangleById("onClick");
let localOffsetWidth = modePosition.size.width;
let localOffsetHeight = modePosition.size.height;
```
## UIInspector
In the following API examples, you must first use [getUIInspector()](#getuiinspector) in **UIContext** to obtain a **UIInspector** instance, and then call the APIs using the obtained instance.
### createComponentObserver
createComponentObserver(id: string): inspector.ComponentObserver
Creates an observer for the specified component.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ---- | ------ | ---- | ------- |
| id | string | Yes | Component ID.|
**Return value**
| Type | Description |
| ------------------------------------------------------------ | -------------------------------------------------- |
| [inspector.ComponentObserver](js-apis-arkui-inspector.md#componentobserver) | Component observer, which is used to register or unregister listeners for completion of component layout or drawing.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
let inspector:UIInspector = uiContext.getUIInspector();
let listener = inspector.createComponentObserver('COMPONENT_ID');
```
## UIObserver11+
In the following API examples, you must first use [getUIObserver()](#getuiobserver11) in **UIContext** to obtain a **UIObserver** instance, and then call the APIs using the obtained instance.
### on('navDestinationUpdate')11+
on(type: 'navDestinationUpdate', callback: Callback\): void
Subscribes to state changes of this **\** component.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'navDestinationUpdate'**, which indicates the state change event of the **\** component.|
| callback | Callback\ | Yes | Callback used to return the current state of the **\** component. |
**Example**
```ts
import { UIObserver } from '@ohos.arkui.UIContext';
let observer:UIObserver = uiContext.getUIObserver();
observer.on('navDestinationUpdate', (info) => {
console.info('NavDestination state update', JSON.stringify(info));
});
```
### off('navDestinationUpdate')11+
off(type: 'navDestinationUpdate', callback?: Callback\): void
Unsubscribes from state changes of this **\** component.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'navDestinationUpdate'**, which indicates the state change event of the **\** component.|
| callback | Callback\ | No | Callback used to return the current state of the **\** component. |
**Example**
```ts
import { UIObserver } from '@ohos.arkui.UIContext';
let observer:UIObserver = uiContext.getUIObserver();
observer.off('navDestinationUpdate');
```
### on('navDestinationUpdate')11+
on(type: 'navDestinationUpdate', options: { navigationId: ResourceStr }, callback: Callback\): void
Subscribes to state changes of this **\** component.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'navDestinationUpdate'**, which indicates the state change event of the **\** component.|
| options | { navigationId: [ResourceStr](../arkui-ts/ts-types.md#resourcestr) } | Yes | ID of the target **\** component. |
| callback | Callback\ | Yes | Callback used to return the current state of the **\** component. |
**Example**
```ts
import { UIObserver } from '@ohos.arkui.UIContext';
let observer:UIObserver = uiContext.getUIObserver();
observer.on('navDestinationUpdate', { navigationId: "testId" }, (info) => {
console.info('NavDestination state update', JSON.stringify(info));
});
```
### off('navDestinationUpdate')11+
off(type: 'navDestinationUpdate', options: { navigationId: ResourceStr }, callback?: Callback\): void
Unsubscribes from state changes of this **\** component.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'navDestinationUpdate'**, which indicates the state change event of the **\** component.|
| options | { navigationId: [ResourceStr](../arkui-ts/ts-types.md#resourcestr) } | Yes | ID of the target **\** component. |
| callback | Callback\ | No | Callback used to return the current state of the **\** component. |
**Example**
```ts
import { UIObserver } from '@ohos.arkui.UIContext';
let observer:UIObserver = uiContext.getUIObserver();
observer.off('navDestinationUpdate', { navigationId: "testId" });
```
### on('routerPageUpdate')11+
on(type: 'routerPageUpdate', callback: Callback\): void
Subscribes to state changes of the page in the router.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'routerPageUpdate'**, which indicates the state change event of the page in the router.|
| callback | Callback\ | Yes | Callback used to return the If **pageInfo** is passed, the current page state is returned. |
**Example**
```ts
import { UIObserver } from '@ohos.arkui.UIContext';
let observer:UIObserver = uiContext.getUIObserver();
observer.on('routerPageUpdate', (info) => {
console.info('RouterPage state updated, called by ' + `${info.name}`);
});
```
### off('routerPageUpdate')11+
off(type: 'routerPageUpdate', callback?: Callback\): void
Unsubscribes to state changes of the page in the router.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The value is fixed at **'routerPageUpdate'**, which indicates the state change event of the page in the router.|
| callback | Callback\ | No | Callback to be unregistered. |
**Example**
```ts
import { UIObserver } from '@ohos.arkui.UIContext';
let observer:UIObserver = uiContext.getUIObserver();
// callBackFunc is defined and used before
observer.off('routerPageUpdate', callBackFunc);
```
## MediaQuery
In the following API examples, you must first use [getMediaQuery()](#getmediaquery) in **UIContext** to obtain a **MediaQuery** instance, and then call the APIs using the obtained instance.
### matchMediaSync
matchMediaSync(condition: string): mediaQuery.MediaQueryListener
Sets the media query criteria and returns the corresponding listening handle.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| --------- | ------ | ---- | ---------------------------------------- |
| condition | string | Yes | Media query condition. For details, see [Syntax](../../ui/arkts-layout-development-media-query.md#syntax).|
**Return value**
| Type | Description |
| ------------------------------------------------------------ | -------------------------------------------- |
| [mediaQuery.MediaQueryListener](js-apis-mediaquery.md#mediaquerylistener) | Listening handle to a media event, which is used to register or unregister the listening callback.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
let mediaquery: MediaQuery = uiContext.getMediaQuery();
let listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.
```
## Router
In the following API examples, you must first use [getRouter()](#getrouter) in **UIContext** to obtain a **Router** instance, and then call the APIs using the obtained instance.
### pushUrl
pushUrl(options: router.RouterOptions): Promise<void>
Navigates to a specified page in the application. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | --------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | Yes | Page routing parameters.|
**Return value**
| Type | Description |
| ------------------- | ------- |
| Promise<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
| 100002 | if the uri is not exist. |
| 100003 | if the pages are pushed too much. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router:Router = uiContext.getRouter();
try {
router.pushUrl({
url: 'pages/routerpage2',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
})
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`pushUrl failed, code is ${code}, message is ${message}`);
}
```
### pushUrl
pushUrl(options: router.RouterOptions, callback: AsyncCallback<void>): void
Navigates to a specified page in the application.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | Yes | Page routing parameters.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
| 100002 | if the uri is not exist. |
| 100003 | if the pages are pushed too much. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router:Router = uiContext.getRouter();
router.pushUrl({
url: 'pages/routerpage2',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
}, (err: Error) => {
if (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`pushUrl failed, code is ${code}, message is ${message}`);
return;
}
console.info('pushUrl success');
})
```
### pushUrl
pushUrl(options: router.RouterOptions, mode: router.RouterMode): Promise<void>
Navigates to a specified page in the application. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ---------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | Yes | Page routing parameters. |
| mode | [router.RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.|
**Return value**
| Type | Description |
| ------------------- | ------- |
| Promise<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
| 100002 | if the uri is not exist. |
| 100003 | if the pages are pushed too much. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
let routerF:Router = uiContext.getRouter();
class RouterTmp{
Standard:router.RouterMode = router.RouterMode.Standard
}
let rtm:RouterTmp = new RouterTmp()
try {
routerF.pushUrl({
url: 'pages/routerpage2',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
}, rtm.Standard)
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`pushUrl failed, code is ${code}, message is ${message}`);
}
```
### pushUrl
pushUrl(options: router.RouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void
Navigates to a specified page in the application.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ---------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | Yes | Page routing parameters. |
| mode | [router.RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
| 100002 | if the uri is not exist. |
| 100003 | if the pages are pushed too much. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
let routerF:Router = uiContext.getRouter();
class RouterTmp{
Standard:router.RouterMode = router.RouterMode.Standard
}
let rtm:RouterTmp = new RouterTmp()
routerF.pushUrl({
url: 'pages/routerpage2',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
}, rtm.Standard, (err) => {
if (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`pushUrl failed, code is ${code}, message is ${message}`);
return;
}
console.info('pushUrl success');
})
```
### replaceUrl
replaceUrl(options: router.RouterOptions): Promise<void>
Replaces the current page with another one in the application and destroys the current page. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | --------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | Yes | Description of the new page.|
**Return value**
| Type | Description |
| ------------------- | ------- |
| Promise<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------------- |
| 100001 | if UI execution context not found, only throw in standard system. |
| 200002 | if the uri is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router:Router = uiContext.getRouter();
try {
router.replaceUrl({
url: 'pages/detail',
params: {
data1: 'message'
}
})
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`replaceUrl failed, code is ${code}, message is ${message}`);
}
```
### replaceUrl
replaceUrl(options: router.RouterOptions, callback: AsyncCallback<void>): void
Replaces the current page with another one in the application and destroys the current page.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | Yes | Description of the new page.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------------- |
| 100001 | if UI execution context not found, only throw in standard system. |
| 200002 | if the uri is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router:Router = uiContext.getRouter();
router.replaceUrl({
url: 'pages/detail',
params: {
data1: 'message'
}
}, (err: Error) => {
if (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`replaceUrl failed, code is ${code}, message is ${message}`);
return;
}
console.info('replaceUrl success');
})
```
### replaceUrl
replaceUrl(options: router.RouterOptions, mode: router.RouterMode): Promise<void>
Replaces the current page with another one in the application and destroys the current page. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ---------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | Yes | Description of the new page. |
| mode | [router.RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.|
**Return value**
| Type | Description |
| ------------------- | ------- |
| Promise<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------------- |
| 100001 | if can not get the delegate, only throw in standard system. |
| 200002 | if the uri is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
let routerF:Router = uiContext.getRouter();
class RouterTmp{
Standard:router.RouterMode = router.RouterMode.Standard
}
let rtm:RouterTmp = new RouterTmp()
try {
routerF.replaceUrl({
url: 'pages/detail',
params: {
data1: 'message'
}
}, rtm.Standard)
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`replaceUrl failed, code is ${code}, message is ${message}`);
}
```
### replaceUrl
replaceUrl(options: router.RouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void
Replaces the current page with another one in the application and destroys the current page.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ---------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | Yes | Description of the new page. |
| mode | [router.RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------------- |
| 100001 | if UI execution context not found, only throw in standard system. |
| 200002 | if the uri is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
let routerF:Router = uiContext.getRouter();
class RouterTmp{
Standard:router.RouterMode = router.RouterMode.Standard
}
let rtm:RouterTmp = new RouterTmp()
routerF.replaceUrl({
url: 'pages/detail',
params: {
data1: 'message'
}
}, rtm.Standard, (err: Error) => {
if (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`replaceUrl failed, code is ${code}, message is ${message}`);
return;
}
console.info('replaceUrl success');
});
```
### pushNamedRoute
pushNamedRoute(options: router.NamedRouterOptions): Promise<void>
Navigates to a page using the named route. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | --------- |
| options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Page routing parameters.|
**Return value**
| Type | Description |
| ------------------- | ------- |
| Promise<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
| 100003 | if the pages are pushed too much. |
| 100004 | if the named route is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router:Router = uiContext.getRouter();
try {
router.pushNamedRoute({
name: 'myPage',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
})
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`pushNamedRoute failed, code is ${code}, message is ${message}`);
}
```
### pushNamedRoute
pushNamedRoute(options: router.NamedRouterOptions, callback: AsyncCallback<void>): void
Navigates to a page using the named route. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------- |
| options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Page routing parameters.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
| 100003 | if the pages are pushed too much. |
| 100004 | if the named route is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router:Router = uiContext.getRouter();
router.pushNamedRoute({
name: 'myPage',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
}, (err: Error) => {
if (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`pushNamedRoute failed, code is ${code}, message is ${message}`);
return;
}
console.info('pushNamedRoute success');
})
```
### pushNamedRoute
pushNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode): Promise<void>
Navigates to a page using the named route. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ---------- |
| options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Page routing parameters. |
| mode | [router.RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.|
**Return value**
| Type | Description |
| ------------------- | ------- |
| Promise<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
| 100003 | if the pages are pushed too much. |
| 100004 | if the named route is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
let routerF:Router = uiContext.getRouter();
class RouterTmp{
Standard:router.RouterMode = router.RouterMode.Standard
}
let rtm:RouterTmp = new RouterTmp()
try {
routerF.pushNamedRoute({
name: 'myPage',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
}, rtm.Standard)
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`pushNamedRoute failed, code is ${code}, message is ${message}`);
}
```
### pushNamedRoute
pushNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void
Navigates to a page using the named route. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ---------- |
| options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Page routing parameters. |
| mode | [router.RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
| 100003 | if the pages are pushed too much. |
| 100004 | if the named route is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
let routerF:Router = uiContext.getRouter();
class RouterTmp{
Standard:router.RouterMode = router.RouterMode.Standard
}
let rtm:RouterTmp = new RouterTmp()
routerF.pushNamedRoute({
name: 'myPage',
params: {
data1: 'message',
data2: {
data3: [123, 456, 789]
}
}
}, rtm.Standard, (err: Error) => {
if (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`pushNamedRoute failed, code is ${code}, message is ${message}`);
return;
}
console.info('pushNamedRoute success');
})
```
### replaceNamedRoute
replaceNamedRoute(options: router.NamedRouterOptions): Promise<void>
Replaces the current page with another one using the named route and destroys the current page. This API uses a promise to return an error.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | --------- |
| options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Description of the new page.|
**Return value**
| Type | Description |
| ------------------- | ------- |
| Promise<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------------- |
| 100001 | if UI execution context not found, only throw in standard system. |
| 100004 | if the named route is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router:Router = uiContext.getRouter();
try {
router.replaceNamedRoute({
name: 'myPage',
params: {
data1: 'message'
}
})
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`replaceNamedRoute failed, code is ${code}, message is ${message}`);
}
```
### replaceNamedRoute
replaceNamedRoute(options: router.NamedRouterOptions, callback: AsyncCallback<void>): void
Replaces the current page with another one using the named route and destroys the current page. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------- |
| options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Description of the new page.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------------- |
| 100001 | if UI execution context not found, only throw in standard system. |
| 100004 | if the named route is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router:Router = uiContext.getRouter();
router.replaceNamedRoute({
name: 'myPage',
params: {
data1: 'message'
}
}, (err: Error) => {
if (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`replaceNamedRoute failed, code is ${code}, message is ${message}`);
return;
}
console.info('replaceNamedRoute success');
})
```
### replaceNamedRoute
replaceNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode): Promise<void>
Replaces the current page with another one using the named route and destroys the current page. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ---------- |
| options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Description of the new page. |
| mode | [router.RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.|
**Return value**
| Type | Description |
| ------------------- | ------- |
| Promise<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------------- |
| 100001 | if can not get the delegate, only throw in standard system. |
| 100004 | if the named route is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
let routerF:Router = uiContext.getRouter();
class RouterTmp{
Standard:router.RouterMode = router.RouterMode.Standard
}
let rtm:RouterTmp = new RouterTmp()
try {
routerF.replaceNamedRoute({
name: 'myPage',
params: {
data1: 'message'
}
}, rtm.Standard)
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`replaceNamedRoute failed, code is ${code}, message is ${message}`);
}
```
### replaceNamedRoute
replaceNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void
Replaces the current page with another one using the named route and destroys the current page. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ---------- |
| options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | Yes | Description of the new page. |
| mode | [router.RouterMode](js-apis-router.md#routermode9) | Yes | Routing mode.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------------- |
| 100001 | if UI execution context not found, only throw in standard system. |
| 100004 | if the named route is not exist. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
import router from '@ohos.router';
let routerF:Router = uiContext.getRouter();
class RouterTmp{
Standard:router.RouterMode = router.RouterMode.Standard
}
let rtm:RouterTmp = new RouterTmp()
routerF.replaceNamedRoute({
name: 'myPage',
params: {
data1: 'message'
}
}, rtm.Standard, (err: Error) => {
if (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`replaceNamedRoute failed, code is ${code}, message is ${message}`);
return;
}
console.info('replaceNamedRoute success');
});
```
### back
back(options?: router.RouterOptions ): void
Returns to the previous page or a specified page.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ---------------------------------------- |
| options | [router.RouterOptions](js-apis-router.md#routeroptions) | No | Description of the page. The **url** parameter indicates the URL of the page to return to. If the specified page does not exist in the page stack, the application does not respond. If no URL is set, the application returns to the previous page, and the page is not rebuilt. The page in the page stack is not reclaimed. It will be reclaimed after being popped up.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router: Router = uiContext.getRouter();
router.back({url:'pages/detail'});
```
### clear
clear(): void
Clears all historical pages in the stack and retains only the current page at the top of the stack.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router: Router = uiContext.getRouter();
router.clear();
```
### getLength
getLength(): string
Obtains the number of pages in the current stack.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ------ | ------------------ |
| string | Number of pages in the stack. The maximum value is **32**.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router: Router = uiContext.getRouter();
let size = router.getLength();
console.log('pages stack size = ' + size);
```
### getState
getState(): router.RouterState
Obtains state information about the current page.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ---------------------------------------- | ------- |
| [RouterState](js-apis-router.md#routerstate) | Page routing state.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router: Router = uiContext.getRouter();
let page = router.getState();
console.log('current index = ' + page.index);
console.log('current name = ' + page.name);
console.log('current path = ' + page.path);
```
### showAlertBeforeBackPage
showAlertBeforeBackPage(options: router.EnableAlertOptions): void
Enables the display of a confirm dialog box before returning to the previous page.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | --------- |
| options | [router.EnableAlertOptions](js-apis-router.md#enablealertoptions) | Yes | Description of the dialog box.|
**Error codes**
For details about the error codes, see [Router Error Codes](../errorcodes/errorcode-router.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router: Router = uiContext.getRouter();
try {
router.showAlertBeforeBackPage({
message: 'Message Info'
});
} catch(error) {
let message = (error as BusinessError).message;
let code = (error as BusinessError).code;
console.error(`showAlertBeforeBackPage failed, code is ${code}, message is ${message}`);
}
```
### hideAlertBeforeBackPage
hideAlertBeforeBackPage(): void
Disables the display of a confirm dialog box before returning to the previous page.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router: Router = uiContext.getRouter();
router.hideAlertBeforeBackPage();
```
### getParams
getParams(): Object
Obtains the parameters passed from the page that initiates redirection to the current page.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Return value**
| Type | Description |
| ------ | ----------------- |
| object | Parameters passed from the page that initiates redirection to the current page.|
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let router: Router = uiContext.getRouter();
router.getParams();
```
## PromptAction
In the following API examples, you must first use [getPromptAction()](#getpromptaction) in **UIContext** to obtain a **PromptAction** instance, and then call the APIs using the obtained instance.
### showToast
showToast(options: promptAction.ShowToastOptions): void
Shows a toast in the given settings.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ------- |
| options | [promptAction.ShowToastOptions](js-apis-promptAction.md#showtoastoptions) | Yes | Toast options.|
**Error codes**
For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let promptAction: PromptAction = uiContext.getPromptAction();
try {
promptAction.showToast({
message: 'Message Info',
duration: 2000
});
} catch (error) {
let message = (error as BusinessError).message;
let code = (error as BusinessError).code;
console.error(`showToast args error code is ${code}, message is ${message}`);
};
```
### showDialog
showDialog(options: promptAction.ShowDialogOptions, callback: AsyncCallback<promptAction.ShowDialogSuccessResponse>): void
Shows a dialog box in the given settings. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ------------ |
| options | [promptAction.ShowDialogOptions](js-apis-promptAction.md#showdialogoptions) | Yes | Dialog box options.|
| callback | AsyncCallback<[promptAction.ShowDialogSuccessResponse](js-apis-promptAction.md#showdialogsuccessresponse)> | Yes | Callback used to return the dialog box response result. |
**Error codes**
For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
class ButtonsModel {
text: string = ""
color: string = ""
}
let promptAction: PromptAction = uiContext.getPromptAction();
try {
promptAction.showDialog({
title: 'showDialog Title Info',
message: 'Message Info',
buttons: [
{
text: 'button1',
color: '#000000'
} as ButtonsModel,
{
text: 'button2',
color: '#000000'
} as ButtonsModel
]
}, (err, data) => {
if (err) {
console.info('showDialog err: ' + err);
return;
}
console.info('showDialog success callback, click button: ' + data.index);
});
} catch (error) {
let message = (error as BusinessError).message;
let code = (error as BusinessError).code;
console.error(`showDialog args error code is ${code}, message is ${message}`);
};
```
### showDialog
showDialog(options: promptAction.ShowDialogOptions): Promise<promptAction.ShowDialogSuccessResponse>
Shows a dialog box. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ------ |
| options | [promptAction.ShowDialogOptions](js-apis-promptAction.md#showdialogoptions) | Yes | Dialog box options.|
**Return value**
| Type | Description |
| ---------------------------------------- | -------- |
| Promise<[promptAction.ShowDialogSuccessResponse](js-apis-promptAction.md#showdialogsuccessresponse)> | Promise used to return the dialog box response result.|
**Error codes**
For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let promptAction: PromptAction = uiContext.getPromptAction();
try {
promptAction.showDialog({
title: 'Title Info',
message: 'Message Info',
buttons: [
{
text: 'button1',
color: '#000000'
},
{
text: 'button2',
color: '#000000'
}
],
})
.then(data => {
console.info('showDialog success, click button: ' + data.index);
})
.catch((err:Error) => {
console.info('showDialog error: ' + err);
})
} catch (error) {
let message = (error as BusinessError).message;
let code = (error as BusinessError).code;
console.error(`showDialog args error code is ${code}, message is ${message}`);
};
```
### showActionMenu11+
showActionMenu(options: promptAction.ActionMenuOptions, callback: AsyncCallback<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)>):void
Shows an action menu in the given settings. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------ |
| options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | Yes | Action menu options. |
| callback | AsyncCallback<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)> | Yes | Callback used to return the action menu response result.|
**Error codes**
For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
| ID| Error Message |
| -------- | ---------------------------------- |
| 100001 | if UI execution context not found. |
**Example**
```ts
import { PromptAction } from '@ohos.arkui.UIContext';
import promptAction from '@ohos.promptAction';
import { BusinessError } from '@ohos.base';
let promptActionF: PromptAction = uiContext.getPromptAction();
try {
promptActionF.showActionMenu({
title: 'Title Info',
buttons: [
{
text: 'item1',
color: '#666666'
},
{
text: 'item2',
color: '#000000'
}
]
}, (err:BusinessError, data:promptAction.ActionMenuSuccessResponse) => {
if (err) {
console.info('showDialog err: ' + err);
return;
}
console.info('showDialog success callback, click button: ' + data.index);
});
} catch (error) {
let message = (error as BusinessError).message;
let code = (error as BusinessError).code;
console.error(`showActionMenu args error code is ${code}, message is ${message}`);
};
```
### showActionMenu(deprecated)
showActionMenu(options: promptAction.ActionMenuOptions, callback: [promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)):void
Shows an action menu in the given settings. This API uses an asynchronous callback to return the result.
his API is deprecated since API version 11. You are advised to use [showActionMenu](#showactionmenu11) instead.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------ |
| options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | Yes | Action menu options. |
| callback | [promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse) | Yes | Callback used to return the action menu response result.|
**Error codes**
For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
**Example**
```ts
import { PromptAction } from '@ohos.arkui.UIContext';
import promptAction from '@ohos.promptAction';
import { BusinessError } from '@ohos.base';
let promptActionF: PromptAction = uiContext.getPromptAction();
try {
promptActionF.showActionMenu({
title: 'Title Info',
buttons: [
{
text: 'item1',
color: '#666666'
},
{
text: 'item2',
color: '#000000'
}
]
}, { index:0 });
} catch (error) {
let message = (error as BusinessError).message;
let code = (error as BusinessError).code;
console.error(`showActionMenu args error code is ${code}, message is ${message}`);
};
```
### showActionMenu
showActionMenu(options: promptAction.ActionMenuOptions): Promise<promptAction.ActionMenuSuccessResponse>
Shows an action menu. This API uses a promise to return the result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ---------------------------------------- | ---- | ------- |
| options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | Yes | Action menu options.|
**Return value**
| Type | Description |
| ---------------------------------------- | ------- |
| Promise<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)> | Promise used to return the action menu response result.|
**Error codes**
For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
| ID | Error Message |
| ------ | ---------------------------------- |
| 100001 | if UI execution context not found. |
**Example**
```ts
import { ComponentUtils, Font, PromptAction, Router, UIInspector, MediaQuery } from '@ohos.arkui.UIContext';
import { BusinessError } from '@ohos.base';
let promptAction: PromptAction = uiContext.getPromptAction();
try {
promptAction.showActionMenu({
title: 'showActionMenu Title Info',
buttons: [
{
text: 'item1',
color: '#666666'
},
{
text: 'item2',
color: '#000000'
},
]
})
.then(data => {
console.info('showActionMenu success, click button: ' + data.index);
})
.catch((err:Error) => {
console.info('showActionMenu error: ' + err);
})
} catch (error) {
let message = (error as BusinessError).message;
let code = (error as BusinessError).code;
console.error(`showActionMenu args error code is ${code}, message is ${message}`);
};
```
## DragController11+
In the following API examples, you must first use [getDragController()](./js-apis-arkui-UIContext.md#getdragcontroller11) in **UIContext** to obtain a **UIContext** instance, and then call the APIs using the obtained instance.
### executeDrag
executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: dragController.DragInfo, callback: AsyncCallback< {event: DragEvent, extraParams: string}>): void
Executes dragging, by passing in the object to be dragged and the dragging information. This API uses a callback to return the drag event result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------- |
| custom | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes | Object to be dragged.
**NOTE**
The global builder is not supported. If the [\](../arkui-ts/ts-basic-components-image.md) component is used in the builder, enable synchronous loading, that is, set the [syncLoad](../arkui-ts/ts-basic-components-image.md#attributes) attribute of the component to **true**.|
| dragInfo | [dragController.DragInfo](js-apis-arkui-dragController.md#draginfo) | Yes | Dragging information. |
| callback | [AsyncCallback](./js-apis-base.md#asynccallback)<{event: [DragEvent](../arkui-ts/ts-universal-events-drag-drop.md#dragevent), extraParams: string}> | Yes | Callback used to return the result.
- **event**: drag event information that includes only the drag result.
- **extraParams**: extra information about the drag event. |
**Error codes**
| ID| Error Message |
| -------- | ------------- |
| 100001 | if some internal handling failed. |
**Example**
```ts
import dragController from "@ohos.arkui.dragController"
import UDC from '@ohos.data.unifiedDataChannel';
@Entry
@Component
struct DragControllerPage {
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Button('touch to execute drag')
.onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
let text = new UDC.Text()
let unifiedData = new UDC.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
class tmp{
event:DragEvent|undefined = undefined
extraParams:string = ''
}
let eve:tmp = new tmp()
dragController.executeDrag(()=>{this.DraggingBuilder()}, dragInfo, (err, eve) => {
if(eve.event){
if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
// ...
} else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
// ...
}
}
})
}
}
})
}
}
}
```
### executeDrag
executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: dragController.DragInfo): Promise<{event: DragEvent, extraParams: string}>
Executes dragging, by passing in the object to be dragged and the dragging information. This API uses a promise to return the drag event result.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------- |
| custom | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes | Object to be dragged.|
| dragInfo | [dragController.DragInfo](js-apis-arkui-dragController.md#draginfo) | Yes | Dragging information. |
**Return value**
| Type | Description |
| ------------------------------------------------------ | ------------------ |
| Promise<{event: [DragEvent](../arkui-ts/ts-universal-events-drag-drop.md#dragevent), extraParams: string}> | Promise used to return the result.
- **event**: drag event information that includes only the drag result.
- **extraParams**: extra information about the drag event.|
**Error codes**
| ID| Error Message |
| -------- | ------------- |
| 100001 | if some internal handling failed. |
**Example**
```ts
import dragController from "@ohos.arkui.dragController"
import componentSnapshot from '@ohos.arkui.componentSnapshot';
import image from '@ohos.multimedia.image';
import UDC from '@ohos.data.unifiedDataChannel';
@Entry
@Component
struct DragControllerPage {
@State pixmap: image.PixelMap|null = null
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
@Builder PixmapBuilder() {
Column() {
Text("PixmapBuilder")
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Button('touch to execute drag')
.onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
let text = new UDC.Text()
let unifiedData = new UDC.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
let pb:CustomBuilder = ():void=>{this.PixmapBuilder()}
componentSnapshot.createFromBuilder(pb).then((pix: image.PixelMap) => {
this.pixmap = pix;
let dragItemInfo: DragItemInfo = {
pixelMap: this.pixmap,
builder: ()=>{this.DraggingBuilder()},
extraInfo: "DragItemInfoTest"
}
class tmp{
event:DragResult|undefined = undefined
extraParams:string = ''
}
let eve:tmp = new tmp()
dragController.executeDrag(dragItemInfo, dragInfo)
.then((eve) => {
if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
// ...
} else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
// ...
}
})
.catch((err:Error) => {
})
})
}
}
})
}
.width('100%')
.height('100%')
}
}
```
### createDragAction
createDragAction(customArray: Array<CustomBuilder \| DragItemInfo>, dragInfo: dragController.DragInfo): dragController.DragAction
Creates a **DragAction** object, by explicitly specifying one or more drag previews, drag data, and information about the dragged object. If the drag initiated by a **DragAction** object is not complete, no new **DragAction** object can be created, and calling this API will throw an exception.
**NOTE**
You are advised to control the number of drag previews. If too many previews are passed in, the drag efficiency may be affected.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------- |
| customArray | Array<[CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo)> | Yes | Object to be dragged.|
| dragInfo | [dragController.DragInfo](js-apis-arkui-dragController.md#dragInfo) | Yes | Dragging information. |
**Return value**
| Type | Description |
| ------------------------------------------------------ | ------------------ |
| [dragController.DragAction](js-apis-arkui-dragController.md#dragaction11)| **DragAction** object, which is used to subscribe to drag state change events and start the dragging service.|
**Error codes**
| ID| Error Message |
| -------- | ------------- |
| 100001 | if some internal handling failed. |
**Example**
1. In the **EntryAbility.ets** file, obtain the UI context and save it to LocalStorage.
```ts
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import hilog from '@ohos.hilog';
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import window from '@ohos.window';
import { UIContext } from '@ohos.arkui.UIContext';
let uiContext: UIContext;
let localStorage: LocalStorage = new LocalStorage('uiContext');
export default class EntryAbility extends UIAbility {
storage: LocalStorage = localStorage;
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
}
onDestroy(): void {
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy');
}
onWindowStageCreate(windowStage: window.WindowStage): void {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
if (err.code) {
hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
return;
}
hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
windowStage.getMainWindow((err, data) =>
{
if (err.code) {
console.log('Failed to abtain the main window. Cause:' + err.message);
return;
}
let windowClass: window.Window = data;
uiContext = windowClass.getUIContext();
this.storage.setOrCreate('uiContext', uiContext);
// Obtain a UIContext instance.
})
});
}
onWindowStageDestroy(): void {
// Main window is destroyed, release UI related resources
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
}
onForeground(): void {
// Ability has brought to foreground
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
}
onBackground(): void {
// Ability has back to background
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground');
}
}
```
2. Call **LocalStorage.getShared()** to obtain the UI context and then use the **DragController** object obtained to perform subsequent operations.
```ts
import dragController from "@ohos.arkui.dragController"
import componentSnapshot from '@ohos.arkui.componentSnapshot';
import image from '@ohos.multimedia.image';
import UDC from '@ohos.data.unifiedDataChannel';
import { UIContext, DragController } from '@ohos.arkui.UIContext'
let storages = LocalStorage.getShared();
@Entry(storages)
@Component
struct DragControllerPage {
@State pixmap: image.PixelMap|null = null
private dragAction: dragController.DragAction|null = null;
customBuilders:Array = new Array();
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Column() {
Text ("Test")
}
.width(100)
.height(100)
.backgroundColor(Color.Red)
Button('Drag Multiple Objects').onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
console.log("muti drag Down by listener");
this.customBuilders.push(()=>{this.DraggingBuilder()});
this.customBuilders.push(()=>{this.DraggingBuilder()});
this.customBuilders.push(()=>{this.DraggingBuilder()});
let text = new UDC.Text()
let unifiedData = new UDC.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
try{
let uiContext: UIContext = storages.get('uiContext') as UIContext;
this.dragAction = uiContext.getDragController().createDragAction(this.customBuilders, dragInfo)
if(!this.dragAction){
console.log("listener dragAction is null");
return
}
this.dragAction.on('statusChange', (dragAndDropInfo)=>{
if (dragAndDropInfo.status == dragController.DragStatus.STARTED) {
console.log("drag has start");
} else if (dragAndDropInfo.status == dragController.DragStatus.ENDED){
console.log("drag has end");
if (!this.dragAction) {
return
}
this.customBuilders.splice(0, this.customBuilders.length)
this.dragAction.off('statusChange')
}
})
this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{
console.log("start drag Error:" + err.message);
})
} catch(err) {
console.log("create dragAction Error:" + err.message);
}
}
}
}).margin({top:20})
}
}
}
```
## AtomicServiceBar11+
In the following API examples, you must first use [getAtomicServiceBar](#getatomicservicebar11) in **UIContext** to obtain an **AtomicServiceBar** instance, and then call the APIs using the obtained instance.
### setVisible11+
setVisible(visible: boolean): void
Sets whether the atomic service menu bar is visible.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name| Type| Mandatory| Description|
| ------- | ------- | ------- | ------- |
| visiable | boolean | Yes| Whether the atomic service menu bar is visible.|
**Example**
```ts
import { UIContext, AtomicServiceBar } from '@ohos.arkui.UIContext';
import hilog from '@ohos.hilog';
import window from "@ohos.window";
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
let uiContext: UIContext = windowStage.getMainWindowSync().getUIContext();
let atomicServiceBar: Nullable = uiContext.getAtomicServiceBar();
if (atomicServiceBar != undefined) {
hilog.info(0x0000, 'testTag', 'Get AtomServiceBar Successfully.');
atomicServiceBar.setVisible(false);
} else {
hilog.error(0x0000, 'testTag', 'Get AtomicServiceBar failed.');
}
});
}
```
### setBackgroundColor11+
setBackgroundColor(color:Nullable): void
Sets the background color of the atomic service menu bar.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | ------ | ------ | ------ |
| color | color:Nullable\<[Color](../arkui-ts/ts-appendix-enums.md#color) \| number \| string> | Yes| Background color of the atomic service menu bar. The value **undefined** means to use the default color.|
**Example**
```ts
import { UIContext, AtomicServiceBar } from '@ohos.arkui.UIContext';
import hilog from '@ohos.hilog';
import window from "@ohos.window";
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
let uiContext: UIContext = windowStage.getMainWindowSync().getUIContext();
let atomicServiceBar: Nullable = uiContext.getAtomicServiceBar();
if (atomicServiceBar != undefined) {
hilog.info(0x0000, 'testTag', 'Get AtomServiceBar Successfully.');
atomicServiceBar.setBackgroundColor(0x88888888);
} else {
hilog.error(0x0000, 'testTag', 'Get AtomicServiceBar failed.');
}
});
}
```
### setTitleContent11+
setTitleContent(content:string): void
Sets the title of the atomic service menu bar.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
|Name|Type|Mandatory|Description|
| ------- | ------- | ------- | ------- |
| content | string | Yes| Title of the atomic service menu bar.|
**Example**
```ts
import { UIContext, AtomicServiceBar } from '@ohos.arkui.UIContext';
import hilog from '@ohos.hilog';
import window from "@ohos.window";
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
let uiContext: UIContext = windowStage.getMainWindowSync().getUIContext();
let atomicServiceBar: Nullable = uiContext.getAtomicServiceBar();
if (atomicServiceBar != undefined) {
hilog.info(0x0000, 'testTag', 'Get AtomServiceBar Successfully.');
atomicServiceBar.setTitleContent('text2');
} else {
hilog.error(0x0000, 'testTag', 'Get AtomicServiceBar failed.');
}
});
}
```
### setTitleFontStyle11+
setTitleFontStyle(font:FontStyle):void
Sets the font style of the atomic service menu bar.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name| Type| Mandatory| Description|
| ------ | ------ | ------ | ------ |
| font | [FontStyle](../arkui-ts/ts-appendix-enums.md#fontstyle) | Yes| Font style of the atomic service menu bar.|
**Example**
```ts
import { UIContext, Font, AtomicServiceBar } from '@ohos.arkui.UIContext';
import hilog from '@ohos.hilog';
import window from "@ohos.window";
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
let uiContext: UIContext = windowStage.getMainWindowSync().getUIContext();
let atomicServiceBar: Nullable = uiContext.getAtomicServiceBar();
if (atomicServiceBar != undefined) {
hilog.info(0x0000, 'testTag', 'Get AtomServiceBar Successfully.');
atomicServiceBar.setTitleFontStyle(FontStyle.Normal);
} else {
hilog.error(0x0000, 'testTag', 'Get AtomicServiceBar failed.');
}
});
}
```
### setIconColor11+
setIconColor(color:Nullable): void
Sets the color of the atomic service icon.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
**Parameters**
| Name| Type| Mandatory| Description|
| ------- | ------- | ------- | ------- |
| color | Nullable\<[Color](../arkui-ts/ts-appendix-enums.md#color) \| number \| string> | Yes| Color of the atomic service icon. The value **undefined** means to use the default color.|
**Example**
```ts
import { UIContext, AtomicServiceBar } from '@ohos.arkui.UIContext';
import hilog from '@ohos.hilog';
import window from "@ohos.window";
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
hilog.info(0x0000, 'testTag', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
let uiContext: UIContext = windowStage.getMainWindowSync().getUIContext();
let atomicServiceBar: Nullable = uiContext.getAtomicServiceBar();
if (atomicServiceBar != undefined) {
hilog.info(0x0000, 'testTag', 'Get AtomServiceBar Successfully.');
atomicServiceBar.setIconColor(0x12345678);
} else {
hilog.error(0x0000, 'testTag', 'Get AtomicServiceBar failed.');
}
});
}
```
## KeyboardAvoidMode11+
Enumerates the avoidance modes for the virtual keyboard.
**System capability**: SystemCapability.ArkUI.ArkUI.Full
| Name | Description |
| ------ | ---------- |
| OFFSET | Avoid the virtual keyboard through offset.|
| RESIZE | Avoid the virtual keyboard through resizing.|