# @ohos.arkui.UIContext (UIContext) 在Stage模型中，WindowStage/Window可以通过[loadContent](js-apis-window.md#loadcontent9)接口加载页面并创建UI的实例，并将页面内容渲染到关联的窗口中，所以UI实例和窗口是一一关联的。一些全局的UI接口是和具体UI实例的执行上下文相关的，在当前接口调用时，通过追溯调用链跟踪到UI的上下文，来确定具体的UI实例。若在非UI页面中或者一些异步回调中调用这类接口，可能无法跟踪到当前UI的上下文，导致接口执行失败。 @ohos.window在API version 10 新增[getUIContext](js-apis-window.md#getuicontext10)接口，获取UI上下文实例UIContext对象，使用UIContext对象提供的替代方法，可以直接作用在对应的UI实例上。 > **说明：** > > 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > > 示例效果请以真机运行为准，当前DevEco Studio预览器不支持。 ## UIContext 以下API需先使用ohos.window中的[getUIContext()](js-apis-window.md#getuicontext10)方法获取UIContext实例，再通过此实例调用对应方法。或者可以通过自定义组件内置方法[getUIContext()](arkui-ts/ts-custom-component-api.md#getuicontext)获取。本文中UIContext对象以uiContext表示。 ### getFont getFont(): Font 获取Font对象。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------------- | ----------- | | [Font](#font) | 返回Font实例对象。 | **示例：** ```ts uiContext.getFont(); ``` ### getComponentUtils getComponentUtils(): ComponentUtils 获取ComponentUtils对象。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | --------------------------------- | --------------------- | | [ComponentUtils](#componentutils) | 返回ComponentUtils实例对象。 | **示例：** ```ts uiContext.getComponentUtils(); ``` ### getUIInspector getUIInspector(): UIInspector 获取UIInspector对象。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | --------------------------- | ------------------ | | [UIInspector](#uiinspector) | 返回UIInspector实例对象。 | **示例：** ```ts uiContext.getUIInspector(); ``` ### getUIObserver11+ getUIObserver(): UIObserver 获取UIObserver对象。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | --------------------------- | ------------------ | | [UIObserver](#uiobserver11) | 返回UIObserver实例对象。 | **示例：** ```ts uiContext.getUIObserver(); ``` ### getMediaQuery getMediaQuery(): MediaQuery 获取MediaQuery对象。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------------------------- | ----------------- | | [MediaQuery](#mediaquery) | 返回MediaQuery实例对象。 | **示例：** ```ts uiContext.getMediaQuery(); ``` ### getRouter getRouter(): Router 获取Router对象。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ----------------- | ------------- | | [Router](#router) | 返回Router实例对象。 | **示例：** ```ts uiContext.getRouter(); ``` ### getPromptAction getPromptAction(): PromptAction 获取PromptAction对象。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ----------------------------- | ------------------- | | [PromptAction](#promptaction) | 返回PromptAction实例对象。 | **示例：** ```ts uiContext.getPromptAction(); ``` ### getOverlayManager12+ getOverlayManager(): OverlayManager 获取OverlayManager对象。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：**: SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ----------------------------- | ------------------- | | [OverlayManager](#overlaymanager12) | 返回OverlayManager实例对象。 | **示例：** ```ts uiContext.getOverlayManager(); ``` ### setOverlayManagerOptions15+ setOverlayManagerOptions(options: OverlayManagerOptions): boolean 设置[OverlayManager](#overlaymanager12)参数。用于在使用OverlayManager能力之前先初始化overlayManager的参数，包括是否需要渲染overlay根节点等属性。该方法需要在执行getOverlayManager方法之前执行生效，且该方法只生效一次。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：**: SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ------------------------------------- | | options | [OverlayManagerOptions](#overlaymanageroptions15) | 是 | OverlayManager参数。| **返回值：** | 类型 | 说明 | | ------- | -------------- | | boolean | 是否设置成功。
返回true时，设置成功。返回false时，设置失败。 | **示例：** ```ts uiContext.setOverlayManagerOptions({ renderRootOverlay: true }); ``` ### getOverlayManagerOptions15+ getOverlayManagerOptions(): OverlayManagerOptions 用于获取当前[OverlayManager](#overlaymanager12)参数。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：**: SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ----------------------------- | ------------------- | | [OverlayManagerOptions](#overlaymanageroptions15) | 返回当前OverlayManagerOptions。 | **示例：** ```ts uiContext.getOverlayManagerOptions(); ``` ### animateTo animateTo(value: AnimateParam, event: () => void): void 提供animateTo接口来指定由于闭包代码导致的状态变化插入过渡动效。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ------------------------------------- | | value | [AnimateParam](arkui-ts/ts-explicit-animation.md#animateparam对象说明) | 是 | 设置动画效果相关参数。 | | event | () => void | 是 | 指定显示动效的闭包函数，在闭包函数中导致的状态变化系统会自动插入过渡动画。 | **示例：** ```ts // xxx.ets @Entry @Component struct AnimateToExample { @State widthSize: number = 250 @State heightSize: number = 100 @State rotateAngle: number = 0 private flag: boolean = true uiContext: UIContext | undefined = undefined; aboutToAppear() { this.uiContext = this.getUIContext(); if (!this.uiContext) { console.warn("no uiContext"); return; } } build() { Column() { Button('change size') .width(this.widthSize) .height(this.heightSize) .margin(30) .onClick(() => { if (this.flag) { this.uiContext?.animateTo({ duration: 2000, curve: Curve.EaseOut, iterations: 3, playMode: PlayMode.Normal, onFinish: () => { console.info('play end') } }, () => { this.widthSize = 150 this.heightSize = 60 }) } else { this.uiContext?.animateTo({}, () => { this.widthSize = 250 this.heightSize = 100 }) } this.flag = !this.flag }) Button('stop rotating') .margin(50) .rotate({ x: 0, y: 0, z: 1, angle: this.rotateAngle }) .onAppear(() => { // 组件出现时开始做动画 this.uiContext?.animateTo({ duration: 1200, curve: Curve.Friction, delay: 500, iterations: -1, // 设置-1表示动画无限循环 playMode: PlayMode.Alternate, expectedFrameRateRange: { min: 10, max: 120, expected: 60, } }, () => { this.rotateAngle = 90 }) }) .onClick(() => { this.uiContext?.animateTo({ duration: 0 }, () => { // this.rotateAngle之前为90，在duration为0的动画中修改属性，可以停止该属性之前的动画，按新设置的属性显示 this.rotateAngle = 0 }) }) }.width('100%').margin({ top: 5 }) } } ``` ### getSharedLocalStorage12+ getSharedLocalStorage(): LocalStorage | undefined 获取当前stage共享的LocalStorage实例。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **模型约束：** 此接口仅可在Stage模型下使用。 **返回值：** | 类型 | 描述 | | ------------------------------ | ----------------- | | [LocalStorage](arkui-ts/ts-state-management.md#localstorage9) \| undefined | 返回LocalStorage实例。共享的LocalStorage实例不存在时返回undefined。 | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { storage: LocalStorage = new LocalStorage(); onWindowStageCreate(windowStage: window.WindowStage) { windowStage.loadContent('pages/Index', this.storage); } } ``` ```ts // Index.ets @Entry @Component struct SharedLocalStorage { localStorage = this.getUIContext().getSharedLocalStorage(); build() { Row() { Column() { Button("Change Local Storage to 47") .onClick(() => { this.localStorage?.setOrCreate("propA", 47); }) Button("Get Local Storage") .onClick(() => { console.info(`localStorage: ${this.localStorage?.get("propA")}`); }) } .width('100%') } .height('100%') } } ``` ### getHostContext12+ getHostContext(): Context | undefined 获得当前元能力的Context。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **模型约束：** 此接口仅可在Stage模型下使用。 **返回值：** | 类型 | 说明 | | ------ | ------------------------------- | | [Context](#context12) \| undefined | 返回当前组件所在Ability的Context，Context的具体类型为当前Ability关联的Context对象。例如：在UIAbility窗口中的页面调用该接口，返回类型为UIAbilityContext。在ExtensionAbility窗口中的页面调用该接口，返回类型为ExtensionContext。ability上下文不存在时返回undefined。 | **示例：** ```ts @Entry @Component struct Index { uiContext = this.getUIContext(); build() { Row() { Column() { Text("cacheDir='"+this.uiContext?.getHostContext()?.cacheDir+"'").fontSize(25) Text("bundleCodeDir='"+this.uiContext?.getHostContext()?.bundleCodeDir+"'").fontSize(25) } .width('100%') } .height('100%') } } ``` ### getFrameNodeById12+ getFrameNodeById(id: string): FrameNode | null 通过组件的id获取组件树的实体节点。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ------------------------------------- | | id | string | 是 | 节点对应的[组件标识](arkui-ts/ts-universal-attributes-component-id.md)。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------- | | [FrameNode](js-apis-arkui-frameNode.md) \| null | 返回的组件树的实体节点或者空节点。 | > **说明：** > > getFrameNodeById通过遍历查询对应id的节点，性能较差。推荐使用[getAttachedFrameNodeById](#getattachedframenodebyid12)。 **示例：** ```ts uiContext.getFrameNodeById("TestNode") ``` ### getAttachedFrameNodeById12+ getAttachedFrameNodeById(id: string): FrameNode | null 通过组件的id获取当前窗口上的实体节点。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ------------------------------------- | | id | string | 是 | 节点对应的[组件标识](arkui-ts/ts-universal-attributes-component-id.md)。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------- | | [FrameNode](js-apis-arkui-frameNode.md) \| null | 返回的组件树的实体节点或者空节点。 | > **说明：** > > getAttachedFrameNodeById仅能查询上屏节点。 **示例：** ```ts uiContext.getAttachedFrameNodeById("TestNode") ``` ### getFrameNodeByUniqueId12+ getFrameNodeByUniqueId(id: number): FrameNode | null 提供getFrameNodeByUniqueId接口通过组件的uniqueId获取组件树的实体节点。 1. 当uniqueId对应的是系统组件时，返回组件所对应的FrameNode； 2. 当uniqueId对应的是自定义组件时，若其有渲染内容，则返回该自定义组件的根节点，类型为__Common__；若其无渲染内容，则返回其第一个子组件的FrameNode。 3. 当uniqueId无对应的组件时，返回null。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ------------------------------------- | | id | number | 是 | 节点对应的UniqueId | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------- | | [FrameNode](js-apis-arkui-frameNode.md) \| null | 返回的组件树的实体节点或者空节点。 | **示例：** ```ts import { UIContext, FrameNode } from '@kit.ArkUI'; @Entry @Component struct MyComponent { aboutToAppear() { let uniqueId: number = this.getUniqueId(); let uiContext: UIContext = this.getUIContext(); if (uiContext) { let node: FrameNode | null = uiContext.getFrameNodeByUniqueId(uniqueId); } } build() { // ... } } ``` ### getPageInfoByUniqueId12+ getPageInfoByUniqueId(id: number): PageInfo 提供getPageInfoByUniqueId接口通过组件的uniqueId获取该节点对应的Router和NavDestination页面信息。 1. 当uniqueId对应的节点在Page节点中，routerPageInfo属性为其对应的Router信息； 2. 当uniqueId对应的节点在NavDestination节点中，navDestinationInfo属性为其对应的NavDestination信息； 3. 当uniqueId对应的节点无对应的Router或NavDestination信息时，对应的属性为undefined； 4. 模态弹窗并不在任何Page节点中。当uniqueId对应的节点在模态弹窗中,例如[CustomDialog](./arkui-ts/ts-methods-custom-dialog-box.md)、[bindSheet](./arkui-ts/ts-universal-attributes-sheet-transition.md#bindsheet)和[bindContentCover](./arkui-ts/ts-universal-attributes-modal-transition.md#bindcontentcover)构建的模态页面中，routerPageInfo属性为undefined。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ------------------------------------- | | id | number | 是 | 节点对应的UniqueId | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------- | | [PageInfo](#pageinfo12) | 返回节点对应的Router和NavDestination信息。 | **示例：** ```ts import { UIContext, PageInfo } from '@kit.ArkUI'; @Entry @Component struct PageInfoExample { @Provide('pageInfos') pageInfos: NavPathStack = new NavPathStack(); build() { Column() { Navigation(this.pageInfos) { NavDestination() { MyComponent() } }.id('navigation') } } } @Component struct MyComponent { @State content: string = ''; build() { Column() { Text('PageInfoExample') Button('click').onClick(() => { const uiContext: UIContext = this.getUIContext(); const uniqueId: number = this.getUniqueId(); const pageInfo: PageInfo = uiContext.getPageInfoByUniqueId(uniqueId); console.info('pageInfo: ' + JSON.stringify(pageInfo)); console.info('navigationInfo: ' + JSON.stringify(uiContext.getNavigationInfoByUniqueId(uniqueId))); }) TextArea({ text: this.content }) .width('100%') .height(100) } .width('100%') .alignItems(HorizontalAlign.Center) } } ``` ### getNavigationInfoByUniqueId12+ getNavigationInfoByUniqueId(id: number): observer.NavigationInfo | undefined 提供getNavigationInfoByUniqueId接口通过组件的uniqueId获取该节点对应的Navigation页面信息。 1. 当uniqueId对应的节点在Navigation节点中，返回其对应的Navigation信息； 2. 当uniqueId对应的节点无对应的Navigation信息时，返回undefined。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ------------------------------------- | | id | number | 是 | 节点对应的UniqueId | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------- | | observer.[NavigationInfo](js-apis-arkui-observer.md#navigationinfo12) \| undefined | 返回节点对应的Navigation信息。 | **示例：** 请参考[getPageInfoByUniqueId](#getpageinfobyuniqueid12)的示例。 ### showAlertDialog showAlertDialog(options: AlertDialogParamWithConfirm | AlertDialogParamWithButtons | AlertDialogParamWithOptions): void 显示警告弹窗组件，可设置文本内容与响应回调。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------------------- | | 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对象说明) | 是 | 定义并显示AlertDialog组件。 | **示例：** ```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 定义列表弹窗并弹出。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------------------------------ | ---- | -------------------- | | value | [ActionSheetOptions](arkui-ts/ts-methods-action-sheet.md#actionsheetoptions对象说明) | 是 | 配置列表弹窗的参数。 | **示例：** ```ts uiContext.showActionSheet({ title: 'ActionSheet title', message: 'message', autoCancel: true, confirm: { value: 'Confirm button', action: () => { console.info('Get Alert Dialog handled') } }, cancel: () => { console.info('actionSheet canceled') }, alignment: DialogAlignment.Bottom, offset: { dx: 0, dy: -10 }, sheets: [ { title: 'apples', action: () => { console.info('apples') } }, { title: 'bananas', action: () => { console.info('bananas') } }, { title: 'pears', action: () => { console.info('pears') } } ] }) ``` ### showDatePickerDialog showDatePickerDialog(options: DatePickerDialogOptions): void 定义日期滑动选择器弹窗并弹出。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------------------------------------ | ---- | ------------------------------ | | options | [DatePickerDialogOptions](arkui-ts/ts-methods-datepicker-dialog.md#datepickerdialogoptions对象说明) | 是 | 配置日期滑动选择器弹窗的参数。 | **示例：** ```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) => { // 通过Date的setFullYear方法设置按下确定按钮时的日期，这样当弹窗再次弹出时显示选中的是上一次确定的日期 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 定义时间滑动选择器弹窗并弹出。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------------------------------------ | ---- | ------------------------------ | | options | [TimePickerDialogOptions](arkui-ts/ts-methods-timepicker-dialog.md#timepickerdialogoptions对象说明) | 是 | 配置时间滑动选择器弹窗的参数。 | **示例：** ```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(() => { this.getUIContext().showTimePickerDialog({ selected: this.selectTime, onAccept: (value: TimePickerResult) => { // 设置selectTime为按下确定按钮时的时间，这样当弹窗再次弹出时显示选中的为上一次确定的时间 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 定义文本滑动选择器弹窗并弹出。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------------------------------------ | ---- | ------------------------------ | | options | [TextPickerDialogOptions](arkui-ts/ts-methods-textpicker-dialog.md#textpickerdialogoptions对象说明) | 是 | 配置文本滑动选择器弹窗的参数。 | **示例：** ```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(() => { this.getUIContext().showTextPickerDialog({ range: this.fruits, selected: this.select, onAccept: (value: TextPickerResult) => { // 设置select为按下确定按钮时候的选中项index，这样当弹窗再次弹出时显示选中的是上一次确定的选项 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 定义Animator类。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | options | [AnimatorOptions](js-apis-animator.md#animatoroptions) | 是 | 定义动画选项。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------- | | [AnimatorResult](js-apis-animator.md#animatorresult) | Animator结果接口。 | **错误码**： 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | **示例：** ```ts // EntryAbility.ets import { AnimatorOptions, window } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; // used in UIAbility 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); }); } ``` ### createAnimator18+ createAnimator(options: AnimatorOptions | SimpleAnimatorOptions): AnimatorResult 创建animator动画结果对象（AnimatorResult）。与[createAnimator](#createanimator)相比，新增对[SimpleAnimatorOptions](js-apis-animator.md#simpleanimatoroptions18)类型入参的支持。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | options | [AnimatorOptions](js-apis-animator.md#animatoroptions) \| [SimpleAnimatorOptions](js-apis-animator.md#simpleanimatoroptions18) | 是 | 定义动画选项。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------------- | | [AnimatorResult](js-apis-animator.md#animatorresult) | Animator结果接口。 | **错误码**： 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | **示例：** ```ts import { SimpleAnimatorOptions, window } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; // used in UIAbility 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: SimpleAnimatorOptions = new SimpleAnimatorOptions(100, 200).duration(2000); uiContext.createAnimator(options); }); } ``` ### runScopedTask runScopedTask(callback: () => void): void 在当前UI上下文执行传入的回调函数。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------- | ---- | ---- | | callback | () => void | 是 | 回调函数 | **示例：** ```ts uiContext.runScopedTask( () => { console.info('Succeeded in runScopedTask'); } ); ``` ### setKeyboardAvoidMode11+ setKeyboardAvoidMode(value: KeyboardAvoidMode): void 配置虚拟键盘弹出时，页面的避让模式。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------- | ---- | ---- | | value | [KeyboardAvoidMode](#keyboardavoidmode11)| 是 | 键盘避让时的页面避让模式。
默认值:KeyboardAvoidMode.OFFSET | **示例：** ```ts // EntryAbility.ets import { KeyboardAvoidMode, UIContext } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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 获取虚拟键盘弹出时，页面的避让模式。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ---------- | ---- | | [KeyboardAvoidMode](#keyboardavoidmode11)| 返回当前的页面避让模式。| **示例：** ```ts // EntryAbility.ets import { KeyboardAvoidMode, UIContext } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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(); hilog.info(0x0000, "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\ 获取AtomicServiceBar对象，通过该对象设置原子化服务menuBar的属性。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------------------------------------------------- | ------------------------------------------------------------ | | Nullable<[AtomicServiceBar](#atomicservicebar11)> | 如果是原子化服务则返回AtomicServerBar类型，否则返回undefined。 | **示例：** ```ts // EntryAbility.ets import { UIContext, AtomicServiceBar, window } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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 获取DragController对象，可通过该对象创建并发起拖拽。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** |类型|说明| |----|----| |[DragController](js-apis-arkui-dragController.md#dragController)| 获取DragController对象。| **示例：** ```ts uiContext.getDragController(); ``` ### keyframeAnimateTo11+ keyframeAnimateTo(param: KeyframeAnimateParam, keyframes: Array<KeyframeState>): void 产生关键帧动画。该接口的使用说明请参考[keyframeAnimateTo](arkui-ts/ts-keyframeAnimateTo.md)。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------ | ---------------------------------------------------- | ------- | ---------------------------- | | param | [KeyframeAnimateParam](arkui-ts/ts-keyframeAnimateTo.md#keyframeanimateparam对象说明) | 是 | 关键帧动画的整体动画参数。 | | keyframes | Array<[KeyframeState](arkui-ts/ts-keyframeAnimateTo.md#keyframestate对象说明)> | 是 | 所有的关键帧状态。 | ### getFocusController12+ getFocusController(): FocusController 获取[FocusController](js-apis-arkui-UIContext.md#focuscontroller12)对象，可通过该对象控制焦点。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** |类型|说明| |----|----| |[FocusController](js-apis-arkui-UIContext.md#focuscontroller12)| 获取FocusController对象。| **示例：** ```ts uiContext.getFocusController(); ``` ### getFilteredInspectorTree12+ getFilteredInspectorTree(filters?: Array\): string 获取组件树及组件属性。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------- | ---- | ------------------------------------------------------------ | | filters | Array\ | 否 | 需要获取的组件属性的过滤列表。目前仅支持过滤字段：
"id"：组件唯一标识。
"src"：资源来源。
"content"：元素、组件或对象所包含的信息或数据。
"editable"：是否可编辑。
"scrollable"：是否可滚动。
"selectable"：是否可选择。
"focusable"：是否可聚焦。
"focused"：是否已聚焦。
其余字段仅供测试场景使用。 | **返回值：** | 类型 | 说明 | | ------ | ---------------------------------- | | string | 获取组件树及组件属性的JSON字符串。 | **错误码**： 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | **示例：** ```ts uiContext.getFilteredInspectorTree(['id', 'src', 'content']); ``` ### getFilteredInspectorTreeById12+ getFilteredInspectorTreeById(id: string, depth: number, filters?: Array\): string 获取指定的组件及其子组件的属性。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------- | ---- | ------------------------------------------------------------ | | id | string | 是 | 指定的[组件标识](arkui-ts/ts-universal-attributes-component-id.md)id。 | | depth | number | 是 | 获取子组件的层数。当取值0时，获取指定的组件及其所有的子孙组件的属性。当取值1时，仅获取指定的组件的属性。当取值2时，指定的组件及其1层子组件的属性。以此类推。 | | filters | Array\ | 否 | 需要获取的组件属性的过滤列表。目前仅支持过滤字段：
"id"：组件唯一标识。
"src"：资源来源。
"content"：元素、组件或对象所包含的信息或数据。
"editable"：是否可编辑。
"scrollable"：是否可滚动。
"selectable"：是否可选择。
"focusable"：是否可聚焦。
"focused"：是否已聚焦。
其余字段仅供测试场景使用。 | **返回值：** | 类型 | 说明 | | ------ | -------------------------------------------- | | string | 获取指定的组件及其子组件的属性的JSON字符串。 | **错误码**： 以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | **示例：** ```ts uiContext.getFilteredInspectorTreeById('testId', 0, ['id', 'src', 'content']); ``` ### getCursorController12+ getCursorController(): CursorController 获取[CursorController](js-apis-arkui-UIContext.md#cursorcontroller12)对象，可通过该对象控制光标。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** |类型|说明| |----|----| |[CursorController](js-apis-arkui-UIContext.md#cursorcontroller12)| 获取CursorController对象。| **示例：** ```ts uiContext.CursorController(); ``` ### getContextMenuController12+ getContextMenuController(): ContextMenuController 获取[ContextMenuController](#contextmenucontroller12)对象，可通过该对象控制菜单。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** |类型|说明| |----|----| |[ContextMenuController](#contextmenucontroller12)| 获取ContextMenuController对象。| **示例：** ```ts uiContext.getContextMenuController(); ``` ### getMeasureUtils12+ getMeasureUtils(): MeasureUtils 允许用户通过UIContext对象，获取MeasureUtils对象进行文本计算。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------ | -------------------------------------------- | | [MeasureUtils](js-apis-arkui-UIContext.md#measureutils12) | 提供文本宽度、高度等相关计算。 | **示例：** ```ts uiContext.getMeasureUtils(); ``` ### getComponentSnapshot12+ getComponentSnapshot(): ComponentSnapshot 获取ComponentSnapshot对象，可通过该对象获取组件截图的能力。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | --------------------------- | | [ComponentSnapshot](js-apis-arkui-UIContext.md#componentsnapshot12) | 获取ComponentSnapshot对象。 | **示例：** ```ts uiContext.getComponentSnapshot(); ``` ### vp2px12+ vp2px(value : number) : number 将vp单位的数值转换为以px为单位的数值。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | -------------------------------------- | | value | number | 是 | 将vp单位的数值转换为以px为单位的数值。
取值范围：(-∞, +∞) | **返回值：** | 类型 | 说明 | | ------ | -------------- | | number | 转换后的数值。
取值范围：(-∞, +∞) | **示例：** ```ts uiContext.vp2px(200); ``` ### px2vp12+ px2vp(value : number) : number 将px单位的数值转换为以vp为单位的数值。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | -------------------------------------- | | value | number | 是 | 将px单位的数值转换为以vp为单位的数值。
取值范围：(-∞, +∞) | **返回值：** | 类型 | 说明 | | ------ | -------------- | | number | 转换后的数值。
取值范围：(-∞, +∞) | **示例：** ```ts uiContext.px2vp(200); ``` ### fp2px12+ fp2px(value : number) : number 将fp单位的数值转换为以px为单位的数值。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | -------------------------------------- | | value | number | 是 | 将fp单位的数值转换为以px为单位的数值。
取值范围：(-∞, +∞) | **返回值：** | 类型 | 说明 | | ------ | -------------- | | number | 转换后的数值。
取值范围：(-∞, +∞) | **示例：** ```ts uiContext.fp2px(200); ``` ### px2fp12+ px2fp(value : number) : number 将px单位的数值转换为以fp为单位的数值。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | -------------------------------------- | | value | number | 是 | 将px单位的数值转换为以fp为单位的数值。
取值范围：(-∞, +∞) | **返回值：** | 类型 | 说明 | | ------ | -------------- | | number | 转换后的数值。
取值范围：(-∞, +∞) | **示例：** ```ts uiContext.px2fp(200); ``` ### lpx2px12+ lpx2px(value : number) : number 将lpx单位的数值转换为以px为单位的数值。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------------------------- | | value | number | 是 | 将lpx单位的数值转换为以px为单位的数值。
取值范围：(-∞, +∞) | **返回值：** | 类型 | 说明 | | ------ | -------------- | | number | 转换后的数值。
取值范围：(-∞, +∞) | **示例：** ```ts uiContext.lpx2px(200); ``` ### px2lpx12+ px2lpx(value : number) : number 将px单位的数值转换为以lpx为单位的数值。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------------------------- | | value | number | 是 | 将px单位的数值转换为以lpx为单位的数值。
取值范围：(-∞, +∞) | **返回值：** | 类型 | 说明 | | ------ | -------------- | | number | 转换后的数值。
取值范围：(-∞, +∞) | **示例：** ```ts uiContext.px2lpx(200); ``` ### getWindowName12+ getWindowName(): string | undefined 获取当前实例所在窗口的名称。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------ | -------------------------------------------- | | string \| undefined | 当前实例所在窗口的名称。若窗口不存在，则返回undefined。 | **示例：** ```ts import { window } from '@kit.ArkUI'; @Entry @Component struct Index { @State message: string = 'Hello World' aboutToAppear() { const windowName = this.getUIContext().getWindowName(); console.info('WindowName ' + windowName); const currWindow = window.findWindow(windowName); const windowProperties = currWindow.getWindowProperties(); console.info(`Window width ${windowProperties.windowRect.width}, height ${windowProperties.windowRect.height}`); } build() { Row() { Column() { Text(this.message) .fontSize(50) .fontWeight(FontWeight.Bold) } .width('100%') } .height('100%') } } ``` ### getWindowWidthBreakpoint13+ getWindowWidthBreakpoint(): WidthBreakpoint 获取当前实例所在窗口的宽度断点枚举值。具体枚举值根据窗口宽度vp值确定，详见 [WidthBreakpoint](./arkui-ts/ts-appendix-enums.md#widthbreakpoint13)。 **原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------ | -------------------------------------------- | | [WidthBreakpoint](./arkui-ts/ts-appendix-enums.md#widthbreakpoint13) | 当前实例所在窗口的宽度断点枚举值。若窗口宽度为 0vp，则返回WIDTH_XS。 | **示例：** ```ts import { UIContext } from '@kit.ArkUI'; @Entry @Component struct Index { @State message: string = 'Hello World'; build() { Row() { Column() { Text(this.message) .fontSize(30) .fontWeight(FontWeight.Bold) Button() { Text('test') .fontSize(30) } .onClick(() => { let uiContext: UIContext = this.getUIContext(); let heightBp: HeightBreakpoint = uiContext.getWindowHeightBreakpoint(); let widthBp: WidthBreakpoint = uiContext.getWindowWidthBreakpoint(); console.info(`Window heightBP: ${heightBp}, widthBp: ${widthBp}`) }) } .width('100%') } .height('100%') } } ``` ### getWindowHeightBreakpoint13+ getWindowHeightBreakpoint(): HeightBreakpoint 获取当前实例所在窗口的高度断点。具体枚举值根据窗口高宽比确定，详见 [HeightBreakpoint](./arkui-ts/ts-appendix-enums.md#heightbreakpoint13)。 **原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------ | -------------------------------------------- | | [HeightBreakpoint](./arkui-ts/ts-appendix-enums.md#heightbreakpoint13) | 当前实例所在窗口的宽高比对应的高度断点枚举值。若窗口高宽比为0，则返回HEIGHT_SM。 | **示例：** ```ts import { UIContext } from '@kit.ArkUI'; @Entry @Component struct Index { @State message: string = 'Hello World'; build() { Row() { Column() { Text(this.message) .fontSize(30) .fontWeight(FontWeight.Bold) Button() { Text('test') .fontSize(30) } .onClick(() => { let uiContext: UIContext = this.getUIContext(); let heightBp: HeightBreakpoint = uiContext.getWindowHeightBreakpoint(); let widthBp: WidthBreakpoint = uiContext.getWindowWidthBreakpoint(); console.info(`Window heightBP: ${heightBp}, widthBp: ${widthBp}`) }) } .width('100%') } .height('100%') } } ``` ### postFrameCallback12+ postFrameCallback(frameCallback: FrameCallback): void 注册一个回调，仅在下一帧渲染时调用。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------------------------- | | frameCallback | [FrameCallback](#framecallback12) | 是 | 下一帧需要执行的回调。 | **示例：** ```ts import {FrameCallback } from '@kit.ArkUI'; class MyFrameCallback extends FrameCallback { private tag: string; constructor(tag: string) { super() this.tag = tag; } onFrame(frameTimeNanos: number) { console.info('MyFrameCallback ' + this.tag + ' ' + frameTimeNanos.toString()); } } @Entry @Component struct Index { build() { Row() { Button('点击触发postFrameCallback') .onClick(() => { this.getUIContext().postFrameCallback(new MyFrameCallback("normTask")); }) } } } ``` ### postDelayedFrameCallback12+ postDelayedFrameCallback(frameCallback: FrameCallback, delayTime: number): void 注册一个回调，在延迟一段时间后的下一帧进行渲染时执行。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------------------------- | | frameCallback | [FrameCallback](#framecallback12) | 是 | 下一帧需要执行的回调。 | | delayTime | number | 是 | 延迟的时间，以毫秒为单位。传入null、undefined或小于0的值，会按0处理。 | **示例：** ```ts import {FrameCallback } from '@kit.ArkUI'; class MyFrameCallback extends FrameCallback { private tag: string; constructor(tag: string) { super() this.tag = tag; } onFrame(frameTimeNanos: number) { console.info('MyFrameCallback ' + this.tag + ' ' + frameTimeNanos.toString()); } } @Entry @Component struct Index { build() { Row() { Button('点击触发postDelayedFrameCallback') .onClick(() => { this.getUIContext().postDelayedFrameCallback(new MyFrameCallback("delayTask"), 5); }) } } } ``` ### requireDynamicSyncScene12+ requireDynamicSyncScene(id: string): Array<DynamicSyncScene> 请求组件的动态帧率场景，用于自定义场景相关帧率配置。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | --------------------------------------- | | id | string | 是 | 节点对应的[组件标识](arkui-ts/ts-universal-attributes-component-id.md)。| **返回值：** | 类型 | 说明 | | ------ | -------------------------------------------- | | Array<DynamicSyncScene> | 获取DynamicSyncScene对象数组。 | **示例：** ```ts uiContext.DynamicSyncScene("dynamicSyncScene") ``` ### openBindSheet12+ openBindSheet\(bindSheetContent: ComponentContent\, sheetOptions?: SheetOptions, targetId?: number): Promise<void> 创建并弹出以bindSheetContent作为内容的半模态页面，使用Promise异步回调。通过该接口弹出的半模态页面样式完全按照bindSheetContent中设置的样式显示。 > **说明：** > > 1. 使用该接口时，若未传入有效的targetId，则不支持设置SheetOptions.preferType为POPUP模式、不支持设置SheetOptions.mode为EMBEDDED模式。 > > 2. 由于[updateBindSheet](#updatebindsheet12)和[closeBindSheet](#closebindsheet12)依赖bindSheetContent去更新或者关闭指定的半模态页面，开发者需自行维护传入的bindSheetContent。 > > 3. 不支持设置SheetOptions.UIContext。 > **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | bindSheetContent | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | 半模态页面中显示的组件内容。 | | sheetOptions | [SheetOptions](arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions) | 否 | 半模态页面样式。
**说明：**
1. 不支持设置SheetOptions.uiContext，该属性的值固定为当前实例的UIContext。
2. 若不传递targetId，则不支持设置SheetOptions.preferType为POPUP样式，若设置了POPUP样式则使用CENTER样式替代。
3. 若不传递targetId，则不支持设置SheetOptions.mode为EMBEDDED模式，默认为OVERLAY模式。
4. 其余属性的默认值参考[SheetOptions](arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions)文档。 | | targetId | number | 否 | 需要绑定组件的ID，若不指定则不绑定任何组件。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[半模态错误码](errorcode-bindSheet.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 120001 | The bindSheetContent is incorrect. | | 120002 | The bindSheetContent already exists. | | 120004 | The targetId does not exist. | | 120005 | The node of targetId is not in the component tree. | | 120006 | The node of targetId is not a child of the page node or NavDestination node. | **示例：** ```ts import { FrameNode, ComponentContent } from "@kit.ArkUI"; import { BusinessError } from '@kit.BasicServicesKit'; class Params { text: string = "" constructor(text: string) { this.text = text; } } let contentNode: ComponentContent; let gUIContext: UIContext; @Builder function buildText(params: Params) { Column() { Text(params.text) Button('Update BindSheet') .fontSize(20) .onClick(() => { gUIContext.updateBindSheet(contentNode, { backgroundColor: Color.Pink, }, true) .then(() => { console.info('updateBindSheet success'); }) .catch((err: BusinessError) => { console.info('updateBindSheet error: ' + err.code + ' ' + err.message); }) }) Button('Close BindSheet') .fontSize(20) .onClick(() => { gUIContext.closeBindSheet(contentNode) .then(() => { console.info('closeBindSheet success'); }) .catch((err: BusinessError) => { console.info('closeBindSheet error: ' + err.code + ' ' + err.message); }) }) } } @Entry @Component struct UIContextBindSheet { @State message: string = 'BindSheet'; aboutToAppear() { gUIContext = this.getUIContext(); contentNode = new ComponentContent(this.getUIContext(), wrapBuilder(buildText), new Params(this.message)); } build() { RelativeContainer() { Column() { Button('Open BindSheet') .fontSize(20) .onClick(() => { let uiContext = this.getUIContext(); let uniqueId = this.getUniqueId(); let frameNode: FrameNode | null = uiContext.getFrameNodeByUniqueId(uniqueId); let targetId = frameNode?.getFirstChild()?.getUniqueId(); uiContext.openBindSheet(contentNode, { height: SheetSize.MEDIUM, backgroundColor: Color.Green, title: { title: "Title", subtitle: "subtitle" } }, targetId) .then(() => { console.info('openBindSheet success'); }) .catch((err: BusinessError) => { console.info('openBindSheet error: ' + err.code + ' ' + err.message); }) }) } } .height('100%') .width('100%') } } ``` ### updateBindSheet12+ updateBindSheet\(bindSheetContent: ComponentContent\, sheetOptions: SheetOptions, partialUpdate?: boolean ): Promise<void> 更新bindSheetContent对应的半模态页面的样式，使用Promise异步回调。 > **说明：** > > 不支持更新SheetOptions.UIContext、SheetOptions.mode、回调函数。 > **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | bindSheetContent | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | 半模态页面中显示的组件内容。 | | sheetOptions | [SheetOptions](arkui-ts/ts-universal-attributes-sheet-transition.md#sheetoptions) | 是 | 半模态页面样式。
**说明：**
不支持更新SheetOptions.uiContext、SheetOptions.mode、回调函数。 | | partialUpdate | boolean | 否 | 半模态页面更新方式, 默认值为false。
**说明：**
1. true为增量更新，保留当前值，更新SheetOptions中的指定属性。
2. false为全量更新，除SheetOptions中的指定属性，其他属性恢复默认值。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[半模态错误码](errorcode-bindSheet.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 120001 | The bindSheetContent is incorrect. | | 120003 | The bindSheetContent cannot be found. | **示例：** ```ts import { FrameNode, ComponentContent } from "@kit.ArkUI"; import { BusinessError } from '@kit.BasicServicesKit'; class Params { text: string = "" constructor(text: string) { this.text = text; } } let contentNode: ComponentContent; let gUIContext: UIContext; @Builder function buildText(params: Params) { Column() { Text(params.text) Button('Update BindSheet') .fontSize(20) .onClick(() => { gUIContext.updateBindSheet(contentNode, { backgroundColor: Color.Pink, }, true) .then(() => { console.info('updateBindSheet success'); }) .catch((err: BusinessError) => { console.info('updateBindSheet error: ' + err.code + ' ' + err.message); }) }) Button('Close BindSheet') .fontSize(20) .onClick(() => { gUIContext.closeBindSheet(contentNode) .then(() => { console.info('closeBindSheet success'); }) .catch((err: BusinessError) => { console.info('closeBindSheet error: ' + err.code + ' ' + err.message); }) }) } } @Entry @Component struct UIContextBindSheet { @State message: string = 'BindSheet'; aboutToAppear() { gUIContext = this.getUIContext(); contentNode = new ComponentContent(this.getUIContext(), wrapBuilder(buildText), new Params(this.message)); } build() { RelativeContainer() { Column() { Button('Open BindSheet') .fontSize(20) .onClick(() => { let uiContext = this.getUIContext(); let uniqueId = this.getUniqueId(); let frameNode: FrameNode | null = uiContext.getFrameNodeByUniqueId(uniqueId); let targetId = frameNode?.getFirstChild()?.getUniqueId(); uiContext.openBindSheet(contentNode, { height: SheetSize.MEDIUM, backgroundColor: Color.Green, title: { title: "Title", subtitle: "subtitle" } }, targetId) .then(() => { console.info('openBindSheet success'); }) .catch((err: BusinessError) => { console.info('openBindSheet error: ' + err.code + ' ' + err.message); }) }) } } .height('100%') .width('100%') } } ``` ### closeBindSheet12+ closeBindSheet\(bindSheetContent: ComponentContent\): Promise<void> 关闭bindSheetContent对应的半模态页面，使用Promise异步回调。 > **说明：** > > 使用此接口关闭半模态页面时，不会触发shouldDismiss回调。 > **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | bindSheetContent | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | 半模态页面中显示的组件内容。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[半模态错误码](errorcode-bindSheet.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 120001 | The bindSheetContent is incorrect. | | 120003 | The bindSheetContent cannot be found. | **示例：** ```ts import { FrameNode, ComponentContent } from "@kit.ArkUI"; import { BusinessError } from '@kit.BasicServicesKit'; class Params { text: string = "" constructor(text: string) { this.text = text; } } let contentNode: ComponentContent; let gUIContext: UIContext; @Builder function buildText(params: Params) { Column() { Text(params.text) Button('Update BindSheet') .fontSize(20) .onClick(() => { gUIContext.updateBindSheet(contentNode, { backgroundColor: Color.Pink, }, true) .then(() => { console.info('updateBindSheet success'); }) .catch((err: BusinessError) => { console.info('updateBindSheet error: ' + err.code + ' ' + err.message); }) }) Button('Close BindSheet') .fontSize(20) .onClick(() => { gUIContext.closeBindSheet(contentNode) .then(() => { console.info('closeBindSheet success'); }) .catch((err: BusinessError) => { console.info('closeBindSheet error: ' + err.code + ' ' + err.message); }) }) } } @Entry @Component struct UIContextBindSheet { @State message: string = 'BindSheet'; aboutToAppear() { gUIContext = this.getUIContext(); contentNode = new ComponentContent(this.getUIContext(), wrapBuilder(buildText), new Params(this.message)); } build() { RelativeContainer() { Column() { Button('Open BindSheet') .fontSize(20) .onClick(() => { let uiContext = this.getUIContext(); let uniqueId = this.getUniqueId(); let frameNode: FrameNode | null = uiContext.getFrameNodeByUniqueId(uniqueId); let targetId = frameNode?.getFirstChild()?.getUniqueId(); uiContext.openBindSheet(contentNode, { height: SheetSize.MEDIUM, backgroundColor: Color.Green, title: { title: "Title", subtitle: "subtitle" } }, targetId) .then(() => { console.info('openBindSheet success'); }) .catch((err: BusinessError) => { console.info('openBindSheet error: ' + err.code + ' ' + err.message); }) }) } } .height('100%') .width('100%') } } ``` ### isFollowingSystemFontScale13+ isFollowingSystemFontScale(): boolean 获取当前UI上下文是否跟随系统字体倍率。 **原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | |---------|---------------| | boolean | 当前UI上下文是否跟随系统字体倍率。
true表示UI上下文跟随系统倍率，false表示UI上下文不跟随系统倍率。 | **示例：** ```ts uiContext.isFollowingSystemFontScale() ``` ### getMaxFontScale13+ getMaxFontScale(): number 获取当前UI上下文最大字体倍率。 **原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | |---------|-----------| | number | 当前UI上下文最大字体倍率。 | **示例：** ```ts uiContext.getMaxFontScale() ``` ### bindTabsToScrollable13+ bindTabsToScrollable(tabsController: TabsController, scroller: Scroller): void; 绑定Tabs组件和可滚动容器组件（支持[List](./arkui-ts/ts-container-list.md)、[Scroll](./arkui-ts/ts-container-scroll.md)、[Grid](./arkui-ts/ts-container-grid.md)、[WaterFlow](./arkui-ts/ts-container-waterflow.md)），当滑动可滚动容器组件时，会触发所有与其绑定的Tabs组件的TabBar的显示和隐藏动效，上滑隐藏，下滑显示。一个TabsController可与多个Scroller绑定，一个Scroller也可与多个TabsController绑定。 > **说明：** > > 当多个可滚动容器组件绑定了同一个Tabs组件时，只要滑动任意一个可滚动容器组件，就会触发TabBar的显示或隐藏。且当任意一个可滚动容器组件滑动到底部时，会立即触发TabBar的显示动效。因此不建议同时触发多个可滚动容器组件的滑动。 **原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | tabsController | [TabsController](./arkui-ts/ts-container-tabs.md#tabscontroller) | 是 | Tabs组件的控制器。 | | scroller | [Scroller](./arkui-ts/ts-container-scroll.md#scroller) | 是 | 可滚动容器组件的控制器。 | **示例：** ```ts @Entry @Component struct TabsExample { private arr: string[] = [] private parentTabsController: TabsController = new TabsController() private childTabsController: TabsController = new TabsController() private listScroller: Scroller = new Scroller() private parentScroller: Scroller = new Scroller() private childScroller: Scroller = new Scroller() aboutToAppear(): void { for (let i = 0; i < 20; i++) { this.arr.push(i.toString()) } let context = this.getUIContext() context.bindTabsToScrollable(this.parentTabsController, this.listScroller) context.bindTabsToScrollable(this.childTabsController, this.listScroller) context.bindTabsToNestedScrollable(this.parentTabsController, this.parentScroller, this.childScroller) } aboutToDisappear(): void { let context = this.getUIContext() context.unbindTabsFromScrollable(this.parentTabsController, this.listScroller) context.unbindTabsFromScrollable(this.childTabsController, this.listScroller) context.unbindTabsFromNestedScrollable(this.parentTabsController, this.parentScroller, this.childScroller) } build() { Tabs({ barPosition: BarPosition.End, controller: this.parentTabsController }) { TabContent() { Tabs({ controller: this.childTabsController }) { TabContent() { List({ space: 20, initialIndex: 0, scroller: this.listScroller }) { ForEach(this.arr, (item: string) => { ListItem() { Text(item) .width('100%') .height(100) .fontSize(16) .textAlign(TextAlign.Center) .borderRadius(10) .backgroundColor(Color.Gray) } }, (item: string) => item) } .scrollBar(BarState.Off) .width('90%') .height('100%') .contentStartOffset(56) .contentEndOffset(52) }.tabBar(SubTabBarStyle.of('顶部页签')) } .width('100%') .height('100%') .barOverlap(true) // 使TabBar叠加在TabContent上，当TabBar向上或向下隐藏后，原位置处不为空白 .clip(true) // 对超出Tabs组件范围的子组件进行裁剪，防止TabBar向上或向下隐藏后误触TabBar }.tabBar(BottomTabBarStyle.of($r('app.media.startIcon'), 'scroller联动多个TabsController')) TabContent() { Scroll(this.parentScroller) { List({ space: 20, initialIndex: 0, scroller: this.childScroller }) { ForEach(this.arr, (item: string) => { ListItem() { Text(item) .width('100%') .height(100) .fontSize(16) .textAlign(TextAlign.Center) .borderRadius(10) .backgroundColor(Color.Gray) } }, (item: string) => item) } .scrollBar(BarState.Off) .width('90%') .height('100%') .contentEndOffset(52) .nestedScroll({ scrollForward: NestedScrollMode.SELF_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST }) } .width('100%') .height('100%') .scrollBar(BarState.Off) .scrollable(ScrollDirection.Vertical) .edgeEffect(EdgeEffect.Spring) }.tabBar(BottomTabBarStyle.of($r('app.media.startIcon'), '嵌套的scroller联动TabsController')) } .width('100%') .height('100%') .barOverlap(true) // 使TabBar叠加在TabContent上，当TabBar向上或向下隐藏后，原位置处不为空白 .clip(true) // 对超出Tabs组件范围的子组件进行裁剪，防止TabBar向上或向下隐藏后误触TabBar } } ``` ![bindTabsToScrollable](figures/bindTabsToScrollable.gif) ### unbindTabsFromScrollable13+ unbindTabsFromScrollable(tabsController: TabsController, scroller: Scroller): void; 解除Tabs组件和可滚动容器组件的绑定。 **原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | tabsController | [TabsController](./arkui-ts/ts-container-tabs.md#tabscontroller) | 是 | Tabs组件的控制器。 | | scroller | [Scroller](./arkui-ts/ts-container-scroll.md#scroller) | 是 | 可滚动容器组件的控制器。 | **示例：** 参考[bindTabsToScrollable](#bindtabstoscrollable13)接口示例。 ### bindTabsToNestedScrollable13+ bindTabsToNestedScrollable(tabsController: TabsController, parentScroller: Scroller, childScroller: Scroller): void; 绑定Tabs组件和嵌套的可滚动容器组件（支持[List](./arkui-ts/ts-container-list.md)、[Scroll](./arkui-ts/ts-container-scroll.md)、[Grid](./arkui-ts/ts-container-grid.md)、[WaterFlow](./arkui-ts/ts-container-waterflow.md)），当滑动父组件或子组件时，会触发所有与其绑定的Tabs组件的TabBar的显示和隐藏动效，上滑隐藏，下滑显示。一个TabsController可与多个嵌套的Scroller绑定，嵌套的Scroller也可与多个TabsController绑定。 **原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | tabsController | [TabsController](./arkui-ts/ts-container-tabs.md#tabscontroller) | 是 | Tabs组件的控制器。 | | parentScroller | [Scroller](./arkui-ts/ts-container-scroll.md#scroller) | 是 | 可滚动容器组件的控制器。 | | childScroller | [Scroller](./arkui-ts/ts-container-scroll.md#scroller) | 是 | 可滚动容器组件的控制器。其对应组件为parentScroller对应组件的子组件，且组件间存在嵌套滚动关系。 | **示例：** 参考[bindTabsToScrollable](#bindtabstoscrollable13)接口示例。 ### unbindTabsFromNestedScrollable13+ unbindTabsFromNestedScrollable(tabsController: TabsController, parentScroller: Scroller, childScroller: Scroller): void; 解除Tabs组件和嵌套的可滚动容器组件的绑定。 **原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | tabsController | [TabsController](./arkui-ts/ts-container-tabs.md#tabscontroller) | 是 | Tabs组件的控制器。 | | parentScroller | [Scroller](./arkui-ts/ts-container-scroll.md#scroller) | 是 | 可滚动容器组件的控制器。 | | childScroller | [Scroller](./arkui-ts/ts-container-scroll.md#scroller) | 是 | 可滚动容器组件的控制器。其对应组件为parentScroller对应组件的子组件，且组件间存在嵌套滚动关系。 | **示例：** 参考[bindTabsToScrollable](#bindtabstoscrollable13)接口示例。 ### enableSwipeBack18+ enableSwipeBack(enabled: Optional\): void 设置是否支持应用内横向滑动返回上一级。 **原子化服务API:** 从API Version 18 开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Circle **参数：** | 参数名 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | enabled | boolean | 是 | 是否支持应用内横向滑动返回，默认值为true。| **示例：** ```js @Entry @Component struct Index { @State isEnable: boolean = true; build() { RelativeContainer() { Button(`enable swipe back: ${this.isEnable}`).onClick(() => { this.isEnable = !this.isEnable; this.getUIContext().enableSwipeBack(this.isEnable); }) } .height('100%') .width('100%') } } ``` ### getTextMenuController16+ getTextMenuController(): TextMenuController 获取[TextMenuController](#textmenucontroller16)对象，可通过该对象控制文本选择菜单。 **原子化服务API:** 从API Version 16 开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** |类型|说明| |----|----| |[TextMenuController](#textmenucontroller16)| 获取TextMenuController对象。| **示例：** 参考[TextMenuController](#textmenucontroller16)接口示例。 ### createUIContextWithoutWindow17+ static createUIContextWithoutWindow(context: common.UIAbilityContext | common.ExtensionContext) : UIContext | undefined 创建一个不依赖窗口的UI实例，并返回其UI上下文。该接口所创建的UI实例是单例。 > **说明：** > > 返回的UI上下文只可用于创建[自定义节点](../../ui/arkts-user-defined-node.md)，不能执行其他UI操作。 **原子化服务API:** 从API version 17 开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ----------- | | context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) \| common.[ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md) | 是 | [UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)或[ExtensionAbility](../apis-ability-kit/js-apis-app-ability-extensionAbility.md)所对应的上下文环境。 | **返回值：** |类型|说明| |----|----| | UIContext \| undefined | 创建的UI实例的上下文，创建失败时返回undefined。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[UI上下文](errorcode-uicontext.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes:
1. The number of parameters is incorrect.
2. Invalid parameter type of context. | | 100001 | Internal error. | **示例：** ```ts import { UIContext } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); let uiContext : UIContext | undefined = UIContext.createUIContextWithoutWindow(this.context); } // ...... } ``` ### destroyUIContextWithoutWindow17+ static destroyUIContextWithoutWindow(): void 销毁[createUIContextWithoutWindow](#createuicontextwithoutwindow17)创建的UI实例。 **原子化服务API:** 从API version 17 开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** ```ts UIContext.destroyUIContextWithoutWindow(); ``` ### dispatchKeyEvent15+ dispatchKeyEvent(node: number | string, event: KeyEvent): boolean 按键事件应分发给指定的组件。为了确保行为的可预测性，目标组件必须位于分发组件的子树中。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 参数名 | 类型 | 必填 | 说明 | | ------ | ----------------------------- | ---- | ------------------ | | node | number \| string | 是 | 组件的id或者节点UniqueID。 | | event |[KeyEvent](./arkui-ts/ts-universal-events-key.md#keyevent对象说明) | 是 | KeyEvent对象。 | **示例：** ```ts @Entry @Component struct Index { build() { Row() { Row() { Button('Button1').id('Button1').onKeyEvent((event) => { console.log("Button1"); return true }) Button('Button2').id('Button2').onKeyEvent((event) => { console.log("Button2"); return true }) } .width('100%') .height('100%') .id('Row1') .onKeyEventDispatch((event) => { let context = this.getUIContext(); context.getFocusController().requestFocus('Button1'); return context.dispatchKeyEvent('Button1', event); }) } .height('100%') .width('100%') .onKeyEventDispatch((event) => { if (event.type == KeyType.Down) { let context = this.getUIContext(); context.getFocusController().requestFocus('Row1'); return context.dispatchKeyEvent('Row1', event); } return true; }) } } ``` ## Font 以下API需先使用UIContext中的[getFont()](#getfont)方法获取到Font对象，再通过该对象调用对应方法。 ### registerFont registerFont(options: font.FontOptions): void 在字体管理中注册自定义字体。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ----------- | | options | [font.FontOptions](js-apis-font.md#fontoptions) | 是 | 注册的自定义字体信息。 | **示例：** ```ts import { Font } from '@kit.ArkUI'; let font:Font = uiContext.getFont(); font.registerFont({ familyName: 'medium', familySrc: '/font/medium.ttf' }); ``` ### getSystemFontList getSystemFontList(): Array\ 获取系统支持的字体名称列表。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | -------------- | --------- | | Array\ | 系统的字体名列表。 | > **说明：** > > 该接口仅在2in1设备上生效。 **示例：** ```ts import { Font } from '@kit.ArkUI'; let font:Font|undefined = uiContext.getFont(); if(font){ font.getSystemFontList() } ``` ### getFontByName getFontByName(fontName: string): font.FontInfo 根据传入的系统字体名称获取系统字体的相关信息。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | ------- | | fontName | string | 是 | 系统的字体名。 | **返回值：** | 类型 | 说明 | | ----------------------------------------- | -------------- | | [font.FontInfo](js-apis-font.md#fontinfo) | 字体的详细信息 | **示例：** ```ts import { Font } from '@kit.ArkUI'; let font:Font|undefined = uiContext.getFont(); if(font){ font.getFontByName('Sans Italic') } ``` ## Context12+ type Context = common.Context 当前组件所在Ability的上下文。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.Ability.AbilityRuntime.Core **模型约束：** 此接口仅可在Stage模型下使用。 | 类型 |说明 | | ------ | ------------------- | | [common.Context](../apis-ability-kit/js-apis-app-ability-common.md#context) |Context的具体类型为当前Ability关联的Context对象。| ## ComponentUtils 以下API需先使用UIContext中的[getComponentUtils()](#getcomponentutils)方法获取到ComponentUtils对象，再通过该对象调用对应方法。 ### getRectangleById getRectangleById(id: string): componentUtils.ComponentInfo 获取组件大小、位置、平移缩放旋转及仿射矩阵属性信息。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | --------- | | id | string | 是 | 组件唯一标识id。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | ------------------------------------------------ | | [componentUtils.ComponentInfo](js-apis-arkui-componentUtils.md#componentinfo) | 组件大小、位置、平移缩放旋转及仿射矩阵属性信息。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | ------ | ------------------- | | 100001 | UI execution context not found. | **示例：** ```ts import { ComponentUtils } from '@kit.ArkUI'; let componentUtils:ComponentUtils = uiContext.getComponentUtils(); let modePosition = componentUtils.getRectangleById("onClick"); let localOffsetWidth = modePosition.size.width; let localOffsetHeight = modePosition.size.height; ``` ## UIInspector 以下API需先使用UIContext中的[getUIInspector()](#getuiinspector)方法获取到UIInspector对象，再通过该对象调用对应方法。 ### createComponentObserver createComponentObserver(id: string): inspector.ComponentObserver 注册组件布局和组件绘制送显完成回调通知。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ------- | | id | string | 是 | 指定组件id，该id通过通用属性[id](./arkui-ts/ts-universal-attributes-component-id.md#id)或者[key](./arkui-ts/ts-universal-attributes-component-id.md#key12)设置。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | -------------------------------------------------- | | [inspector.ComponentObserver](js-apis-arkui-inspector.md#componentobserver) | 组件回调事件监听句柄，用于注册和取消注册监听回调。 | **示例：** ```ts import { UIInspector } from '@kit.ArkUI'; let inspector: UIInspector = uiContext.getUIInspector(); let listener = inspector.createComponentObserver('COMPONENT_ID'); ``` ## PageInfo12+ Router和NavDestination等页面信息，若无对应的Router或NavDestination页面信息，则对应属性为undefined。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | routerPageInfo | observer.[RouterPageInfo](js-apis-arkui-observer.md#routerpageinfo) | 否 | Router信息。 | | navDestinationInfo | observer.[NavDestinationInfo](js-apis-arkui-observer.md#navdestinationinfo) | 否 | NavDestination信息。 | ## UIObserver11+ 以下API需先使用UIContext中的[getUIObserver()](#getuiobserver11)方法获取到UIObserver对象，再通过该对象调用对应方法。 ### on('navDestinationUpdate')11+ on(type: 'navDestinationUpdate', callback: Callback\): void 监听NavDestination组件的状态变化。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'navDestinationUpdate'，即NavDestination组件的状态变化。 | | callback | Callback\ | 是 | 回调函数。返回当前的NavDestination组件状态。 | **示例：** ```ts // Index.ets // 演示 uiObserver.on('navDestinationUpdate', callback) // uiObserver.off('navDestinationUpdate', callback) @Component struct PageOne { build() { NavDestination() { Text("pageOne") }.title("pageOne") } } @Entry @Component struct Index { private stack: NavPathStack = new NavPathStack(); @Builder PageBuilder(name: string) { PageOne() } aboutToAppear() { this.getUIContext().getUIObserver().on('navDestinationUpdate', (info) => { console.info('NavDestination state update', JSON.stringify(info)); }); } aboutToDisappear() { this.getUIContext().getUIObserver().off('navDestinationUpdate'); } build() { Column() { Navigation(this.stack) { Button("push").onClick(() => { this.stack.pushPath({ name: "pageOne" }); }) } .title("Navigation") .navDestination(this.PageBuilder) } .width('100%') .height('100%') } } ``` ### off('navDestinationUpdate')11+ off(type: 'navDestinationUpdate', callback?: Callback\): void 取消监听NavDestination组件的状态变化。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'navDestinationUpdate'，即NavDestination组件的状态变化。 | | callback | Callback\ | 否 | 回调函数。返回当前的NavDestination组件状态。 | **示例：** 参考[uiObserver.on('navDestinationUpdate')](#onnavdestinationupdate11)示例。 ### on('navDestinationUpdate')11+ on(type: 'navDestinationUpdate', options: { navigationId: ResourceStr }, callback: Callback\): void 监听NavDestination组件的状态变化。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'navDestinationUpdate'，即NavDestination组件的状态变化。 | | options | { navigationId: [ResourceStr](arkui-ts/ts-types.md#resourcestr) } | 是 | 指定监听的Navigation的id。 | | callback | Callback\ | 是 | 回调函数。返回当前的NavDestination组件状态。 | **示例：** ```ts // Index.ets // 演示 uiObserver.on('navDestinationUpdate', navigationId, callback) // uiObserver.off('navDestinationUpdate', navigationId, callback) @Component struct PageOne { build() { NavDestination() { Text("pageOne") }.title("pageOne") } } @Entry @Component struct Index { private stack: NavPathStack = new NavPathStack(); @Builder PageBuilder(name: string) { PageOne() } aboutToAppear() { this.getUIContext().getUIObserver().on('navDestinationUpdate', { navigationId: "testId" }, (info) => { console.info('NavDestination state update', JSON.stringify(info)); }); } aboutToDisappear() { this.getUIContext().getUIObserver().off('navDestinationUpdate', { navigationId: "testId" }); } build() { Column() { Navigation(this.stack) { Button("push").onClick(() => { this.stack.pushPath({ name: "pageOne" }); }) } .id("testId") .title("Navigation") .navDestination(this.PageBuilder) } .width('100%') .height('100%') } } ``` ### off('navDestinationUpdate')11+ off(type: 'navDestinationUpdate', options: { navigationId: ResourceStr }, callback?: Callback\): void 取消监听NavDestination组件的状态变化。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'navDestinationUpdate'，即NavDestination组件的状态变化。 | | options | { navigationId: [ResourceStr](arkui-ts/ts-types.md#resourcestr) } | 是 | 指定监听的Navigation的id。 | | callback | Callback\ | 否 | 回调函数。返回当前的NavDestination组件状态。 | **示例：** 参考[uiObserver.on('navDestinationUpdate')](#onnavdestinationupdate11-1)示例。 ### on('scrollEvent')12+ on(type: 'scrollEvent', callback: Callback\): void 监听滚动事件的开始和结束。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'scrollEvent'，即滚动事件的开始和结束。 | | callback | Callback\ | 是 | 回调函数。返回滚动事件的信息。 | **示例：** 请参考[offscrollevent示例](#offscrollevent12-1) ### off('scrollEvent')12+ off(type: 'scrollEvent', callback?: Callback\): void 取消监听滚动事件的开始和结束。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'scrollEvent'，即滚动事件的开始和结束。 | | callback | Callback\ | 否 | 回调函数。返回滚动事件的信息。 | **示例：** 请参考[offscrollevent示例](#offscrollevent12-1) ### on('scrollEvent')12+ on(type: 'scrollEvent', options: observer.ObserverOptions, callback: Callback\): void 监听滚动事件的开始和结束。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'scrollEvent'，即滚动事件的开始和结束。 | | options | [observer.ObserverOptions](js-apis-arkui-observer.md#observeroptions12) | 是 | Observer选项，包含指定监听的滚动组件的id。 | | callback | Callback\ | 是 | 回调函数。返回滚动事件的信息。 | **示例：** 请参考[offscrollevent示例](#offscrollevent12-1) ### off('scrollEvent')12+ off(type: 'scrollEvent', options: observer.ObserverOptions, callback?: Callback\): void 取消监听滚动事件的开始和结束。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'scrollEvent'，即滚动事件的开始和结束。 | | options | [observer.ObserverOptions](js-apis-arkui-observer.md#observeroptions12) | 是 | Observer选项，包含指定监听的滚动组件的id。 | | callback | Callback\ | 否 | 回调函数。返回滚动事件的信息。 | **示例：** ```ts import { UIObserver } from '@kit.ArkUI' @Entry @Component struct Index { scroller: Scroller = new Scroller() observer: UIObserver = new UIObserver() private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7] build() { Row() { Column() { Scroll(this.scroller) { Column() { ForEach(this.arr, (item: number) => { Text(item.toString()) .width('90%') .height(150) .backgroundColor(0xFFFFFF) .borderRadius(15) .fontSize(16) .textAlign(TextAlign.Center) .margin({ top: 10 }) }, (item: string) => item) }.width('100%') } .id("testId") .height('80%') } .width('100%') Row() { Button('UIObserver on') .onClick(() => { this.observer.on('scrollEvent', (info) => { console.info('scrollEventInfo', JSON.stringify(info)); }); }) Button('UIObserver off') .onClick(() => { this.observer.off('scrollEvent'); }) } Row() { Button('UIObserverWithId on') .onClick(() => { this.observer.on('scrollEvent', { id:"testId" }, (info) => { console.info('scrollEventInfo', JSON.stringify(info)); }); }) Button('UIObserverWithId off') .onClick(() => { this.observer.off('scrollEvent', { id:"testId" }); }) } } .height('100%') } } ``` ### on('routerPageUpdate')11+ on(type: 'routerPageUpdate', callback: Callback\): void 监听router中page页面的状态变化。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'routerPageUpdate'，即router中page页面的状态变化。 | | callback | Callback\ | 是 | 回调函数。携带pageInfo，返回当前的page页面状态。 | **示例：** ```ts import { UIContext, UIObserver } from '@kit.ArkUI'; let observer:UIObserver = this.getUIContext().getUIObserver(); observer.on('routerPageUpdate', (info) => { console.info('RouterPage state updated, called by ' + `${info.name}`); }); ``` ### off('routerPageUpdate')11+ off(type: 'routerPageUpdate', callback?: Callback\): void 取消监听router中page页面的状态变化。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'routerPageUpdate'，即router中page页面的状态变化。 | | callback | Callback\ | 否 | 需要被注销的回调函数。 | **示例：** ```ts import { UIContext, UIObserver } from '@kit.ArkUI'; let observer:UIObserver = this.getUIContext().getUIObserver(); function callBackFunc(info:observer.RouterPageInfo) {}; // callBackFunc is defined and used before observer.off('routerPageUpdate', callBackFunc); ``` ### on('densityUpdate')12+ on(type: 'densityUpdate', callback: Callback\): void 监听屏幕像素密度变化。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'densityUpdate'，即屏幕像素密度变化。 | | callback | Callback\ | 是 | 回调函数。携带densityInfo，返回变化后的屏幕像素密度。 | ```ts import { uiObserver } from '@kit.ArkUI'; @Entry @Component struct Index { @State density: number = 0; @State message: string = '未注册监听' densityUpdateCallback = (info: uiObserver.DensityInfo) => { this.density = info.density; this.message = '变化后的DPI：' + this.density.toString(); } build() { Column() { Text(this.message) .fontSize(24) .fontWeight(FontWeight.Bold) Button('注册屏幕像素密度变化监听') .onClick(() => { this.message = '已注册监听' this.getUIContext().getUIObserver().on('densityUpdate', this.densityUpdateCallback); }) } } } ``` ### off('densityUpdate')12+ off(type: 'densityUpdate', callback?: Callback\): void 取消监听屏幕像素密度的变化。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------- | | type | string | 是 | 监听事件，固定为'densityUpdate'，即屏幕像素密度变化。 | | callback | Callback\ | 否 | 需要被注销的回调函数。若不指定具体的回调函数，则注销该UIContext下所有densityUpdate事件监听。 | ```ts import { uiObserver } from '@kit.ArkUI'; @Entry @Component struct Index { @State density: number = 0; @State message: string = '未注册监听' densityUpdateCallback = (info: uiObserver.DensityInfo) => { this.density = info.density; this.message = '变化后的DPI：' + this.density.toString(); } build() { Column() { Text(this.message) .fontSize(24) .fontWeight(FontWeight.Bold) Button('注册屏幕像素密度变化监听') .margin({ bottom: 10 }) .onClick(() => { this.message = '已注册监听' this.getUIContext().getUIObserver().on('densityUpdate', this.densityUpdateCallback); }) Button('解除注册屏幕像素密度变化监听') .onClick(() => { this.message = '未注册监听' this.getUIContext().getUIObserver().off('densityUpdate', this.densityUpdateCallback); }) } } } ``` ### on('willDraw')12+ on(type: 'willDraw', callback: Callback\): void 监听每一帧绘制指令下发情况。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'willDraw'，即是否将要绘制。 | | callback | Callback\ | 是 | 回调函数。 | ```ts import { uiObserver } from '@kit.ArkUI'; @Entry @Component struct Index { willDrawCallback = () => { console.info("willDraw指令下发"); } build() { Column() { Button('注册绘制指令下发监听') .onClick(() => { this.getUIContext().getUIObserver().on('willDraw', this.willDrawCallback); }) } } } ``` ### off('willDraw')12+ off(type: 'willDraw', callback?: Callback\): void 取消监听每一帧绘制指令下发情况。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'willDraw'，即是否将要绘制。 | | callback | Callback\ | 否 | 需要被注销的回调函数。 | ```ts import { uiObserver } from '@kit.ArkUI'; @Entry @Component struct Index { willDrawCallback = () => { console.info("willDraw指令下发") } build() { Column() { Button('注册绘制指令下发监听') .margin({ bottom: 10 }) .onClick(() => { this.getUIContext().getUIObserver().on('willDraw', this.willDrawCallback); }) Button('解除注册绘制指令下发监听') .onClick(() => { this.getUIContext().getUIObserver().off('willDraw', this.willDrawCallback); }) } } } ``` ### on('didLayout')12+ on(type: 'didLayout', callback: Callback\): void 监听每一帧布局完成情况。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'didLayout'，即是否布局完成。 | | callback | Callback\ | 是 | 回调函数。 | ```ts import { uiObserver } from '@kit.ArkUI'; @Entry @Component struct Index { didLayoutCallback = () => { console.info("layout布局完成"); } build() { Column() { Button('注册布局完成监听') .onClick(() => { this.getUIContext().getUIObserver().on('didLayout', this.didLayoutCallback); }) } } } ``` ### off('didLayout')12+ off(type: 'didLayout', callback?: Callback\): void 取消监听每一帧布局完成情况。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'didLayout'，即是否将要绘制。 | | callback | Callback\ | 否 | 需要被注销的回调函数。 | ```ts import { uiObserver } from '@kit.ArkUI'; @Entry @Component struct Index { didLayoutCallback = () => { console.info("layout布局完成") } build() { Column() { Button('注册布局完成监听') .margin({ bottom: 10 }) .onClick(() => { this.getUIContext().getUIObserver().on('didLayout', this.didLayoutCallback); }) Button('解除注册注册布局完成监听') .onClick(() => { this.getUIContext().getUIObserver().off('didLayout', this.didLayoutCallback); }) } } } ``` ### on('navDestinationSwitch')12+ on(type: 'navDestinationSwitch', callback: Callback\): void 监听Navigation的页面切换事件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'navDestinationSwitch'，即Navigation的页面切换事件。 | | callback | Callback\ | 是 | 回调函数。携带NavDestinationSwitchInfo，返回页面切换事件的信息。 | **示例：** ```ts // Index.ets // 演示 UIObserver.on('navDestinationSwitch', callback) // UIObserver.off('navDestinationSwitch', callback) import { uiObserver } from '@kit.ArkUI'; @Component struct PageOne { build() { NavDestination() { Text("pageOne") }.title("pageOne") } } function callBackFunc(info: uiObserver.NavDestinationSwitchInfo) { console.info(`testTag navDestinationSwitch from: ${JSON.stringify(info.from)} to: ${JSON.stringify(info.to)}`) } @Entry @Component struct Index { private stack: NavPathStack = new NavPathStack(); @Builder PageBuilder(name: string) { PageOne() } aboutToAppear() { let obs = this.getUIContext().getUIObserver(); obs.on('navDestinationSwitch', callBackFunc); } aboutToDisappear() { let obs = this.getUIContext().getUIObserver(); obs.off('navDestinationSwitch', callBackFunc); } build() { Column() { Navigation(this.stack) { Button("push").onClick(() => { this.stack.pushPath({name: "pageOne"}); }) } .title("Navigation") .navDestination(this.PageBuilder) } .width('100%') .height('100%') } } ``` ### off('navDestinationSwitch')12+ off(type: 'navDestinationSwitch', callback?: Callback\): void 取消监听Navigation的页面切换事件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'navDestinationSwitch'，即Navigation的页面切换事件。 | | callback | Callback\ | 否 | 需要被注销的回调函数。 | **示例代码参考上述UIObserver.on('navDestinationSwitch')接口的示例代码** ### on('navDestinationSwitch')12+ on(type: 'navDestinationSwitch', observerOptions: observer.NavDestinationSwitchObserverOptions, callback: Callback\): void 监听Navigation的页面切换事件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'navDestinationSwitch'，即Navigation的页面切换事件。 | | observerOptions | observer.[NavDestinationSwitchObserverOptions](js-apis-arkui-observer.md#navdestinationswitchobserveroptions12) | 是 | 监听选项。 | | callback | Callback\ | 是 | 回调函数。携带NavDestinationSwitchInfo，返回页面切换事件的信息。 | **示例：** ```ts // Index.ets // 演示 UIObserver.on('navDestinationSwitch', NavDestinationSwitchObserverOptions, callback) // UIObserver.off('navDestinationSwitch', NavDestinationSwitchObserverOptions, callback) import { uiObserver } from '@kit.ArkUI'; @Component struct PageOne { build() { NavDestination() { Text("pageOne") }.title("pageOne") } } function callBackFunc(info: uiObserver.NavDestinationSwitchInfo) { console.info(`testTag navDestinationSwitch from: ${JSON.stringify(info.from)} to: ${JSON.stringify(info.to)}`) } @Entry @Component struct Index { private stack: NavPathStack = new NavPathStack(); @Builder PageBuilder(name: string) { PageOne() } aboutToAppear() { let obs = this.getUIContext().getUIObserver(); obs.on('navDestinationSwitch', { navigationId: "myNavId" }, callBackFunc) } aboutToDisappear() { let obs = this.getUIContext().getUIObserver(); obs.off('navDestinationSwitch', { navigationId: "myNavId" }, callBackFunc) } build() { Column() { Navigation(this.stack) { Button("push").onClick(() => { this.stack.pushPath({name: "pageOne"}); }) } .id("myNavId") .title("Navigation") .navDestination(this.PageBuilder) } .width('100%') .height('100%') } } ``` ### off('navDestinationSwitch')12+ off(type: 'navDestinationSwitch', observerOptions: observer.NavDestinationSwitchObserverOptions, callback?: Callback\): void 取消监听Navigation的页面切换事件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'navDestinationSwitch'，即Navigation的页面切换事件。 | | observerOptions | observer.[NavDestinationSwitchObserverOptions](js-apis-arkui-observer.md#navdestinationswitchobserveroptions12) | 是 | 监听选项。 | | callback | Callback\ | 否 | 需要被注销的回调函数。 | **示例代码参考上述UIObserver.on('navDestinationSwitch')接口的示例代码** ### on('willClick')12+ on(type: 'willClick', callback: GestureEventListenerCallback): void 监听点击事件指令下发情况。暂不支持屏幕朗读触控模式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'willClick'，用于监听点击事件指令下发情况，所注册回调将于点击事件触发前触发。 | | callback | [GestureEventListenerCallback](#gestureeventlistenercallback12) | 是 | 回调函数。可以获得点击事件的GestureEvent和组件的FrameNode。 | **示例：** ```ts // 在页面Component中使用 import { UIContext, UIObserver, FrameNode } from '@kit.ArkUI'; // callback是开发者定义的监听回调函数 let callback = (event: GestureEvent, frameNode?: FrameNode) => {}; let observer: UIObserver = this.getUIContext().getUIObserver(); observer.on('willClick', callback); ``` ### off('willClick')12+ off(type: 'willClick', callback?: GestureEventListenerCallback): void 取消监听点击事件指令下发情况。暂不支持屏幕朗读触控模式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | | type | string | 是 | 监听事件，固定为'willClick'，即点击事件指令下发情况。 | | callback | [GestureEventListenerCallback](#gestureeventlistenercallback12) | 否 | 需要被注销的回调函数。 | **示例：** ```ts // 在页面Component中使用 import { UIContext, UIObserver, FrameNode } from '@kit.ArkUI'; // callback是开发者定义的监听回调函数 let callback = (event: GestureEvent, frameNode?: FrameNode) => {}; let observer: UIObserver = this.getUIContext().getUIObserver(); observer.off('willClick', callback); ``` ### on('didClick')12+ on(type: 'didClick', callback: GestureEventListenerCallback): void 监听点击事件指令下发情况。暂不支持屏幕朗读触控模式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'didClick'，用于监听点击事件指令下发情况，所注册回调将于点击事件触发后触发。 | | callback | [GestureEventListenerCallback](#gestureeventlistenercallback12) | 是 | 回调函数。可以获得点击事件的GestureEvent和组件的FrameNode。 | **示例：** ```ts // 在页面Component中使用 import { UIContext, UIObserver, FrameNode } from '@kit.ArkUI'; // callback是开发者定义的监听回调函数 let callback = (event: GestureEvent, frameNode?: FrameNode) => {}; let observer: UIObserver = this.getUIContext().getUIObserver(); observer.on('didClick', callback); ``` ### off('didClick')12+ off(type: 'didClick', callback?: GestureEventListenerCallback): void 取消监听点击事件指令下发情况。暂不支持屏幕朗读触控模式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | | type | string | 是 | 监听事件，固定为'didClick'，即点击事件指令下发情况。 | | callback | [GestureEventListenerCallback](#gestureeventlistenercallback12) | 否 | 需要被注销的回调函数。 | **示例：** ```ts // 在页面Component中使用 import { UIContext, UIObserver, FrameNode } from '@kit.ArkUI'; // callback是开发者定义的监听回调函数 let callback = (event: GestureEvent, frameNode?: FrameNode) => {}; let observer: UIObserver = this.getUIContext().getUIObserver(); observer.off('didClick', callback); ``` ### on('willClick')12+ on(type: 'willClick', callback: ClickEventListenerCallback): void 监听点击事件指令下发情况。暂不支持屏幕朗读触控模式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'willClick'，用于监听点击事件指令下发情况，所注册回调将于点击事件触发前触发。 | | callback | [ClickEventListenerCallback](#clickeventlistenercallback12) | 是 | 回调函数。可以获得点击事件的ClickEvent和组件的FrameNode。 | **示例：** ```ts // 在页面Component中使用 import { UIContext, UIObserver, FrameNode } from '@kit.ArkUI'; // callback是开发者定义的监听回调函数 let callback = (event: ClickEvent, frameNode?: FrameNode) => {}; let observer: UIObserver = this.getUIContext().getUIObserver(); observer.on('willClick', callback); ``` ### off('willClick')12+ off(type: 'willClick', callback?: ClickEventListenerCallback): void 取消监听点击事件指令下发情况。暂不支持屏幕朗读触控模式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | | type | string | 是 | 监听事件，固定为'willClick'，即点击事件指令下发情况。 | | callback | [ClickEventListenerCallback](#clickeventlistenercallback12) | 否 | 需要被注销的回调函数。 | **示例：** ```ts // 在页面Component中使用 import { UIContext, UIObserver, FrameNode } from '@kit.ArkUI'; // callback是开发者定义的监听回调函数 let callback = (event: ClickEvent, frameNode?: FrameNode) => {}; let observer: UIObserver = this.getUIContext().getUIObserver(); observer.off('willClick', callback); ``` ### on('didClick')12+ on(type: 'didClick', callback: ClickEventListenerCallback): void 监听点击事件指令下发情况。暂不支持屏幕朗读触控模式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'didClick'，用于监听点击事件指令下发情况，所注册回调将于点击事件触发后触发。 | | callback | [ClickEventListenerCallback](#clickeventlistenercallback12) | 是 | 回调函数。可以获得点击事件的ClickEvent和组件的FrameNode。 | **示例：** ```ts // 在页面Component中使用 import { UIContext, UIObserver, FrameNode } from '@kit.ArkUI'; // callback是开发者定义的监听回调函数 let callback = (event: ClickEvent, frameNode?: FrameNode) => {}; let observer: UIObserver = this.getUIContext().getUIObserver(); observer.on('didClick', callback); ``` ### off('didClick')12+ off(type: 'didClick', callback?: ClickEventListenerCallback): void 取消监听点击事件指令下发情况。暂不支持屏幕朗读触控模式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------------------- | ---- | ---------------------------------------------------- | | type | string | 是 | 监听事件，固定为'didClick'，即点击事件指令下发情况。 | | callback | [ClickEventListenerCallback](#clickeventlistenercallback12) | 否 | 需要被注销的回调函数。 | **示例：** ```ts // 在页面Component中使用 import { UIContext, UIObserver, FrameNode } from '@kit.ArkUI'; // callback是开发者定义的监听回调函数 let callback = (event: ClickEvent, frameNode?: FrameNode) => {}; let observer: UIObserver = this.getUIContext().getUIObserver(); observer.off('didClick', callback); ``` ### on('tabContentUpdate')12+ on(type: 'tabContentUpdate', callback: Callback\): void 监听TabContent页面的切换事件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'tabContentUpdate'，即TabContent页面的切换事件。 | | callback | Callback\ | 是 | 回调函数。携带TabContentInfo，返回TabContent页面切换事件的信息。 | **示例：** ```ts import { uiObserver } from '@kit.ArkUI'; function callbackFunc(info: uiObserver.TabContentInfo) { console.info('tabContentUpdate', JSON.stringify(info)); } @Entry @Component struct TabsExample { aboutToAppear(): void { let observer = this.getUIContext().getUIObserver(); observer.on('tabContentUpdate', callbackFunc); } aboutToDisappear(): void { let observer = this.getUIContext().getUIObserver(); observer.off('tabContentUpdate', callbackFunc); } build() { Column() { Tabs() { TabContent() { Column().width('100%').height('100%').backgroundColor('#00CB87') }.tabBar('green').id('tabContentId0') TabContent() { Column().width('100%').height('100%').backgroundColor('#007DFF') }.tabBar('blue').id('tabContentId1') TabContent() { Column().width('100%').height('100%').backgroundColor('#FFBF00') }.tabBar('yellow').id('tabContentId2') TabContent() { Column().width('100%').height('100%').backgroundColor('#E67C92') }.tabBar('pink').id('tabContentId3') } .width(360) .height(296) .backgroundColor('#F1F3F5') .id('tabsId') }.width('100%') } } ``` ### off('tabContentUpdate')12+ off(type: 'tabContentUpdate', callback?: Callback\): void 取消监听TabContent页面的切换事件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'tabContentUpdate'，即TabContent页面的切换事件。 | | callback | Callback\ | 否 | 需要被注销的回调函数。 | **示例：** 参考[on('tabContentUpdate')](#ontabcontentupdate12)接口示例。 ### on('tabContentUpdate')12+ on(type: 'tabContentUpdate', options: observer.ObserverOptions, callback: Callback\): void 监听TabContent页面的切换事件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'tabContentUpdate'，即TabContent页面的切换事件。 | | options | observer.[ObserverOptions](js-apis-arkui-observer.md#observeroptions12) | 是 | 指定监听的Tabs组件的id。 | | callback | Callback\ | 是 | 回调函数。携带TabContentInfo，返回TabContent页面切换事件的信息。 | **示例：** ```ts import { uiObserver } from '@kit.ArkUI'; function callbackFunc(info: uiObserver.TabContentInfo) { console.info('tabContentUpdate', JSON.stringify(info)); } @Entry @Component struct TabsExample { aboutToAppear(): void { let observer = this.getUIContext().getUIObserver(); observer.on('tabContentUpdate', { id: 'tabsId' }, callbackFunc); } aboutToDisappear(): void { let observer = this.getUIContext().getUIObserver(); observer.off('tabContentUpdate', { id: 'tabsId' }, callbackFunc); } build() { Column() { Tabs() { TabContent() { Column().width('100%').height('100%').backgroundColor('#00CB87') }.tabBar('green').id('tabContentId0') TabContent() { Column().width('100%').height('100%').backgroundColor('#007DFF') }.tabBar('blue').id('tabContentId1') TabContent() { Column().width('100%').height('100%').backgroundColor('#FFBF00') }.tabBar('yellow').id('tabContentId2') TabContent() { Column().width('100%').height('100%').backgroundColor('#E67C92') }.tabBar('pink').id('tabContentId3') } .width(360) .height(296) .backgroundColor('#F1F3F5') .id('tabsId') }.width('100%') } } ``` ### off('tabContentUpdate')12+ off(type: 'tabContentUpdate', options: observer.ObserverOptions, callback?: Callback\): void 取消监听TabContent页面的切换事件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'tabContentUpdate'，即TabContent页面的切换事件。 | | options | observer.[ObserverOptions](js-apis-arkui-observer.md#observeroptions12) | 是 | 指定监听的Tabs组件的id。 | | callback | Callback\ | 否 | 需要被注销的回调函数。 | **示例：** 参考[on('tabContentUpdate')](#ontabcontentupdate12-1)接口示例。 ## GestureEventListenerCallback12+ type GestureEventListenerCallback = (event: GestureEvent, node?: FrameNode) => void ArkTS GestureEvent事件监听函数类型。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | --------------------------- | | event | [GestureEvent](../apis-arkui/arkui-ts/ts-gesture-settings.md#gestureevent对象说明) | 是 | 触发事件监听的手势事件的相关信息。 | | node | [FrameNode](js-apis-arkui-frameNode.md#framenode) | 否 | 触发事件监听的手势事件所绑定的组件。 | ## ClickEventListenerCallback12+ type ClickEventListenerCallback = (event: ClickEvent, node?: FrameNode) => void ArkTS GestureEvent事件监听函数类型。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | --------------------------- | | event | [ClickEvent](../apis-arkui/arkui-ts/ts-universal-events-click.md#clickevent对象说明) | 是 | 触发事件监听的点击事件的相关信息。 | | node | [FrameNode](js-apis-arkui-frameNode.md#framenode) | 否 | 触发事件监听的点击事件所绑定的组件。 | ## MediaQuery 以下API需先使用UIContext中的[getMediaQuery()](#getmediaquery)方法获取到MediaQuery对象，再通过该对象调用对应方法。 ### matchMediaSync matchMediaSync(condition: string): mediaQuery.MediaQueryListener 设置媒体查询的查询条件，并返回对应的监听句柄。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ---------------------------------------- | | condition | string | 是 | 媒体事件的匹配条件，具体可参考[媒体查询语法规则](../../ui/arkts-layout-development-media-query.md#语法规则)。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | -------------------------------------------- | | [mediaQuery.MediaQueryListener](js-apis-mediaquery.md#mediaquerylistener) | 媒体事件监听句柄，用于注册和去注册监听回调。 | **示例：** ```ts import { MediaQuery } from '@kit.ArkUI'; let mediaquery: MediaQuery = uiContext.getMediaQuery(); let listener = mediaquery.matchMediaSync('(orientation: landscape)'); //监听横屏事件 ``` ## Router 以下API需先使用UIContext中的[getRouter()](#getrouter)方法获取到Router对象，再通过该对象调用对应方法。 ### pushUrl pushUrl(options: router.RouterOptions): Promise<void> 跳转到应用内的指定页面，通过Promise获取跳转异常的返回结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | --------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 是 | 跳转页面描述信息。 | **返回值：** | 类型 | 说明 | | ------------------- | ------- | | Promise<void> | 异常返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | | 100002 | Uri error. The URI of the page to redirect is incorrect or does not exist. | | 100003 | Page stack error. Too many pages are pushed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit' @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().pushUrl({ url: 'pages/routerpage2', params: { data1: 'message', data2: { data3: [123, 456, 789] } } }) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### pushUrl pushUrl(options: router.RouterOptions, callback: AsyncCallback<void>): void 跳转到应用内的指定页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 是 | 跳转页面描述信息。 | | callback | AsyncCallback<void> | 是 | 异常响应回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | | 100002 | Uri error. The URI of the page to redirect is incorrect or does not exist. | | 100003 | Page stack error. Too many pages are pushed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit' @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().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'); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### pushUrl pushUrl(options: router.RouterOptions, mode: router.RouterMode): Promise<void> 跳转到应用内的指定页面，通过Promise获取跳转异常的返回结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ---------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 是 | 跳转页面描述信息。 | | mode | [router.RouterMode](js-apis-router.md#routermode9) | 是 | 跳转页面使用的模式。 | **返回值：** | 类型 | 说明 | | ------------------- | ------- | | Promise<void> | 异常返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | | 100002 | Uri error. The URI of the page to redirect is incorrect or does not exist. | | 100003 | Page stack error. Too many pages are pushed. | **示例：** ```ts import { router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit' class RouterTmp { Standard: router.RouterMode = router.RouterMode.Standard } let rtm: RouterTmp = new RouterTmp() @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().pushUrl({ url: 'pages/routerpage2', params: { data1: 'message', data2: { data3: [123, 456, 789] } } }, rtm.Standard) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### pushUrl pushUrl(options: router.RouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void 跳转到应用内的指定页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 是 | 跳转页面描述信息。 | | mode | [router.RouterMode](js-apis-router.md#routermode9) | 是 | 跳转页面使用的模式。 | | callback | AsyncCallback<void> | 是 | 异常响应回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | | 100002 | Uri error. The URI of the page to redirect is incorrect or does not exist. | | 100003 | Page stack error. Too many pages are pushed. | **示例：** ```ts import { router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit' class RouterTmp { Standard: router.RouterMode = router.RouterMode.Standard } let rtm: RouterTmp = new RouterTmp() @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().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'); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### replaceUrl replaceUrl(options: router.RouterOptions): Promise<void> 用应用内的某个页面替换当前页面，并销毁被替换的页面，通过Promise获取跳转异常的返回的结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | --------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 是 | 替换页面描述信息。 | **返回值：** | 类型 | 说明 | | ------------------- | ------- | | Promise<void> | 异常返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | The UI execution context is not found. This error code is thrown only in the standard system. | | 200002 | Uri error. The URI of the page to be used for replacement is incorrect or does not exist. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit' @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().replaceUrl({ url: 'pages/detail', params: { data1: 'message' } }) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### replaceUrl replaceUrl(options: router.RouterOptions, callback: AsyncCallback<void>): void 用应用内的某个页面替换当前页面，并销毁被替换的页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 是 | 替换页面描述信息。 | | callback | AsyncCallback<void> | 是 | 异常响应回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | The UI execution context is not found. This error code is thrown only in the standard system. | | 200002 | Uri error. The URI of the page to be used for replacement is incorrect or does not exist. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit' @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().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'); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### replaceUrl replaceUrl(options: router.RouterOptions, mode: router.RouterMode): Promise<void> 用应用内的某个页面替换当前页面，并销毁被替换的页面，通过Promise获取跳转异常的返回结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ---------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 是 | 替换页面描述信息。 | | mode | [router.RouterMode](js-apis-router.md#routermode9) | 是 | 跳转页面使用的模式。 | **返回值：** | 类型 | 说明 | | ------------------- | ------- | | Promise<void> | 异常返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Failed to get the delegate. This error code is thrown only in the standard system. | | 200002 | Uri error. The URI of the page to be used for replacement is incorrect or does not exist. | **示例：** ```ts import { router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit' class RouterTmp { Standard: router.RouterMode = router.RouterMode.Standard } let rtm: RouterTmp = new RouterTmp() @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().replaceUrl({ url: 'pages/detail', params: { data1: 'message' } }, rtm.Standard) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### replaceUrl replaceUrl(options: router.RouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void 用应用内的某个页面替换当前页面，并销毁被替换的页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 是 | 替换页面描述信息。 | | mode | [router.RouterMode](js-apis-router.md#routermode9) | 是 | 跳转页面使用的模式。 | | callback | AsyncCallback<void> | 是 | 异常响应回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | The UI execution context is not found. This error code is thrown only in the standard system. | | 200002 | Uri error. The URI of the page to be used for replacement is incorrect or does not exist. | **示例：** ```ts import { router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; class RouterTmp { Standard: router.RouterMode = router.RouterMode.Standard } let rtm: RouterTmp = new RouterTmp() @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().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'); }); } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### pushNamedRoute pushNamedRoute(options: router.NamedRouterOptions): Promise<void> 跳转到指定的命名路由页面，通过Promise获取跳转异常的返回结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | --------- | | options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | 是 | 跳转页面描述信息。 | **返回值：** | 类型 | 说明 | | ------------------- | ------- | | Promise<void> | 异常返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | | 100003 | Page stack error. Too many pages are pushed. | | 100004 | Named route error. The named route does not exist. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit' @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().pushNamedRoute({ name: 'myPage', params: { data1: 'message', data2: { data3: [123, 456, 789] } } }) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### pushNamedRoute pushNamedRoute(options: router.NamedRouterOptions, callback: AsyncCallback<void>): void 跳转到指定的命名路由页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------- | | options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | 是 | 跳转页面描述信息。 | | callback | AsyncCallback<void> | 是 | 异常响应回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | | 100003 | Page stack error. Too many pages are pushed. | | 100004 | Named route error. The named route does not exist. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().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'); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### pushNamedRoute pushNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode): Promise<void> 跳转到指定的命名路由页面，通过Promise获取跳转异常的返回结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ---------- | | options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | 是 | 跳转页面描述信息。 | | mode | [router.RouterMode](js-apis-router.md#routermode9) | 是 | 跳转页面使用的模式。 | **返回值：** | 类型 | 说明 | | ------------------- | ------- | | Promise<void> | 异常返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | | 100003 | Page stack error. Too many pages are pushed. | | 100004 | Named route error. The named route does not exist. | **示例：** ```ts import { router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; class RouterTmp{ Standard:router.RouterMode = router.RouterMode.Standard } let rtm:RouterTmp = new RouterTmp() @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().pushNamedRoute({ name: 'myPage', params: { data1: 'message', data2: { data3: [123, 456, 789] } } }, rtm.Standard) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### pushNamedRoute pushNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void 跳转到指定的命名路由页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------- | | options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | 是 | 跳转页面描述信息。 | | mode | [router.RouterMode](js-apis-router.md#routermode9) | 是 | 跳转页面使用的模式。 | | callback | AsyncCallback<void> | 是 | 异常响应回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | | 100003 | Page stack error. Too many pages are pushed. | | 100004 | Named route error. The named route does not exist. | **示例：** ```ts import { router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; class RouterTmp { Standard: router.RouterMode = router.RouterMode.Standard } let rtm: RouterTmp = new RouterTmp() @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().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'); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### replaceNamedRoute replaceNamedRoute(options: router.NamedRouterOptions): Promise<void> 用指定的命名路由页面替换当前页面，并销毁被替换的页面，通过Promise获取跳转异常的返回结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | --------- | | options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | 是 | 替换页面描述信息。 | **返回值：** | 类型 | 说明 | | ------------------- | ------- | | Promise<void> | 异常返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------------- | | 401 | if the number of parameters is less than 1 or the type of the url parameter is not string. | | 100001 | The UI execution context is not found. This error code is thrown only in the standard system. | | 100004 | Named route error. The named route does not exist. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().replaceNamedRoute({ name: 'myPage', params: { data1: 'message' } }) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### replaceNamedRoute replaceNamedRoute(options: router.NamedRouterOptions, callback: AsyncCallback<void>): void 用指定的命名路由页面替换当前页面，并销毁被替换的页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | --------- | | options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | 是 | 替换页面描述信息。 | | callback | AsyncCallback<void> | 是 | 异常响应回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | The UI execution context is not found. This error code is thrown only in the standard system. | | 100004 | Named route error. The named route does not exist. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().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'); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### replaceNamedRoute replaceNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode): Promise<void> 用指定的命名路由页面替换当前页面，并销毁被替换的页面，通过Promise获取跳转异常的返回结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ---------- | | options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | 是 | 替换页面描述信息。 | | mode | [router.RouterMode](js-apis-router.md#routermode9) | 是 | 跳转页面使用的模式。 | **返回值：** | 类型 | 说明 | | ------------------- | ------- | | Promise<void> | 异常返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Failed to get the delegate. This error code is thrown only in the standard system. | | 100004 | Named route error. The named route does not exist. | **示例：** ```ts import { router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; class RouterTmp { Standard: router.RouterMode = router.RouterMode.Standard } let rtm: RouterTmp = new RouterTmp() @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().replaceNamedRoute({ name: 'myPage', params: { data1: 'message' } }, rtm.Standard) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`pushUrl failed, code is ${error.code}, message is ${error.message}`); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### replaceNamedRoute replaceNamedRoute(options: router.NamedRouterOptions, mode: router.RouterMode, callback: AsyncCallback<void>): void 用指定的命名路由页面替换当前页面，并销毁被替换的页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------- | | options | [router.NamedRouterOptions](js-apis-router.md#namedrouteroptions10) | 是 | 替换页面描述信息。 | | mode | [router.RouterMode](js-apis-router.md#routermode9) | 是 | 跳转页面使用的模式。 | | callback | AsyncCallback<void> | 是 | 异常响应回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------------- | | 401 | if the number of parameters is less than 1 or the type of the url parameter is not string. | | 100001 | The UI execution context is not found. This error code is thrown only in the standard system. | | 100004 | Named route error. The named route does not exist. | **示例：** ```ts import { router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; class RouterTmp { Standard: router.RouterMode = router.RouterMode.Standard } let rtm: RouterTmp = new RouterTmp() @Entry @Component struct Index { async routePage() { this.getUIContext().getRouter().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'); }) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button() { Text('next page') .fontSize(25) .fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) .margin({ top: 20 }) .backgroundColor('#ccc') .onClick(() => { this.routePage() }) } .width('100%') .height('100%') } } ``` ### back back(options?: router.RouterOptions ): void 返回上一页面或指定的页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ---------------------------------------- | | options | [router.RouterOptions](js-apis-router.md#routeroptions) | 否 | 返回页面描述信息，其中参数url指路由跳转时会返回到指定url的界面，如果页面栈上没有url页面，则不响应该情况。如果url未设置，则返回上一页，页面不会重新构建，页面栈里面的page不会回收，出栈后会被回收。 | **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); router.back({url:'pages/detail'}); ``` ### back12+ back(index: number, params?: Object): void; 返回指定的页面。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------- | ---- | ---------- | | index | number | 是 | 跳转目标页面的索引值。
取值范围：[0, +∞) | | params | Object | 否 | 页面返回时携带的参数。 | **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); router.back(1); ``` ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); router.back(1, {info:'来自Home页'}); //携带参数返回 ``` ### clear clear(): void 清空页面栈中的所有历史页面，仅保留当前页面作为栈顶页面。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); router.clear(); ``` ### getLength getLength(): string 获取当前在页面栈内的页面数量。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------ | ------------------ | | string | 页面数量，页面栈支持最大数值是32。 | **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); let size = router.getLength(); console.info('pages stack size = ' + size); ``` ### getState getState(): router.RouterState 获取当前页面的状态信息。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | router.[RouterState](js-apis-router.md#routerstate) | 页面状态信息。 | **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); let page = router.getState(); console.info('current index = ' + page.index); console.info('current name = ' + page.name); console.info('current path = ' + page.path); ``` ### getStateByIndex12+ getStateByIndex(index: number): router.RouterState | undefined 通过索引值获取对应页面的状态信息。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------- | ---- | ---------- | | index | number | 是 | 表示要获取的页面索引。
取值范围：[0, +∞) | **返回值：** | 类型 | 说明 | | --------------------------- | ------- | | router.[RouterState](js-apis-router.md#outerstate) \| undefined | 返回页面状态信息。索引不存在时返回undefined。 | **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); let options: router.RouterState | undefined = router.getStateByIndex(1); if (options != undefined) { console.info('index = ' + options.index); console.info('name = ' + options.name); console.info('path = ' + options.path); console.info('params = ' + options.params); } ``` ### getStateByUrl12+ getStateByUrl(url: string): Array 通过url获取当前页面的状态信息。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------- | ---- | ---------- | | url | string | 是 | 表示要获取对应页面信息的url。 | **返回值：** | 类型 | 说明 | | --------------------------- | ------- | | Array | 页面状态信息。 | **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); let options:Array = router.getStateByUrl('pages/index'); for (let i: number = 0; i < options.length; i++) { console.info('index = ' + options[i].index); console.info('name = ' + options[i].name); console.info('path = ' + options[i].path); console.info('params = ' + options[i].params); } ``` ### showAlertBeforeBackPage showAlertBeforeBackPage(options: router.EnableAlertOptions): void 开启页面返回询问对话框。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | --------- | | options | [router.EnableAlertOptions](js-apis-router.md#enablealertoptions) | 是 | 文本弹窗信息描述。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.router(页面路由)](errorcode-router.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { Router } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; 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 禁用页面返回询问对话框。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); router.hideAlertBeforeBackPage(); ``` ### getParams getParams(): Object 获取发起跳转的页面往当前页传入的参数。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------ | ----------------- | | Object | 发起跳转的页面往当前页传入的参数。 | **示例：** ```ts import { Router } from '@kit.ArkUI'; let router: Router = uiContext.getRouter(); router.getParams(); ``` ## CustomBuilderWithId18+ type CustomBuilderWithId = (id: number) => void 组件属性方法参数可使用CustomBuilderWithId类型来自定义UI描述，并且可以指定组件ID生成用户自定义组件。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | id | number | 是 | 组件ID | ## TargetInfo18+ 指定组件绑定的目标节点。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 名称 | 类型 | 只读 | 可选 | 说明 | | -------- | -------- | -------- | -------- | -------- | | id | string \| number | 否 | 否 | 指定popup或menu绑定的目标节点。
**说明：**
1. 当id是number时，对应组件实例的UniquelD，此id由系统保证唯一性。
2. 当id是string时，对应[通用属性id](arkui-ts/ts-universal-attributes-component-id.md#id)所指定的组件，此id的唯一性需由开发者确保，但实际可能会有多个。 | | componentId | number | 否 | 是 | 目标节点所在的自定义组件的UniquelD。当上述id指定为string类型时，可通过此属性圈定范围。方便开发者在一定范围内保证id: string的唯一性。 | ## PromptAction 以下API需先使用UIContext中的[getPromptAction()](#getpromptaction)方法获取到PromptAction对象，再通过该对象调用对应方法。 ### showToast showToast(options: promptAction.ShowToastOptions): void 创建并显示文本提示框。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | options | [promptAction.ShowToastOptions](js-apis-promptAction.md#showtoastoptions) | 是 | 文本弹窗选项。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { PromptAction } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; 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}`); }; ``` ### openToast18+ openToast(options: promptAction.ShowToastOptions): Promise<number> **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------------------------------------ | ---- | -------------- | | options | [promptAction.ShowToastOptions](js-apis-promptAction.md#showtoastoptions) | 是 | 文本弹窗选项。 | **返回值** | 类型 | 说明 | | ---------------- | ------------------------------------ | | Promise<number> | 返回供closeToast使用的文本提示框id。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { PromptAction } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; @Entry @Component struct toastExample { @State toastId: number = 0; promptAction: PromptAction = this.getUIContext().getPromptAction() build() { Column() { Button('Open Toast') .height(100) .onClick(() => { this.promptAction.openToast({ message: 'Toast Massage', duration: 10000, }).then((toastId: number) => { this.toastId = toastId; }) .catch((error: BusinessError) => { console.error(`openToast error code is ${error.code}, message is ${error.message}`) }) }) Blank().height(50); Button('Close Toast') .height(100) .onClick(() => { try { this.promptAction.closeToast(this.toastId); } catch (error) { let message = (error as BusinessError).message; let code = (error as BusinessError).code; console.error(`CloseToast error code is ${code}, message is ${message}`); }; }) }.height('100%').width('100%').justifyContent(FlexAlign.Center) } } ``` ### closeToast18+ closeToast(toastId: number): void **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | ----------------------------- | | toastId | number | 是 | openToast返回的文本提示框id。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** 示例请看[openToaset18](#opentoast18)的示例。 ### showDialog showDialog(options: promptAction.ShowDialogOptions, callback: AsyncCallback<promptAction.ShowDialogSuccessResponse>): void 创建并显示对话框，对话框响应结果异步返回。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ------------ | | options | [promptAction.ShowDialogOptions](js-apis-promptAction.md#showdialogoptions) | 是 | 页面显示对话框信息描述。 | | callback | AsyncCallback<[promptAction.ShowDialogSuccessResponse](js-apis-promptAction.md#showdialogsuccessresponse)> | 是 | 对话框响应结果回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { PromptAction } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; let promptAction: PromptAction = uiContext.getPromptAction(); try { promptAction.showDialog({ title: 'showDialog Title Info', message: 'Message Info', buttons: [ { text: 'button1', color: '#000000' }, { text: 'button2', color: '#000000' } ] }, (err, data) => { if (err) { console.error('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> 创建并显示对话框，对话框响应后同步返回结果，通过Promise获取对话框响应结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------ | | options | [promptAction.ShowDialogOptions](js-apis-promptAction.md#showdialogoptions) | 是 | 对话框选项。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | -------- | | Promise<[promptAction.ShowDialogSuccessResponse](js-apis-promptAction.md#showdialogsuccessresponse)> | 对话框响应结果。 | **错误码：** 以下错误码的详细介绍请参见[ 通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { PromptAction } from '@kit.ArkUI'; let promptAction: PromptAction = uiContext.getPromptAction(); 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.error('showDialog error: ' + err); }) ``` ### showActionMenu11+ showActionMenu(options: promptAction.ActionMenuOptions, callback: AsyncCallback<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)>):void 创建并显示操作菜单，菜单响应结果异步返回。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | 是 | 操作菜单选项。 | | callback | AsyncCallback<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)> | 是 | 菜单响应结果回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | -------- | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { PromptAction, promptAction } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; 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.error('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 创建并显示操作菜单，菜单响应结果异步返回。 从API version11开始不再维护，建议使用[showActionMenu](#showactionmenu11)。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | 是 | 操作菜单选项。 | | callback | [promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse) | 是 | 菜单响应结果回调。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { PromptAction,promptAction } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; 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> 创建并显示操作菜单，通过Promise获取菜单响应结果。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | 是 | 操作菜单选项。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)> | 菜单响应结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { PromptAction } from '@kit.ArkUI'; let promptAction: PromptAction = uiContext.getPromptAction(); 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.error('showActionMenu error: ' + err); }) ``` ### openCustomDialog12+ openCustomDialog\(dialogContent: ComponentContent\, options?: promptAction.BaseDialogOptions): Promise<void> 创建并弹出dialogContent对应的自定义弹窗，使用Promise异步回调。通过该接口弹出的弹窗内容样式完全按照dialogContent中设置的样式显示，即相当于customdialog设置customStyle为true时的显示效果。暂不支持[isModal](js-apis-promptAction.md#basedialogoptions11) = true与[showInSubWindow](js-apis-promptAction.md#basedialogoptions11) = true同时使用。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | dialogContent | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | 自定义弹窗中显示的组件内容。 | | options | [promptAction.BaseDialogOptions](js-apis-promptAction.md#basedialogoptions11) | 否 | 弹窗样式。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103302 | Dialog content already exists.| **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { ComponentContent } from '@kit.ArkUI'; class Params { text: string = "" constructor(text: string) { this.text = text; } } @Builder function buildText(params: Params) { Column() { Text(params.text) .fontSize(50) .fontWeight(FontWeight.Bold) .margin({ bottom: 36 }) }.backgroundColor('#FFF0F0F0') } @Entry @Component struct Index { @State message: string = "hello" build() { Row() { Column() { Button("click me") .onClick(() => { let uiContext = this.getUIContext(); let promptAction = uiContext.getPromptAction(); let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), new Params(this.message)); promptAction.openCustomDialog(contentNode) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`OpenCustomDialog args error code is ${error.code}, message is ${error.message}`); }) }) } .width('100%') .height('100%') } .height('100%') } } ``` ### openCustomDialogWithController18+ openCustomDialogWithController\(dialogContent: ComponentContent\, controller: promptAction.DialogController, options?: promptAction.BaseDialogOptions): Promise<void> 创建并弹出dialogContent对应的自定义弹窗，使用Promise异步回调。支持传入弹窗控制器与自定义弹窗绑定，后续可以通过控制器控制自定义弹窗。 通过该接口弹出的弹窗内容样式完全按照dialogContent中设置的样式显示，即相当于customdialog设置customStyle为true时的显示效果。 暂不支持[isModal](js-apis-promptAction.md#basedialogoptions11) = true与[showInSubWindow](js-apis-promptAction.md#basedialogoptions11) = true同时使用。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | dialogContent | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | 自定义弹窗中显示的组件内容。 | | controller | [promptAction.DialogController](js-apis-promptAction.md#dialogcontroller18) | 是 | 自定义弹窗的控制器。 | | options | [promptAction.BaseDialogOptions](js-apis-promptAction.md#basedialogoptions11) | 否 | 自定义弹窗的样式。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103302 | Dialog content already exists.| **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { ComponentContent, promptAction } from '@kit.ArkUI'; class Params { text: string = "" dialogController: promptAction.DialogController = new promptAction.DialogController(); constructor(text: string, dialogController: promptAction.DialogController) { this.text = text; this.dialogController = dialogController; } } @Builder function buildText(params: Params) { Column() { Text(params.text) .fontSize(50) .fontWeight(FontWeight.Bold) .margin({ bottom: 36 }) Button('点我关闭弹窗：通过外部传递的DialogController') .onClick(() => { if (params.dialogController != undefined) { params.dialogController.close() } }) }.backgroundColor('#FFF0F0F0') } @Entry @ComponentV2 struct Index { @Local message: string = "hello" private dialogController: promptAction.DialogController = new promptAction.DialogController() build() { Row() { Column() { Button("click me") .onClick(() => { let uiContext = this.getUIContext(); let promptAction = uiContext.getPromptAction(); let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), new Params(this.message, this.dialogController)); promptAction.openCustomDialogWithController(contentNode, this.dialogController) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`OpenCustomDialogWithController args error code is ${error.code}, message is ${error.message}`); }) }) } .width('100%') .height('100%') } .height('100%') } } ``` ### closeCustomDialog12+ closeCustomDialog\(dialogContent: ComponentContent\): Promise<void> 关闭已弹出的dialogContent对应的自定义弹窗，使用Promise异步回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | dialogContent | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | 自定义弹窗中显示的组件内容。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103303 | The ComponentContent cannot be found. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { ComponentContent } from '@kit.ArkUI'; class Params { text: string = "" constructor(text: string) { this.text = text; } } @Builder function buildText(params: Params) { Column() { Text(params.text) .fontSize(50) .fontWeight(FontWeight.Bold) .margin({ bottom: 36 }) }.backgroundColor('#FFF0F0F0') } @Entry @Component struct Index { @State message: string = "hello" build() { Row() { Column() { Button("click me") .onClick(() => { let uiContext = this.getUIContext(); let promptAction = uiContext.getPromptAction(); let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), new Params(this.message)); promptAction.openCustomDialog(contentNode) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`OpenCustomDialog args error code is ${error.code}, message is ${error.message}`); }) setTimeout(() => { promptAction.closeCustomDialog(contentNode) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`OpenCustomDialog args error code is ${error.code}, message is ${error.message}`); }) }, 2000); //2秒后自动关闭 }) } .width('100%') .height('100%') } .height('100%') } } ``` ### updateCustomDialog12+ updateCustomDialog\(dialogContent: ComponentContent\, options: promptAction.BaseDialogOptions): Promise<void> 更新已弹出的dialogContent对应的自定义弹窗的样式，使用Promise异步回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | dialogContent | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | 自定义弹窗中显示的组件内容。 | | options | [promptAction.BaseDialogOptions](js-apis-promptAction.md#basedialogoptions11) | 是 | 弹窗样式，目前仅支持更新alignment、offset、autoCancel、maskColor。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103303 | The ComponentContent cannot be found. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { ComponentContent } from '@kit.ArkUI'; class Params { text: string = "" constructor(text: string) { this.text = text; } } @Builder function buildText(params: Params) { Column() { Text(params.text) .fontSize(50) .fontWeight(FontWeight.Bold) .margin({ bottom: 36 }) }.backgroundColor('#FFF0F0F0') } @Entry @Component struct Index { @State message: string = "hello" build() { Row() { Column() { Button("click me") .onClick(() => { let uiContext = this.getUIContext(); let promptAction = uiContext.getPromptAction(); let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), new Params(this.message)) promptAction.openCustomDialog(contentNode) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`updateCustomDialog args error code is ${error.code}, message is ${error.message}`) }) setTimeout(() => { promptAction.updateCustomDialog(contentNode, { alignment: DialogAlignment.CenterEnd }) .then(() => { console.info('succeeded') }) .catch((error: BusinessError) => { console.error(`updateCustomDialog args error code is ${error.code}, message is ${error.message}`) }) }, 2000); //2秒后自动更新弹窗位置 }) } .width('100%') .height('100%') } .height('100%') } } ``` ### openCustomDialog12+ openCustomDialog(options: promptAction.CustomDialogOptions): Promise\ 创建并弹出自定义弹窗。使用Promise异步回调，返回供closeCustomDialog使用的对话框id。暂不支持isModal = true与showInSubWindow = true同时使用。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | options | [promptAction.CustomDialogOptions](js-apis-promptAction.md#customdialogoptions11) | 是 | 自定义弹窗的内容。 | **返回值：** | 类型 | 说明 | | ------------------- | --------------------------------------- | | Promise<void> | 返回供closeCustomDialog使用的对话框id。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | ### presentCustomDialog18+ presentCustomDialog(builder: CustomBuilder \| CustomBuilderWithId, controller?: promptAction.DialogController, options?: promptAction.DialogOptions): Promise\ 创建并弹出自定义弹窗。使用Promise异步回调，返回供closeCustomDialog使用的对话框id。 支持在自定义弹窗内容中持有弹窗ID进行对应操作。支持传入弹窗控制器与自定义弹窗绑定，后续可以通过控制器控制自定义弹窗。 暂不支持isModal = true与showInSubWindow = true同时使用。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------------------------------------ | ---- | ------------------ | | builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [CustomBuilderWithId](#custombuilderwithid18) | 是 | 自定义弹窗的内容。 | | controller | [promptAction.DialogController](js-apis-promptAction.md#dialogcontroller18) | 否 | 自定义弹窗的控制器。 | | options | [promptAction.DialogOptions](js-apis-promptAction.md#dialogoptions18) | 否 | 自定义弹窗的样式。 | **返回值：** | 类型 | 说明 | | ------------------- | --------------------------------------- | | Promise<number> | 返回自定义弹窗ID。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { PromptAction, promptAction } from '@kit.ArkUI'; @Entry @ComponentV2 struct Index { @Local message: string = "hello" private ctx: UIContext = this.getUIContext() private promptAction: PromptAction = this.ctx.getPromptAction() private dialogController: promptAction.DialogController = new promptAction.DialogController() private customDialogComponentId: number = 0 @Builder customDialogComponent() { Column() { Text(this.message).fontSize(30) Row({ space: 10 }) { Button("通过DialogId关闭").onClick(() => { this.promptAction.closeCustomDialog(this.customDialogComponentId) }) Button("通过DialogController关闭").onClick(() => { this.dialogController.close() }) } }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) } @Builder customDialogComponentWithId(dialogId: number) { Column() { Text(this.message).fontSize(30) Row({ space: 10 }) { Button("通过DialogId关闭").onClick(() => { this.promptAction.closeCustomDialog(dialogId) }) Button("通过DialogController关闭").onClick(() => { this.dialogController.close() }) } }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) } build() { Row() { Column({ space: 10 }) { Button('presentCustomDialog') .fontSize(20) .onClick(() => { this.promptAction.presentCustomDialog(() => { this.customDialogComponent() }, this.dialogController) .then((dialogId: number) => { this.customDialogComponentId = dialogId }) .catch((err: BusinessError) => { console.error("presentCustomDialog error: " + err.code + " " + err.message) }) }) Button('presentCustomDialog with id') .fontSize(20) .onClick(() => { this.promptAction.presentCustomDialog((dialogId: number) => { this.customDialogComponentWithId(dialogId) }, this.dialogController) .catch((err: BusinessError) => { console.error("presentCustomDialog with id error: " + err.code + " " + err.message) }) }) } .width('100%') .height('100%') } .height('100%') } } ``` ### closeCustomDialog12+ closeCustomDialog(dialogId: number): void 关闭自定义弹窗。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | -------------------------------- | | dialogId | number | 是 | openCustomDialog返回的对话框id。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal error. | **示例：** ```ts import { PromptAction } from '@kit.ArkUI'; @Entry @Component struct Index { promptAction: PromptAction = this.getUIContext().getPromptAction() private customDialogComponentId: number = 0 @Builder customDialogComponent() { Column() { Text('弹窗').fontSize(30) Row({ space: 50 }) { Button("确认").onClick(() => { this.promptAction.closeCustomDialog(this.customDialogComponentId) }) Button("取消").onClick(() => { this.promptAction.closeCustomDialog(this.customDialogComponentId) }) } }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) } build() { Row() { Column() { Button("click me") .onClick(() => { this.promptAction.openCustomDialog({ builder: () => { this.customDialogComponent() }, onWillDismiss: (dismissDialogAction: DismissDialogAction) => { console.info("reason" + JSON.stringify(dismissDialogAction.reason)) console.log("dialog onWillDismiss") if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { dismissDialogAction.dismiss() } if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { dismissDialogAction.dismiss() } } }).then((dialogId: number) => { this.customDialogComponentId = dialogId }) }) } .width('100%') .height('100%') } .height('100%') } } ``` ### getTopOrder18+ getTopOrder(): LevelOrder 返回最顶层显示的弹窗的顺序。 获取最顶层显示的弹窗的顺序，可以在下一个弹窗时指定期望的顺序。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------------------- | --------------------------------------- | | [LevelOrder](js-apis-promptAction.md#levelorder18) | 返回弹窗层级信息。 | **示例：** 该示例通过调用getTopOrder接口，展示了获取最顶层显示的弹窗的顺序的功能。 ```ts import { ComponentContent, PromptAction, LevelOrder, promptAction, UIContext } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; class Params { text: string = "" constructor(text: string) { this.text = text; } } @Builder function buildText(params: Params) { Column({ space: 20 }) { Text(params.text) .fontSize(50) .fontWeight(FontWeight.Bold) .margin({ bottom: 36 }) }.backgroundColor('#FFF0F0F0') } @Entry @Component struct Index { @State message: string = '弹窗' private ctx: UIContext = this.getUIContext() private promptAction: PromptAction = this.ctx.getPromptAction() private contentNode: ComponentContent = new ComponentContent(this.ctx, wrapBuilder(buildText), new Params(this.message)) private baseDialogOptions: promptAction.BaseDialogOptions = { showInSubWindow: false, levelOrder: LevelOrder.clamp(30.1), } build() { Row() { Column({ space: 10 }) { Button('openCustomDialog弹窗') .fontSize(20) .onClick(() => { this.promptAction.openCustomDialog(this.contentNode, this.baseDialogOptions) .catch((err: BusinessError) => { console.error("openCustomDialog error: " + err.code + " " + err.message) }) .then(() => { let topOrder: LevelOrder = this.promptAction.getTopOrder(); if (topOrder !== undefined) { console.error('topOrder: ' + topOrder.getOrder()); } }) }) }.width('100%') }.height('100%') } } ``` ### getBottomOrder18+ getBottomOrder(): LevelOrder 返回最底层显示的弹窗的顺序。 获取最底层显示的弹窗的顺序，可以在下一个弹窗时指定期望的顺序。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------------------- | --------------------------------------- | | [LevelOrder](js-apis-promptAction.md#levelorder18) | 返回弹窗层级信息。 | **示例：** 该示例通过调用getBottomOrder接口，展示了获取最底层显示的弹窗的顺序的功能。 ```ts import { ComponentContent, PromptAction, LevelOrder, promptAction, UIContext } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; class Params { text: string = "" constructor(text: string) { this.text = text; } } @Builder function buildText(params: Params) { Column({ space: 20 }) { Text(params.text) .fontSize(50) .fontWeight(FontWeight.Bold) .margin({ bottom: 36 }) }.backgroundColor('#FFF0F0F0') } @Entry @Component struct Index { @State message: string = '弹窗' private ctx: UIContext = this.getUIContext() private promptAction: PromptAction = this.ctx.getPromptAction() private contentNode: ComponentContent = new ComponentContent(this.ctx, wrapBuilder(buildText), new Params(this.message)) private baseDialogOptions: promptAction.BaseDialogOptions = { showInSubWindow: false, levelOrder: LevelOrder.clamp(30.1), } build() { Row() { Column({ space: 10 }) { Button('openCustomDialog弹窗') .fontSize(20) .onClick(() => { this.promptAction.openCustomDialog(this.contentNode, this.baseDialogOptions) .catch((err: BusinessError) => { console.error("openCustomDialog error: " + err.code + " " + err.message) }) .then(() => { let bottomOrder: LevelOrder = this.promptAction.getBottomOrder(); if (bottomOrder !== undefined) { console.error('bottomOrder: ' + bottomOrder.getOrder()); } }) }) }.width('100%') }.height('100%') } } ``` ### openPopup18+ openPopup\(content: ComponentContent\, target: TargetInfo, options?: PopupCommonOptions): Promise<void> 创建并弹出以content作为内容的popup弹窗，使用Promise异步回调。 > **说明：** > > 1. 使用该接口时，若未传入有效的target，则无法弹出popup弹窗。 > > 2. 由于[updatePopup](#updatepopup18)和[closePopup](#closepopup18)依赖content去更新或者关闭指定的popup弹窗，开发者需自行维护传入的content。 > > 3. 如果在wrapBuilder中包含其他组件（例如：[Popup](arkui-ts/ohos-arkui-advanced-Popup.md#popup)、[Chip](arkui-ts/ohos-arkui-advanced-Chip.md#chip)组件），则[ComponentContent](./js-apis-arkui-ComponentContent.md#componentcontent-1)应采用带有四个参数的构造函数constructor，其中options参数应传递{ nestingBuilderSupported: true }。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | content | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | popup弹窗中显示的组件内容。 | | target | [TargetInfo](#targetinfo18) | 是 | 需要绑定组件的信息。 | | options | [PopupCommonOptions](arkui-ts/ts-universal-attributes-popup.md#popupcommonoptions18类型说明) | 否 | popup弹窗样式。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103302 | The ComponentContent already exists. | | 103304 | The targetId does not exist. | | 103305 | The node of targetId is not in the component tree. | **示例：** ```ts import { ComponentContent, FrameNode } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; interface PopupParam { updateFunc?: () => void closeFunc?: () => void } export function showPopup(context: UIContext, uniqueId: number, contentNode: ComponentContent, popupParam: PopupParam) { const promptAction = context.getPromptAction(); let frameNode: FrameNode | null = context.getFrameNodeByUniqueId(uniqueId); let targetId = frameNode?.getFirstChild()?.getUniqueId(); promptAction.openPopup(contentNode, { id: targetId }, { radius: 16, mask: { color: Color.Pink }, enableArrow: true, }) .then(() => { console.info('openPopup success'); }) .catch((err: BusinessError) => { console.info('openPopup error: ' + err.code + ' ' + err.message); }) popupParam.updateFunc = () => { promptAction.updatePopup(contentNode, { enableArrow: false }, true) .then(() => { console.info('updatePopup success'); }) .catch((err: BusinessError) => { console.info('updatePopup error: ' + err.code + ' ' + err.message); }) } popupParam.closeFunc = () => { promptAction.closePopup(contentNode) .then(() => { console.info('closePopup success'); }) .catch((err: BusinessError) => { console.info('closePopup error: ' + err.code + ' ' + err.message); }) } } @Builder function buildText(param?: PopupParam) { Column() { Text('popup') Button('Update Popup') .fontSize(20) .onClick(() => { param?.updateFunc?.(); }) Button('Close Popup') .fontSize(20) .onClick(() => { param?.closeFunc?.(); }) } } @Entry @Component struct Index { build() { Column() { Button('Open Popup') .fontSize(20) .onClick(() => { let context = this.getUIContext() const popupParam: PopupParam = {}; const contentNode = new ComponentContent(context, wrapBuilder(buildText), popupParam); showPopup(context, this.getUniqueId(), contentNode, popupParam) }) } } } ``` ### updatePopup18+ updatePopup\(content: ComponentContent\, options: PopupCommonOptions, partialUpdate?: boolean ): Promise<void> 更新content对应的popup弹窗的样式，使用Promise异步回调。 > **说明：** > > 不支持更新showInSubWindow、focusable、onStateChange、onWillDismiss、transition。 > **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | content | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | popup弹窗中显示的组件内容。 | | options | [PopupCommonOptions](arkui-ts/ts-universal-attributes-popup.md#popupcommonoptions18类型说明) | 是 | popup弹窗样式。
**说明：**
不支持更新showInSubWindow、focusable、onStateChange、onWillDismiss、transition。 | | partialUpdate | boolean | 否 | popup弹窗更新方式, 默认值为false。
**说明：**
1. true为增量更新，保留当前值，更新options中的指定属性。
2. false为全量更新，除options中的指定属性，其他属性恢复默认值。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103303 | The ComponentContent cannot be found. | **示例：** 请参考[openPopup](#openpopup18)示例。 ### closePopup18+ closePopup\(content: ComponentContent\): Promise<void> 关闭content对应的popup弹窗，使用Promise异步回调。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | content | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | popup弹窗中显示的组件内容。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103303 | The ComponentContent cannot be found. | **示例：** 请参考[openPopup](#openpopup18)示例。 ### openMenu18+ openMenu\(content: ComponentContent\, target: TargetInfo, options?: MenuOptions): Promise<void> 创建并弹出以content作为内容的menu弹窗。使用Promise异步回调。 > **说明：** > > 1. 使用该接口时，若未传入有效的target，则无法弹出menu弹窗。 > > 2. 由于[updateMenu](#updatemenu18)和[closeMenu](#closemenu18)依赖content去更新或者关闭指定的menu弹窗，开发者需自行维护传入的content。 > > 3. 如果在wrapBuilder中包含其他组件（例如：[Popup](arkui-ts/ohos-arkui-advanced-Popup.md#popup)、[Chip](arkui-ts/ohos-arkui-advanced-Chip.md#chip)组件），则[ComponentContent](./js-apis-arkui-ComponentContent.md#componentcontent-1)应采用带有四个参数的构造函数constructor，其中options参数应传递{ nestingBuilderSupported: true }。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | content | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | menu弹窗中显示的组件内容。 | | target | [TargetInfo](#targetinfo18) | 是 | 需要绑定组件的信息。 | | options | [MenuOptions](./arkui-ts/ts-universal-attributes-menu.md#menuoptions10) | 否 | menu弹窗样式。
**说明：**
title属性不生效。
preview参数仅支持设置MenuPreviewMode类型。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103302 | The ComponentContent already exists. | | 103304 | The targetId does not exist. | | 103305 | The node of targetId is not in the component tree. | **示例：** ```ts import { ComponentContent, FrameNode } from '@kit.ArkUI'; export function doSomething(context: UIContext, uniqueId: number, contentNode: ComponentContent) { showMenu(context, uniqueId, contentNode); } @Builder function MyMenu() { Column() { Menu() { MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项1" }) MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项2" }) } } .width('80%') .padding('20lpx') } export function showMenu(context: UIContext, uniqueId: number, contentNode: ComponentContent) { const promptAction = context.getPromptAction(); let frameNode: FrameNode | null = context.getFrameNodeByUniqueId(uniqueId); let frameNodeTarget = frameNode?.getFirstChild(); frameNodeTarget = frameNodeTarget?.getChild(0); let targetId = frameNodeTarget?.getUniqueId(); promptAction.openMenu(contentNode, { id: targetId }, { enableArrow: true, }); } @Entry @Component struct Index { build() { Column() { Button('OpenMenu', { type: ButtonType.Normal, stateEffect: true }) .borderRadius('16lpx') .width('80%') .margin(10) .onClick(() => { let context = this.getUIContext() const contentNode = new ComponentContent(context, wrapBuilder(MyMenu)); doSomething(context, this.getUniqueId(), contentNode) }) } } } ``` ### updateMenu18+ updateMenu\(content: ComponentContent\, options: MenuOptions, partialUpdate?: boolean ): Promise<void> 更新content对应的menu弹窗的样式。使用Promise异步回调。 > **说明：** > > 不支持更新showInSubWindow、preview、previewAnimationOptions、transition、onAppear、aboutToAppear、onDisappear、aboutToDisappear。 > **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | content | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | menu弹窗中显示的组件内容。 | | options | [MenuOptions](./arkui-ts/ts-universal-attributes-menu.md#menuoptions10) | 是 | menu弹窗样式。
**说明：**
不支持更新showInSubWindow、preview、previewAnimationOptions、transition、onAppear、aboutToAppear、onDisappear、aboutToDisappear。 | | partialUpdate | boolean | 否 | menu弹窗更新方式，默认值为false。
**说明：**
1. true为增量更新，保留当前值，更新options中的指定属性。
2. false为全量更新，除options中的指定属性，其他属性恢复默认值。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103303 | The ComponentContent cannot be found. | **示例：** ```ts import { ComponentContent, FrameNode } from '@kit.ArkUI'; export function doSomething(context: UIContext, uniqueId: number, contentNode: ComponentContent) { showMenu(context, uniqueId, contentNode); } @Builder function MyMenu() { Column() { Menu() { MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项1" }) MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项2" }) } } .width('80%') .padding('20lpx') } export function showMenu(context: UIContext, uniqueId: number, contentNode: ComponentContent) { const promptAction = context.getPromptAction(); let frameNode: FrameNode | null = context.getFrameNodeByUniqueId(uniqueId); let frameNodeTarget = frameNode?.getFirstChild(); frameNodeTarget = frameNodeTarget?.getChild(0); let targetId = frameNodeTarget?.getUniqueId(); promptAction.openMenu(contentNode, { id: targetId }, { enableArrow: true, }); setTimeout(() => { promptAction.updateMenu(contentNode, { enableArrow: false, }); }, 2000) } @Entry @Component struct Index { build() { Column() { Button('OpenMenu', { type: ButtonType.Normal, stateEffect: true }) .borderRadius('16lpx') .width('80%') .margin(10) .onClick(() => { let context = this.getUIContext() const contentNode = new ComponentContent(context, wrapBuilder(MyMenu)); doSomething(context, this.getUniqueId(), contentNode) }) } } } ``` ### closeMenu18+ closeMenu\(content: ComponentContent\): Promise<void> 关闭content对应的menu弹窗。使用Promise异步回调。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | content | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | menu弹窗中显示的组件内容。 | **返回值：** | 类型 | 说明 | | ---------------------------------------- | ------- | | Promise<void> | 异常返回Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 | 错误码ID | 错误信息 | | ------ | ---------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 103301 | The ComponentContent is incorrect. | | 103303 | The ComponentContent cannot be found. | **示例：** ```ts import { ComponentContent, FrameNode } from '@kit.ArkUI'; export function doSomething(context: UIContext, uniqueId: number, contentNode: ComponentContent) { showMenu(context, uniqueId, contentNode); } @Builder function MyMenu() { Column() { Menu() { MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项1" }) MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项2" }) } } .width('80%') .padding('20lpx') } export function showMenu(context: UIContext, uniqueId: number, contentNode: ComponentContent) { const promptAction = context.getPromptAction(); let frameNode: FrameNode | null = context.getFrameNodeByUniqueId(uniqueId); let frameNodeTarget = frameNode?.getFirstChild(); frameNodeTarget = frameNodeTarget?.getChild(0); let targetId = frameNodeTarget?.getUniqueId(); promptAction.openMenu(contentNode, { id: targetId }, { enableArrow: true, }); setTimeout(() => { promptAction.closeMenu(contentNode); }, 2000) } @Entry @Component struct Index { build() { Column() { Button('OpenMenu', { type: ButtonType.Normal, stateEffect: true }) .borderRadius('16lpx') .width('80%') .margin(10) .onClick(() => { let context = this.getUIContext() const contentNode = new ComponentContent(context, wrapBuilder(MyMenu)); doSomething(context, this.getUniqueId(), contentNode) }) } } } ``` ## DragController11+ 以下API需先使用UIContext中的[getDragController()](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取UIContext实例，再通过此实例调用对应方法。 ### executeDrag11+ executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: dragController.DragInfo, callback: AsyncCallback<dragController.DragEventParam>): void 主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过回调返回拖拽事件结果。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | custom | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo说明) | 是 | 拖拽发起后跟手效果所拖拽的对象。
**说明：**
不支持全局builder。如果builder中使用了[Image](arkui-ts/ts-basic-components-image.md)组件，应尽量开启同步加载，即配置Image的[syncLoad](arkui-ts/ts-basic-components-image.md#syncload8)为true。该builder只用于生成当次拖拽中显示的图片，builder的修改不会同步到当前正在拖拽的图片，对builder的修改需要在下一次拖拽时生效。 | | dragInfo | [dragController.DragInfo](js-apis-arkui-dragController.md#draginfo) | 是 | 拖拽信息。 | | callback | [AsyncCallback](../apis-basic-services-kit/js-apis-base.md#asynccallback)<[dragController.DragEventParam](js-apis-arkui-dragController.md#drageventparam12)> | 是 | 拖拽结束返回结果的回调
- event：拖拽事件信息，仅包括拖拽结果。
- extraParams：拖拽事件额外信息。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal handling failed. | **示例：** ```ts import { dragController } from "@kit.ArkUI" import { unifiedDataChannel } from '@kit.ArkData'; @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 unifiedDataChannel.Text() let unifiedData = new unifiedDataChannel.UnifiedData(text) let dragInfo: dragController.DragInfo = { pointerId: 0, data: unifiedData, extraParams: '' } class tmp{ event:DragEvent|undefined = undefined extraParams:string = '' } let eve:tmp = new tmp() this.getUIContext().getDragController().executeDrag(()=>{this.DraggingBuilder()}, dragInfo, (err, eve) => { if(eve.event){ if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { // ... } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { // ... } } }) } } }) } } } ``` ### executeDrag11+ executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: dragController.DragInfo): Promise<dragController.DragEventParam> 主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过Promise返回拖拽事件结果。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | -------------------------------- | | custom | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo说明) | 是 | 拖拽发起后跟手效果所拖拽的对象。 | | dragInfo | [dragController.DragInfo](js-apis-arkui-dragController.md#draginfo) | 是 | 拖拽信息。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | ------------------------------------------------------------ | | Promise<[dragController.DragEventParam](js-apis-arkui-dragController.md#drageventparam12)> | 拖拽结束返回结果的回调
- event：拖拽事件信息，仅包括拖拽结果。
- extraParams：拖拽事件额外信息。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal handling failed. | **示例：** ```ts import { dragController } from "@kit.ArkUI" import { image } from '@kit.ImageKit'; import { unifiedDataChannel } from '@kit.ArkData'; @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 unifiedDataChannel.Text() let unifiedData = new unifiedDataChannel.UnifiedData(text) let dragInfo: dragController.DragInfo = { pointerId: 0, data: unifiedData, extraParams: '' } let pb:CustomBuilder = ():void=>{this.PixmapBuilder()} this.getUIContext().getComponentSnapshot().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() this.getUIContext().getDragController().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%') } } ``` ### createDragAction11+ createDragAction(customArray: Array<CustomBuilder \| DragItemInfo>, dragInfo: dragController.DragInfo): dragController.DragAction 创建拖拽的Action对象，需要显式指定拖拽背板图(可多个)，以及拖拽的数据，跟手点等信息；当通过一个已创建的 Action 对象发起的拖拽未结束时，无法再次创建新的 Action 对象，接口会抛出异常；当Action对象的生命周期结束后，注册在该对象上的回调函数会失效，因此需要在一个尽量长的作用域下持有该对象，并在每次发起拖拽前通过createDragAction返回新的对象覆盖旧值。 **说明：** 建议控制传递的拖拽背板数量，传递过多容易导致拖起的效率问题。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | -------------------------------- | | customArray | Array<[CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo说明)> | 是 | 拖拽发起后跟手效果所拖拽的对象。 | | dragInfo | [dragController.DragInfo](js-apis-arkui-dragController.md#draginfo) | 是 | 拖拽信息。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------ | ------------------ | | [dragController.DragAction](js-apis-arkui-dragController.md#dragaction11)| 创建拖拽Action对象，主要用于后面实现注册监听拖拽状态改变事件和启动拖拽服务。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Internal handling failed. | **示例：** 1.在EntryAbility.ets中获取UI上下文并保存至LocalStorage中。 ```ts import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; import { window, UIContext } from '@kit.ArkUI'; 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', this.storage, (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.error('Failed to abtain the main window. Cause:' + err.message); return; } let windowClass: window.Window = data; uiContext = windowClass.getUIContext(); this.storage.setOrCreate('uiContext', uiContext); // 获取UIContext实例 }) }); } 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.通过this.getUIContext().getSharedLocalStorage()获取上下文，进而获取DragController对象实施后续操作。 ```ts import { dragController, componentSnapshot, UIContext, DragController } from "@kit.ArkUI" import { image } from '@kit.ImageKit'; import { unifiedDataChannel } from '@kit.ArkData'; @Entry() @Component struct DragControllerPage { @State pixmap: image.PixelMap|null = null private dragAction: dragController.DragAction|null = null; customBuilders:Array = new Array(); storages = this.getUIContext().getSharedLocalStorage() @Builder DraggingBuilder() { Column() { Text("DraggingBuilder") } .width(100) .height(100) .backgroundColor(Color.Blue) } build() { Column() { Column() { Text("测试") } .width(100) .height(100) .backgroundColor(Color.Red) Button('多对象dragAction customBuilder拖拽').onTouch((event?:TouchEvent) => { if(event){ if (event.type == TouchType.Down) { console.info("muti drag Down by listener"); this.customBuilders.push(()=>{this.DraggingBuilder()}); this.customBuilders.push(()=>{this.DraggingBuilder()}); this.customBuilders.push(()=>{this.DraggingBuilder()}); let text = new unifiedDataChannel.Text() let unifiedData = new unifiedDataChannel.UnifiedData(text) let dragInfo: dragController.DragInfo = { pointerId: 0, data: unifiedData, extraParams: '' } try{ let uiContext: UIContext = this.storages?.get('uiContext') as UIContext; this.dragAction = uiContext.getDragController().createDragAction(this.customBuilders, dragInfo) if(!this.dragAction){ console.info("listener dragAction is null"); return } this.dragAction.on('statusChange', (dragAndDropInfo)=>{ if (dragAndDropInfo.status == dragController.DragStatus.STARTED) { console.info("drag has start"); } else if (dragAndDropInfo.status == dragController.DragStatus.ENDED){ console.info("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.error("start drag Error:" + err.message); }) } catch(err) { console.error("create dragAction Error:" + err.message); } } } }).margin({top:20}) } } } ``` ### getDragPreview11+ getDragPreview(): dragController.DragPreview 返回一个代表拖拽背板的对象。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | ------------------------------------------------------------ | | [dragController.DragPreview](js-apis-arkui-dragController.md#dragpreview11) | 一个代表拖拽背板的对象，提供背板样式设置的接口，在OnDrop和OnDragEnd回调中使用不生效。 | **错误码：** 通用错误码请参考[通用错误码说明文档](../errorcode-universal.md)。 **示例：** 请参考[animate](js-apis-arkui-dragController.md#animate11) ### setDragEventStrictReportingEnabled12+ setDragEventStrictReportingEnabled(enable: boolean): void 当目标从父组件拖拽到子组件时，通过该方法设置是否会触发父组件的onDragLeave的回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** : SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | | enable | boolean | 是 | 将目标从父组件拖拽到子组件时，是否会触发父组件的onDragLeave的回调。true表示触发父组件的onDragLeave的回调，false表示不触发。 | **示例：** ```ts import { UIAbility } from '@kit.AbilityKit'; import { window, UIContext } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage): void { windowStage.loadContent('pages/Index', (err, data) => { if (err.code) { return; } windowStage.getMainWindow((err, data) => { if (err.code) { return; } let windowClass: window.Window = data; let uiContext: UIContext = windowClass.getUIContext(); uiContext.getDragController().setDragEventStrictReportingEnabled(true); }); }); } } ``` ### cancelDataLoading15+ cancelDataLoading(key: string): void 当使用[startDataLoading](arkui-ts/ts-universal-events-drag-drop.md#dragevent7)获取拖拽数据时，可调用该接口取消数据传输。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：** : SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | | key | string | 是 | 拖拽数据的标识，用于区分每次拖拽。key可通过startDataLoading接口获取。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[拖拽事件错误码](./errorcode-drag-event.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. | | 190004 | Operation failed. | ### notifyDragStartRequest18+ notifyDragStartRequest(requestStatus: dragController.DragStartRequestStatus): void 控制应用是否可以发起拖拽。 **原子化服务API**: 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力**: SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填| 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | | requestStatus | [dragController.DragStartRequestStatus](js-apis-arkui-dragController.md#dragstartrequeststatus18) | 是 |定义应用是否可以发起拖拽。| **示例：** ```ts import { unifiedDataChannel } from '@kit.ArkData'; import { image } from '@kit.ImageKit'; import { dragController } from "@kit.ArkUI"; // xxx.ets @Entry @Component struct NormalEts { @State finished: boolean = false @State timeout1: number = 1 @State pixmap: image.PixelMap | undefined = undefined @State unifiedData1: unifiedDataChannel.UnifiedData | undefined = undefined @State previewData: DragItemInfo | undefined = undefined loadData() { let timeout = setTimeout(() => { this.getUIContext().getComponentSnapshot().get("image1", (error: Error, pixmap: image.PixelMap) => { this.pixmap = pixmap this.previewData = { pixelMap: this.pixmap } }) let data: unifiedDataChannel.Image = new unifiedDataChannel.Image(); data.imageUri = "app.media.startIcon"; let unifiedData = new unifiedDataChannel.UnifiedData(data); this.unifiedData1 = unifiedData this.getUIContext().getDragController().notifyDragStartRequest(dragController.DragStartRequestStatus.READY) }, 4000); this.timeout1 = timeout } build() { Column({space: 20}) { Image($r("app.media.startIcon")) .width(300) .height(200) .id("image1") .draggable(true) .dragPreview(this.previewData) .onPreDrag((status: PreDragStatus) => { if (status == PreDragStatus.PREPARING_FOR_DRAG_DETECTION) { this.loadData() } else { clearTimeout(this.timeout1); } }) .onDragStart((event: DragEvent) => { if (this.finished == false) { this.getUIContext().getDragController().notifyDragStartRequest(dragController.DragStartRequestStatus.WAITING) } else { event.setData(this.unifiedData1); } }) .onDragEnd(()=>{ this.finished = false }) } .height(400) .backgroundColor(Color.Pink) } } ``` ## OverlayManager12+ 以下API需先使用UIContext中的[getOverlayManager()](#getoverlaymanager12)方法获取到OverlayManager对象，再通过该对象调用对应方法。 > **说明：** > > OverlayManager上节点的层级在Page页面层级之上，在Dialog、Popup、Menu、BindSheet、BindContentCover和Toast等之下。 > > OverlayManager上节点安全区域内外的绘制方式与Page一致，键盘避让方式与Page一致。 > > 与OverlayManager相关的属性推荐采用AppStorage来进行应用全局存储，以免切换页面后属性值发生变化从而导致业务错误。 ### addComponentContent12+ addComponentContent(content: ComponentContent, index?: number): void 在OverlayManager上新增指定节点。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ----------- | | content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是 | 在OverlayManager上新增指定节点上添加此content。
**说明：**
新增的节点默认处于页面居中，按层级堆叠。| | index | number | 否 | 新增节点在OverlayManager上的层级位置。
**说明：**
当index ≥ 0时，若index的值越大，则ComponentContent的层级越高；当多个ComponentContent的index相同时，若ComponentContent添加的时间越晚，则层级越高。
当index < 0、index = null或index = undefined时，ComponentContent默认添加至最高层。
当同一个ComponentContent被添加多次时，只保留最后一次添加的ComponentContent。
**示例：** ```ts import { ComponentContent, OverlayManager } from '@kit.ArkUI'; class Params { text: string = ""; offset: Position; constructor(text: string, offset: Position) { this.text = text; this.offset = offset; } } @Builder function builderText(params: Params) { Column() { Text(params.text) .fontSize(30) .fontWeight(FontWeight.Bold) }.offset(params.offset) } @Entry @Component struct OverlayExample { @State message: string = 'ComponentContent'; private uiContext: UIContext = this.getUIContext(); private overlayNode: OverlayManager = this.uiContext.getOverlayManager(); @StorageLink('contentArray') contentArray: ComponentContent[] = []; @StorageLink('componentContentIndex') componentContentIndex: number = 0; @StorageLink('arrayIndex') arrayIndex: number = 0; @StorageLink("componentOffset") componentOffset: Position = { x: 0, y: 80 }; build() { Column() { Button("++componentContentIndex: " + this.componentContentIndex).onClick(() => { ++this.componentContentIndex; }) Button("--componentContentIndex: " + this.componentContentIndex).onClick(() => { --this.componentContentIndex; }) Button("增加ComponentContent" + this.contentArray.length).onClick(() => { let componentContent = new ComponentContent( this.uiContext, wrapBuilder<[Params]>(builderText), new Params(this.message + (this.contentArray.length), this.componentOffset) ); this.contentArray.push(componentContent); this.overlayNode.addComponentContent(componentContent, this.componentContentIndex); }) Button("++arrayIndex: " + this.arrayIndex).onClick(() => { ++this.arrayIndex; }) Button("--arrayIndex: " + this.arrayIndex).onClick(() => { --this.arrayIndex; }) Button("删除ComponentContent" + this.arrayIndex).onClick(() => { if (this.arrayIndex >= 0 && this.arrayIndex < this.contentArray.length) { let componentContent = this.contentArray.splice(this.arrayIndex, 1); this.overlayNode.removeComponentContent(componentContent.pop()); } else { console.info("arrayIndex有误"); } }) Button("显示ComponentContent" + this.arrayIndex).onClick(() => { if (this.arrayIndex >= 0 && this.arrayIndex < this.contentArray.length) { let componentContent = this.contentArray[this.arrayIndex]; this.overlayNode.showComponentContent(componentContent); } else { console.info("arrayIndex有误"); } }) Button("隐藏ComponentContent" + this.arrayIndex).onClick(() => { if (this.arrayIndex >= 0 && this.arrayIndex < this.contentArray.length) { let componentContent = this.contentArray[this.arrayIndex]; this.overlayNode.hideComponentContent(componentContent); } else { console.info("arrayIndex有误"); } }) Button("显示所有ComponentContent").onClick(() => { this.overlayNode.showAllComponentContents(); }) Button("隐藏所有ComponentContent").onClick(() => { this.overlayNode.hideAllComponentContents(); }) Button("跳转页面").onClick(() => { this.getUIContext().getRouter().pushUrl({ url: 'pages/Second' }) }) } .width('100%') .height('100%') } } ``` ### addComponentContentWithOrder18+ addComponentContentWithOrder(content: ComponentContent, levelOrder?: LevelOrder): void 指定显示顺序创建浮层节点。 支持在浮层节点创建时指定显示的顺序。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ----------- | | content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是 | 在OverlayManager上新增指定节点上添加此content。
**说明：**
新增的节点默认处于页面居中位置，按层级堆叠。| | levelOrder | [LevelOrder](js-apis-promptAction.md#levelorder18) | 否 | 新增浮层节点的显示顺序。
**说明：**
- 默认值：LevelOrder.clamp(0)。| **示例：** 该示例通过调用addComponentContentWithOrder接口，展示了指定显示顺序创建浮层节点的功能。 ```ts import { ComponentContent, PromptAction, LevelOrder, UIContext, OverlayManager } from '@kit.ArkUI'; class Params { text: string = "" offset: Position constructor(text: string, offset: Position) { this.text = text this.offset = offset } } @Builder function builderText(params: Params) { Column() { Text(params.text) .fontSize(30) .fontWeight(FontWeight.Bold) }.offset(params.offset) } @Entry @Component struct Index { @State message: string = '弹窗' private ctx: UIContext = this.getUIContext() private promptAction: PromptAction = this.ctx.getPromptAction() private overlayNode: OverlayManager = this.ctx.getOverlayManager() @StorageLink('contentArray') contentArray: ComponentContent[] = [] @StorageLink('componentContentIndex') componentContentIndex: number = 0 @StorageLink('arrayIndex') arrayIndex: number = 0 @StorageLink("componentOffset") componentOffset: Position = {x: 0, y: 80} build() { Row() { Column({ space: 10 }) { Button('OverlayManager下面弹窗') .fontSize(20) .onClick(() => { let componentContent = new ComponentContent( this.ctx, wrapBuilder<[Params]>(builderText), new Params(this.message + (this.contentArray.length), this.componentOffset) ) this.contentArray.push(componentContent) this.overlayNode.addComponentContentWithOrder(componentContent, LevelOrder.clamp(100.1)) let topOrder: LevelOrder = this.promptAction.getTopOrder(); if (topOrder !== undefined) { console.error('topOrder: ' + topOrder.getOrder()); } let bottomOrder: LevelOrder = this.promptAction.getBottomOrder(); if (bottomOrder !== undefined) { console.error('bottomOrder: ' + bottomOrder.getOrder()); } }) Button('OverlayManager上面弹窗') .fontSize(20) .onClick(() => { let componentContent = new ComponentContent( this.ctx, wrapBuilder<[Params]>(builderText), new Params(this.message + (this.contentArray.length), this.componentOffset) ) this.contentArray.push(componentContent) this.overlayNode.addComponentContentWithOrder(componentContent, LevelOrder.clamp(100.2)) let topOrder: LevelOrder = this.promptAction.getTopOrder(); if (topOrder !== undefined) { console.error('topOrder: ' + topOrder.getOrder()); } let bottomOrder: LevelOrder = this.promptAction.getBottomOrder(); if (bottomOrder !== undefined) { console.error('bottomOrder: ' + bottomOrder.getOrder()); } }) }.width('100%') }.height('100%') } } ``` ### removeComponentContent12+ removeComponentContent(content: ComponentContent): void 在overlay上删除指定节点。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ----------- | | content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是 | 在OverlayManager上删除此content。 | **示例：** 请参考[addComponentContent示例](#addcomponentcontent12) ### showComponentContent12+ showComponentContent(content: ComponentContent): void 在OverlayManager上显示指定节点。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ----------- | | content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是 | 在OverlayManager上显示此content。| **示例：** 请参考[addComponentContent示例](#addcomponentcontent12) ### hideComponentContent12+ hideComponentContent(content: ComponentContent): void 在OverlayManager上隐藏指定节点。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ----------- | | content | [ComponentContent](js-apis-arkui-ComponentContent.md) | 是 | 在OverlayManager上隐藏此content。 | **示例：** 请参考[addComponentContent示例](#addcomponentcontent12) ### showAllComponentContents12+ showAllComponentContents(): void 显示OverlayManager上所有的ComponentContent。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** 请参考[addComponentContent示例](#addcomponentcontent12) ### hideAllComponentContents12+ hideAllComponentContents(): void 隐藏OverlayManager上的所有ComponentContent。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** 请参考[addComponentContent示例](#addcomponentcontent12) ## OverlayManagerOptions15+ 初始化[OverlayManager](#overlaymanager12)时所用参数。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | --------------- | ---------------------- | ------------ | --------------------- | | renderRootOverlay | boolean | 否 | 是否渲染overlay根节点，true表示渲染overlay根节点，false表示不渲染overlay根节点，默认值为true。| ## AtomicServiceBar11+ 以下接口需要先使用UIContext中的[getAtomicServiceBar](#getatomicservicebar11)方法获取到AtomicServiceBar对象，再通过该对象调用对应方法。 > **说明：** > > 从API version 12开始原子化服务menuBar样式变更，以下接口将失效。 ### setVisible11+ setVisible(visible: boolean): void 通过该方法设置原子化服务menuBar是否可见。 > **说明：** > > 从API version 12开始原子化服务menuBar样式变更，menuBar默认隐藏，变为悬浮按钮，通过该接口无法改变menuBar的可见性。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ------- | ------- | | visible | boolean | 是 | 原子化服务menuBar是否可见。true表示设置menuBar可见，false表示设置menuBar不可见。| **示例：** ```ts import {UIContext, AtomicServiceBar, window } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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.info(0x0000, 'testTag', 'Get AtomicServiceBar failed.'); } }); } ``` ### setBackgroundColor11+ setBackgroundColor(color:Nullable): void 通过该方法设置原子化服务menuBar的背景颜色。 > **说明：** > > 从API version 12开始原子化服务menuBar样式变更，menuBar的背景默认隐藏，通过该接口无法改变menuBar的背景颜色。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ------ | ------ | | color | Nullable\<[Color](arkui-ts/ts-appendix-enums.md#color) \| number \| string> | 是 | 通过该方法设置原子化服务menuBar的背景颜色，undefined代表使用默认颜色。number为HEX格式颜色，支持rgb或者argb，示例：0xffffff。string为rgb或者argb格式颜色，示例：'#ffffff'。| **示例：** ```ts import {UIContext, AtomicServiceBar,window } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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 通过该方法设置原子化服务menuBar的标题内容。 > **说明：** > > 从API version 12开始原子化服务menuBar样式变更，menuBar的标题默认隐藏，通过该接口无法改变menuBar的标题内容。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** |参数名|类型|必填|说明 | | ------- | ------- | ------- | ------- | | content | string | 是 | 原子化服务menuBar中的标题内容。| **示例：** ```ts import {UIContext, AtomicServiceBar,window } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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.info(0x0000, 'testTag', 'Get AtomicServiceBar failed.'); } }); } ``` ### setTitleFontStyle11+ setTitleFontStyle(font:FontStyle):void 通过该方法设置原子化服务menuBar的字体样式。 > **说明：** > > 从API version 12开始原子化服务menuBar样式变更，menuBar的标题默认隐藏，通过该接口无法改变menuBar的字体样式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ------ | ------ | | font | [FontStyle](arkui-ts/ts-appendix-enums.md#fontstyle) | 是 | 原子化服务menuBar中的字体样式。 | **示例：** ```ts import {UIContext, Font, AtomicServiceBar } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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.info(0x0000, 'testTag', 'Get AtomicServiceBar failed.'); } }); } ``` ### setIconColor11+ setIconColor(color:Nullable): void 通过该方法设置原子化服务图标的颜色。 > **说明：** > > 从API version 12开始原子化服务menuBar样式变更，menuBar默认隐藏，悬浮按钮图标不予用户设置，通过该接口无法改变menuBar的图标颜色。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ------- | ------- | | color | Nullable\<[Color](arkui-ts/ts-appendix-enums.md#color) \| number \| string> | 是 | 原子化服务图标的颜色，undefined代表使用默认颜色。number为HEX格式颜色，支持rgb或者argb，示例：0xffffff。string为rgb或者argb格式颜色，示例：'#ffffff'。 | **示例：** ```ts import {UIContext, Font, window } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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.info(0x0000, 'testTag', 'Get AtomicServiceBar failed.'); } }); } ``` ### getBarRect15+ getBarRect(): Frame 获取原子化服务menuBar相对窗口的布局信息。 > **说明：** > > 布局信息包含了原子化服务menuBar的左右margin。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ----------------- | ------------- | | [Frame](./js-apis-arkui-graphics.md#frame) | 原子化服务menuBar的大小和位置。 | **示例：** ```ts import { AtomicServiceBar } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; @Entry @Component struct Index { build() { Button("getBarRect") .onClick(() => { let uiContext: UIContext = this.getUIContext(); let currentBar: Nullable = uiContext.getAtomicServiceBar(); if (currentBar != undefined) { let rect = currentBar.getBarRect(); hilog.info(0x0000, 'testTag', 'Get AtomServiceBar Successfully. x:' + rect.x + ' y:' + rect.y + ' width:' + rect.width + ' height:' + rect.height); } else { hilog.info(0x0000, 'testTag', 'Get AtomServiceBar failed.'); } }) } } ``` ## KeyboardAvoidMode11+ 配置键盘避让时页面的避让模式。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 值 | 说明 | | ------ | ---- | ---------- | | OFFSET | 0 | 上抬模式。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| | RESIZE | 1 | 压缩模式。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| | OFFSET_WITH_CARET14+ | 2 | 上抬模式，输入框光标位置发生变化时候也会触发避让。
**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| | RESIZE_WITH_CARET14+ | 3 | 压缩模式，输入框光标位置发生变化时候也会触发避让。
**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| | NONE14+ | 4 | 不避让键盘。
**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| ## FocusController12+ 以下API需先使用UIContext中的[getFocusController()](js-apis-arkui-UIContext.md#getFocusController12)方法获取UIContext实例，再通过此实例调用对应方法。 ### clearFocus12+ clearFocus(): void 清除焦点，将焦点强制转移到页面根容器节点，焦点链路上其他节点失焦。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** ```ts @Entry @Component struct ClearFocusExample { @State inputValue: string = '' @State btColor: Color = Color.Blue build() { Column({ space: 20 }) { Column({ space: 5 }) { Button('button1') .width(200) .height(70) .fontColor(Color.White) .focusOnTouch(true) .backgroundColor(Color.Blue) Button('button2') .width(200) .height(70) .fontColor(Color.White) .focusOnTouch(true) .backgroundColor(this.btColor) .defaultFocus(true) .onFocus(() => { this.btColor = Color.Red }) .onBlur(() => { this.btColor = Color.Blue }) Button('clearFocus') .width(200) .height(70) .fontColor(Color.White) .backgroundColor(Color.Blue) .onClick(() => { this.getUIContext().getFocusController().clearFocus() }) } } .width('100%') .height('100%') } } ``` ### requestFocus12+ requestFocus(key: string): void 通过组件的id将焦点转移到组件树对应的实体节点。当前帧生效。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ------- | ------- | | key | string | 是 | 节点对应的[组件标识](arkui-ts/ts-universal-attributes-component-id.md)。| **错误码：** 以下错误码的详细介绍请参见[焦点错误码](errorcode-focus.md)。 | 错误码ID | 错误信息 | | -------- | ----------------------------------------------- | | 150001 | the component cannot be focused. | | 150002 | This component has an unfocusable ancestor. | | 150003 | the component is not on tree or does not exist. | **示例：** ```ts @Entry @Component struct RequestExample { @State btColor: Color = Color.Blue build() { Column({ space: 20 }) { Column({ space: 5 }) { Button('Button') .width(200) .height(70) .fontColor(Color.White) .focusOnTouch(true) .backgroundColor(this.btColor) .onFocus(() => { this.btColor = Color.Red }) .onBlur(() => { this.btColor = Color.Blue }) .id("testButton") Divider() .vertical(false) .width("80%") .backgroundColor(Color.Black) .height(10) Button('requestFocus') .width(200) .height(70) .onClick(() => { this.getUIContext().getFocusController().requestFocus("testButton") }) Button('requestFocus fail') .width(200) .height(70) .onClick(() => { try { this.getUIContext().getFocusController().requestFocus("eee") } catch (error) { console.error('requestFocus failed code is ' + error.code + ' message is ' + error.message) } }) } } .width('100%') .height('100%') } } ``` ### activate14+ activate(isActive: boolean, autoInactive?: boolean): void 设置当前界面的[焦点激活态](../../ui/arkts-common-events-focus-event.md)。 **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ------- | ------- | | isActive| boolean| 是 | 设置是否进入/退出焦点激活态。
true表示设置进入焦点激活态，false表示设置退出焦点激活态。 | | autoInactive | boolean | 否 | 设置焦点激活态退出逻辑。
为true时，会自动在触摸事件、鼠标事件触发时退出，为false时，仅受开发者API控制。
默认值：true | ```ts // 该示例表示在页面加载完成时进入焦点激活态，可按方向键在button间走焦 @Entry @Component struct ActivateExample { aboutToAppear() { this.getUIContext().getFocusController().activate(true, false) } aboutToDisappear() { this.getUIContext().getFocusController().activate(false) } build() { Row() { Button('Button1') .width(200) .height(70) .defaultFocus(true) Button('Button2') .width(200) .height(70) Button('Button3') .width(200) .height(70) } .padding(10) .justifyContent(FlexAlign.SpaceBetween) .width(800) } } ``` ### setAutoFocusTransfer14+ setAutoFocusTransfer(isAutoFocusTransfer: boolean): void; 设置页面切换时，新的页面是否需要主动获取焦点。 **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ------- | ------- | | isAutoFocusTransfer | boolean| 是 | 设置页面切换时，新的页面是否需要主动获取焦点，例如[Router](js-apis-router.md#routerpushurldeprecated)、[Navigation](arkui-ts/ts-basic-components-navigation.md#navigation)、[Menu](arkui-ts/ts-basic-components-menu.md#menu)、[Dialog](arkui-ts/ohos-arkui-advanced-Dialog.md)、[Popup](arkui-ts/ohos-arkui-advanced-Popup.md#popup)等。true表示需要主动获取焦点，false表示不需要主动获取焦点。默认值为true。 | ```ts @CustomDialog struct CustomDialogExample { controller?: CustomDialogController build() { Column() { Text('这是自定义弹窗') .fontSize(30) .height(100) Text('弹窗不能主动获取焦点') .fontSize(20) .height(100) Button('点我关闭弹窗') .onClick(() => { if (this.controller != undefined) { this.getUIContext().getFocusController().setAutoFocusTransfer(true) this.controller.close() } }) .margin(20) } } } @Entry @Component struct CustomDialogUser { dialogController: CustomDialogController | null = new CustomDialogController({ builder: CustomDialogExample({ }), }) aboutToDisappear() { this.dialogController = null } build() { Column() { Button('click me') .onClick(() => { if (this.dialogController != null) { this.getUIContext().getFocusController().setAutoFocusTransfer(false) this.dialogController.open() } }).backgroundColor(0x317aff) }.width('100%').margin({ top: 5 }) } } ``` ### setKeyProcessingMode15+ setKeyProcessingMode(mode: KeyProcessingMode): void 设置按键事件处理的优先级。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ------- | ------- | | mode | [KeyProcessingMode](./arkui-ts/ts-universal-attributes-focus.md#keyprocessingmode15)| 是 | 按键处理模式。 | ```ts // 该示例演示了在页面加载完成后设置走焦类型的实现方式。 @Entry @Component struct Index { aboutToAppear() { this.getUIContext().getFocusController().setKeyProcessingMode(KeyProcessingMode.ANCESTOR_EVENT) } build() { Row() { Row() { Button('Button1').id('Button1').onKeyEvent((event) => { console.log("Button1"); return true }) Button('Button2').id('Button2').onKeyEvent((event) => { console.log("Button2"); return true }) } .width('100%') .height('100%') .id('Row1') .onKeyEventDispatch((event) => { let context = this.getUIContext(); context.getFocusController().requestFocus('Button1'); return context.dispatchKeyEvent('Button1', event); }) } .height('100%') .width('100%') .onKeyEventDispatch((event) => { if (event.type == KeyType.Down) { let context = this.getUIContext(); context.getFocusController().requestFocus('Row1'); return context.dispatchKeyEvent('Row1', event); } return true; }) } } ``` ## PointerStyle12+ type PointerStyle = pointer.PointerStyle 光标样式。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.MultimodalInput.Input.Pointer |类型|说明| | -- | -- | |[pointer.PointerStyle](../apis-input-kit/js-apis-pointer.md#pointerstyle) |光标样式。| ## CursorController12+ 以下API需先使用UIContext中的[getCursorController()](js-apis-arkui-UIContext.md#getcursorcontroller12)方法获取CursorController实例，再通过此实例调用对应方法。 ### restoreDefault12+ restoreDefault(): void 恢复默认的光标样式 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** 当光标移出绿框时，通过CursorController的restoreDefault方法恢复默认光标样式 ```ts import { pointer } from '@kit.InputKit'; import { UIContext, CursorController } from '@kit.ArkUI'; @Entry @Component struct CursorControlExample { @State text: string = '' cursorCustom: CursorController = this.getUIContext().getCursorController(); build() { Column() { Row().height(200).width(200).backgroundColor(Color.Green).position({x: 150 ,y:70}) .onHover((flag) => { if (flag) { this.cursorCustom.setCursor(pointer.PointerStyle.EAST) } else { console.info("restoreDefault"); this.cursorCustom.restoreDefault(); } }) }.width('100%') } } ``` ![cursor-restoreDefault](figures/cursor-restoreDefault.gif) ### setCursor12+ setCursor(value: PointerStyle): void 更改当前的鼠标光标样式 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------- | ---- | ------- | | value | [PointerStyle](#pointerstyle12) | 是 | 光标样式 | **示例：** 当光标进入蓝框时，通过CursorController的setCursor方法修改光标样式为PointerStyle.WEST ```ts import { pointer } from '@kit.InputKit'; import { UIContext, CursorController } from '@kit.ArkUI'; @Entry @Component struct CursorControlExample { @State text: string = '' cursorCustom: CursorController = this.getUIContext().getCursorController(); build() { Column() { Row().height(200).width(200).backgroundColor(Color.Blue).position({x: 100 ,y:70}) .onHover((flag) => { if (flag) { this.cursorCustom.setCursor(pointer.PointerStyle.WEST) } else { this.cursorCustom.restoreDefault(); } }) }.width('100%') } } ``` ![cursor-setCursor](figures/cursor-setCursor.gif) ## ContextMenuController12+ 以下API需先使用UIContext中的[getContextMenuController()](js-apis-arkui-UIContext.md#getcontextmenucontroller12)方法获取ContextMenuController实例，再通过此实例调用对应方法。 ### close12+ close(): void 关闭菜单 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **示例：** 通过定时器触发，调用ContextMenuController的close方法关闭菜单 ```ts import { ContextMenuController } from '@kit.ArkUI'; @Entry @Component struct Index { menu: ContextMenuController = this.getUIContext().getContextMenuController(); @Builder MenuBuilder() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button('Test ContextMenu1 Close') Divider().strokeWidth(2).margin(5).color(Color.Black) Button('Test ContextMenu2') Divider().strokeWidth(2).margin(5).color(Color.Black) Button('Test ContextMenu3') } .width(200) .height(160) } build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Button("启动定时器").onClick(()=> { setTimeout(() => { this.menu.close(); }, 10000); }) Column() { Text("Test ContextMenu close") .fontSize(20) .width('100%') .height(500) .backgroundColor(0xAFEEEE) .textAlign(TextAlign.Center) } .bindContextMenu(this.MenuBuilder, ResponseType.LongPress) } .width('100%') .height('100%') } } ``` ![contextMenuController_close](figures/contextMenuController_close.gif) ## MeasureUtils12+ 以下API需先使用UIContext中的[getMeasureUtils()](js-apis-arkui-UIContext.md#getmeasureutils12)方法获取MeasureUtils实例，再通过此实例调用对应方法。 ### measureText12+ measureText(options: MeasureOptions): number 计算指定文本单行布局下的宽度。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------- | ---- | --------- | | options | [MeasureOptions](js-apis-measure.md#measureoptions) | 是 | 被计算文本描述信息。 | **返回值：** | 类型 | 说明 | | ------------ | --------- | | number | 文本宽度。
**说明:**
单位px。 | **示例：** 通过MeasureUtils的measureText方法获取"Hello World"文字的宽度。 ```ts import { MeasureUtils } from '@kit.ArkUI'; @Entry @Component struct Index { @State uiContext: UIContext = this.getUIContext(); @State uiContextMeasure: MeasureUtils = this.uiContext.getMeasureUtils(); @State textWidth: number = this.uiContextMeasure.measureText({ textContent: "Hello World", fontSize: '50px' }) build() { Row() { Column() { Text(`The width of 'Hello World': ${this.textWidth}`) } .width('100%') } .height('100%') } } ``` ### measureTextSize12+ measureTextSize(options: MeasureOptions): SizeOptions 计算指定文本单行布局下的宽度和高度。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------- | ---- | --------- | | options | [MeasureOptions](js-apis-measure.md#measureoptions) | 是 | 被计算文本描述信息。 | **返回值：** | 类型 | 说明 | | ------------ | --------- | | [SizeOption](arkui-ts/ts-types.md#sizeoptions) | 返回文本所占布局宽度和高度。
**说明:**
文本宽度以及高度返回值单位均为px。 | **示例：** 通过MeasureUtils的measureTextSize方法获取"Hello World"文字的宽度和高度 ```ts import { MeasureUtils } from '@kit.ArkUI'; @Entry @Component struct Index { @State uiContext: UIContext = this.getUIContext(); @State uiContextMeasure: MeasureUtils = this.uiContext.getMeasureUtils(); textSize : SizeOptions = this.uiContextMeasure.measureTextSize({ textContent: "Hello World", fontSize: '50px' }) build() { Row() { Column() { Text(`The width of 'Hello World': ${this.textSize.width}`) Text(`The height of 'Hello World': ${this.textSize.height}`) } .width('100%') } .height('100%') } } ``` ## ComponentSnapshot12+ 以下API需先使用UIContext中的[getComponentSnapshot()](js-apis-arkui-UIContext.md#getcomponentsnapshot12)方法获取ComponentSnapshot对象，再通过此实例调用对应方法。 缩放、平移、旋转等图形变换属性只对被截图组件的子组件生效；对目标组件本身应用图形变换属性不生效，显示的是还是图形变换前的效果。 ### get12+ get(id: string, callback: AsyncCallback, options?: componentSnapshot.SnapshotOptions): void 获取已加载的组件的截图，传入组件的[组件标识](arkui-ts/ts-universal-attributes-component-id.md#组件标识)，找到对应组件进行截图。通过回调返回结果。 > **说明：** > > 截图会获取最近一帧的绘制内容。如果在组件触发更新的同时调用截图，更新的渲染内容不会被截取到，截图会返回上一帧的绘制内容。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | id | string | 是 | 目标组件的[组件标识](arkui-ts/ts-universal-attributes-component-id.md#组件标识)。 | | callback | [AsyncCallback](../apis-basic-services-kit/js-apis-base.md#asynccallback)<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 截图返回结果的回调。 | | options12+ | [componentSnapshot.SnapshotOptions](js-apis-arkui-componentSnapshot.md#snapshotoptions12) | 否 | 截图相关的自定义参数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Invalid ID. | **示例：** ```ts import { image } from '@kit.ImageKit'; import { UIContext } from '@kit.ArkUI'; @Entry @Component struct SnapshotExample { @State pixmap: image.PixelMap | undefined = undefined uiContext: UIContext = this.getUIContext(); build() { Column() { Row() { Image(this.pixmap).width(150).height(150).border({ color: Color.Black, width: 2 }).margin(5) Image($r('app.media.img')).autoResize(true).width(150).height(150).margin(5).id("root") } Button("click to generate UI snapshot") .onClick(() => { this.uiContext.getComponentSnapshot().get("root", (error: Error, pixmap: image.PixelMap) => { if (error) { console.error("error: " + JSON.stringify(error)) return; } this.pixmap = pixmap }, {scale : 2, waitUntilRenderFinished : true}) }).margin(10) } .width('100%') .height('100%') .alignItems(HorizontalAlign.Center) } } ``` ### get12+ get(id: string, options?: componentSnapshot.SnapshotOptions): Promise 获取已加载的组件的截图，传入组件的[组件标识](arkui-ts/ts-universal-attributes-component-id.md#组件标识)，找到对应组件进行截图。通过Promise返回结果。 > **说明：** > > 截图会获取最近一帧的绘制内容。如果在组件触发更新的同时调用截图，更新的渲染内容不会被截取到，截图会返回上一帧的绘制内容。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------------------------------------ | | id | string | 是 | 目标组件的[组件标识](arkui-ts/ts-universal-attributes-component-id.md#组件标识)。 | | options12+ | [componentSnapshot.SnapshotOptions](js-apis-arkui-componentSnapshot.md#snapshotoptions12) | 否 | 截图相关的自定义参数。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | ---------------- | | Promise<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 截图返回的结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Invalid ID. | **示例：** ```ts import { image } from '@kit.ImageKit'; import { UIContext } from '@kit.ArkUI'; @Entry @Component struct SnapshotExample { @State pixmap: image.PixelMap | undefined = undefined uiContext: UIContext = this.getUIContext(); build() { Column() { Row() { Image(this.pixmap).width(150).height(150).border({ color: Color.Black, width: 2 }).margin(5) Image($r('app.media.icon')).autoResize(true).width(150).height(150).margin(5).id("root") } Button("click to generate UI snapshot") .onClick(() => { this.uiContext.getComponentSnapshot() .get("root", {scale : 2, waitUntilRenderFinished : true}) .then((pixmap: image.PixelMap) => { this.pixmap = pixmap }) .catch((err: Error) => { console.error("error: " + err) }) }).margin(10) } .width('100%') .height('100%') .alignItems(HorizontalAlign.Center) } } ``` ### createFromBuilder12+ createFromBuilder(builder: CustomBuilder, callback: AsyncCallback, delay?: number, checkImageStatus?: boolean, options?: componentSnapshot.SnapshotOptions): void 在应用后台渲染[CustomBuilder](arkui-ts/ts-types.md#custombuilder8)自定义组件，并输出其截图。通过回调返回结果。 > **说明：** > > 由于需要等待组件构建、渲染成功，离屏截图的回调有500ms以内的延迟。 > > 部分执行耗时任务的组件可能无法及时在截图前加载完成，因此会截取不到加载成功后的图像。例如：加载网络图片的[Image](arkui-ts/ts-basic-components-image.md)组件、[Web](../apis-arkweb/ts-basic-components-web.md)组件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) | 是 | 自定义组件构建函数。
**说明：** 不支持全局builder。 | | callback | [AsyncCallback](../apis-basic-services-kit/js-apis-base.md#asynccallback)<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 截图返回结果的回调。支持在回调中获取离屏组件绘制区域坐标和大小。 | | delay12+ | number | 否 | 指定触发截图指令的延迟时间。当布局中使用了图片组件时，需要指定延迟时间，以便系统解码图片资源。资源越大，解码需要的时间越长，建议尽量使用不需要解码的PixelMap资源。
当使用PixelMap资源或对Image组件设置syncload为true时，可以配置delay为0，强制不等待触发截图。该延迟时间并非指接口从调用到返回的时间，由于系统需要对传入的builder进行临时离屏构建，因此返回的时间通常要比该延迟时间长。
**说明：** 截图接口传入的builder中，不应使用状态变量控制子组件的构建，如果必须要使用，在调用截图接口时，也不应再有变化，以避免出现截图不符合预期的情况。
默认值：300
单位：毫秒
取值范围：[0, +∞)，小于0时按默认值处理。 | | checkImageStatus12+ | boolean | 否 | 指定是否允许在截图之前，校验图片解码状态。如果为true，则会在截图之前检查所有Image组件是否已经解码完成，如果没有完成检查，则会放弃截图并返回异常。
默认值：false| | options12+ | [componentSnapshot.SnapshotOptions](js-apis-arkui-componentSnapshot.md#snapshotoptions12) | 否 | 截图相关的自定义参数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | The builder is not a valid build function. | | 160001 | An image component in builder is not ready for taking a snapshot. The check for the ready state is required when the checkImageStatus option is enabled. | **示例：** ```ts import { image } from '@kit.ImageKit'; import { UIContext } from '@kit.ArkUI'; @Entry @Component struct ComponentSnapshotExample { @State pixmap: image.PixelMap | undefined = undefined uiContext: UIContext = this.getUIContext(); @Builder RandomBuilder() { Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { Text('Test menu item 1') .fontSize(20) .width(100) .height(50) .textAlign(TextAlign.Center) Divider().height(10) Text('Test menu item 2') .fontSize(20) .width(100) .height(50) .textAlign(TextAlign.Center) } .width(100) .id("builder") } build() { Column() { Button("click to generate UI snapshot") .onClick(() => { this.uiContext.getComponentSnapshot().createFromBuilder(() => { this.RandomBuilder() }, (error: Error, pixmap: image.PixelMap) => { if (error) { console.error("error: " + JSON.stringify(error)) return; } this.pixmap = pixmap }, 320, true, {scale : 2, waitUntilRenderFinished : true}) }) Image(this.pixmap) .margin(10) .height(200) .width(200) .border({ color: Color.Black, width: 2 }) }.width('100%').margin({ left: 10, top: 5, bottom: 5 }).height(300) } } ``` ### createFromBuilder12+ createFromBuilder(builder: CustomBuilder, delay?: number, checkImageStatus?: boolean, options?: componentSnapshot.SnapshotOptions): Promise 在应用后台渲染[CustomBuilder](arkui-ts/ts-types.md#custombuilder8)自定义组件，并输出其截图。通过Promise返回结果。 > **说明：** > > 由于需要等待组件构建、渲染成功，离屏截图的回调有500ms以内的延迟。 > > 部分执行耗时任务的组件可能无法及时在截图前加载完成，因此会截取不到加载成功后的图像。例如：加载网络图片的[Image](arkui-ts/ts-basic-components-image.md)组件、[Web](../apis-arkweb/ts-basic-components-web.md)组件。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------------------- | ---- | ------------------------------------------------------- | | builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) | 是 | 自定义组件构建函数。
**说明：** 不支持全局builder。 | | delay12+ | number | 否 | 指定触发截图指令的延迟时间。当布局中使用了图片组件时，需要指定延迟时间，以便系统解码图片资源。资源越大，解码需要的时间越长，建议尽量使用不需要解码的PixelMap资源。
当使用PixelMap资源或对Image组件设置syncload为true时，可以配置delay为0，强制不等待触发截图。该延迟时间并非指接口从调用到返回的时间，由于系统需要对传入的builder进行临时离屏构建，因此返回的时间通常要比该延迟时间长。
**说明：** 截图接口传入的builder中，不应使用状态变量控制子组件的构建，如果必须要使用，在调用截图接口时，也不应再有变化，以避免出现截图不符合预期的情况。
默认值：300
单位：毫秒| | checkImageStatus12+ | boolean | 否 | 指定是否允许在截图之前，校验图片解码状态。如果为true，则会在截图之前检查所有Image组件是否已经解码完成，如果没有完成检查，则会放弃截图并返回异常。
默认值：false| | options12+ | [componentSnapshot.SnapshotOptions](js-apis-arkui-componentSnapshot.md#snapshotoptions12) | 否 | 截图相关的自定义参数。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | ---------------- | | Promise<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 截图返回的结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | The builder is not a valid build function. | | 160001 | An image component in builder is not ready for taking a snapshot. The check for the ready state is required when the checkImageStatus option is enabled. | **示例：** ```ts import { image } from '@kit.ImageKit'; import { UIContext } from '@kit.ArkUI'; @Entry @Component struct ComponentSnapshotExample { @State pixmap: image.PixelMap | undefined = undefined uiContext: UIContext = this.getUIContext(); @Builder RandomBuilder() { Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { Text('Test menu item 1') .fontSize(20) .width(100) .height(50) .textAlign(TextAlign.Center) Divider().height(10) Text('Test menu item 2') .fontSize(20) .width(100) .height(50) .textAlign(TextAlign.Center) } .width(100) .id("builder") } build() { Column() { Button("click to generate UI snapshot") .onClick(() => { this.uiContext.getComponentSnapshot() .createFromBuilder(() => { this.RandomBuilder() }, 320, true, {scale : 2, waitUntilRenderFinished : true}) .then((pixmap: image.PixelMap) => { this.pixmap = pixmap }) .catch((err: Error) => { console.error("error: " + err) }) }) Image(this.pixmap) .margin(10) .height(200) .width(200) .border({ color: Color.Black, width: 2 }) }.width('100%').margin({ left: 10, top: 5, bottom: 5 }).height(300) } } ``` ### getSync12+ getSync(id: string, options?: componentSnapshot.SnapshotOptions): image.PixelMap 获取已加载的组件的截图，传入组件的[组件标识](arkui-ts/ts-universal-attributes-component-id.md#组件标识)，找到对应组件进行截图。同步等待截图完成返回[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)。 > **说明：** > > 截图会获取最近一帧的绘制内容。如果在组件触发更新的同时调用截图，更新的渲染内容不会被截取到，截图会返回上一帧的绘制内容。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | id | string | 是 | 目标组件的[组件标识](arkui-ts/ts-universal-attributes-component-id.md#组件标识)。 | | options | [componentSnapshot.SnapshotOptions](js-apis-arkui-componentSnapshot.md#snapshotoptions12) | 否 | 截图相关的自定义参数。 | **返回值：** | 类型 | 说明 | | ----------------------------- | -------- | | image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 截图返回的结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | ------ | ------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Invalid ID. | | 160002 | Timeout. | **示例：** ```ts import { image } from '@kit.ImageKit'; import { UIContext } from '@kit.ArkUI'; @Entry @Component struct SnapshotExample { @State pixmap: image.PixelMap | undefined = undefined build() { Column() { Row() { Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5) Image($r('app.media.img')).autoResize(true).width(200).height(200).margin(5).id("root") } Button("click to generate UI snapshot") .onClick(() => { try { let pixelmap = this.getUIContext().getComponentSnapshot().getSync("root", {scale : 2, waitUntilRenderFinished : true}) this.pixmap = pixelmap } catch (error) { console.error("getSync errorCode: " + error.code + " message: " + error.message) } }).margin(10) } .width('100%') .height('100%') .alignItems(HorizontalAlign.Center) } } ``` ### getWithUniqueId15+ getWithUniqueId(uniqueId: number, options?: componentSnapshot.SnapshotOptions): Promise 获取已加载的组件的截图，传入组件的[uniqueId](js-apis-arkui-frameNode.md#getuniqueid12)，找到对应组件进行截图。通过Promise返回结果。 > **说明：** > > 截图会获取最近一帧的绘制内容。如果在组件触发更新的同时调用截图，更新的渲染内容不会被截取到，截图会返回上一帧的绘制内容。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | uniqueId | number | 是 | 目标组件的[uniqueId](js-apis-arkui-frameNode.md#getuniqueid12) | | options | [componentSnapshot.SnapshotOptions](js-apis-arkui-componentSnapshot.md#snapshotoptions12) | 否 | 截图相关的自定义参数。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------------ | ---------------- | | Promise<image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 截图返回的结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Invalid ID. | **示例：** ```ts import { NodeController, FrameNode, typeNode } from '@kit.ArkUI'; import { image } from '@kit.ImageKit'; import { UIContext } from '@kit.ArkUI'; class MyNodeController extends NodeController { public node: FrameNode | null = null; public imageNode: FrameNode | null = null; makeNode(uiContext: UIContext): FrameNode | null { this.node = new FrameNode(uiContext); this.node.commonAttribute.width('100%').height('100%') let image = typeNode.createNode(uiContext, 'Image'); image.initialize($r('app.media.img')).width('100%').height('100%').autoResize(true) this.imageNode = image; this.node.appendChild(image); return this.node; } } @Entry @Component struct SnapshotExample { private myNodeController: MyNodeController = new MyNodeController(); @State pixmap: image.PixelMap | undefined = undefined build() { Column() { Row() { Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5) NodeContainer(this.myNodeController).width(200).height(200).margin(5) } Button("UniqueId get snapshot") .onClick(() => { try { this.getUIContext() .getComponentSnapshot() .getWithUniqueId(this.myNodeController.imageNode?.getUniqueId(), {scale: 2, waitUntilRenderFinished: true}) .then((pixmap: image.PixelMap) => { this.pixmap = pixmap }) .catch((err: Error) => { console.log("error: " + err) }) } catch (error) { console.error("UniqueId get snapshot Error: " + JSON.stringify(error)) } }).margin(10) } .width('100%') .height('100%') .alignItems(HorizontalAlign.Center) } } ``` ### getSyncWithUniqueId15+ getSyncWithUniqueId(uniqueId: number, options?: componentSnapshot.SnapshotOptions): image.PixelMap 获取已加载的组件的截图，传入组件的[uniqueId](js-apis-arkui-frameNode.md#getuniqueid12)，找到对应组件进行截图。同步等待截图完成返回[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)。 > **说明：** > > 截图会获取最近一帧的绘制内容。如果在组件触发更新的同时调用截图，更新的渲染内容不会被截取到，截图会返回上一帧的绘制内容。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ---------------------------------------- | | uniqueId | number | 是 | 目标组件的[uniqueId](js-apis-arkui-frameNode.md#getuniqueid12)。 | | options | [componentSnapshot.SnapshotOptions](js-apis-arkui-componentSnapshot.md#snapshotoptions12) | 否 | 截图相关的自定义参数。 | **返回值：** | 类型 | 说明 | | ----------------------------- | -------- | | image.[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 截图返回的结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 | 错误码ID | 错误信息 | | ------ | ------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | Invalid ID. | | 160002 | Timeout. | **示例：** ```ts import { NodeController, FrameNode, typeNode } from '@kit.ArkUI'; import { image } from '@kit.ImageKit'; import { UIContext } from '@kit.ArkUI'; class MyNodeController extends NodeController { public node: FrameNode | null = null; public imageNode: FrameNode | null = null; makeNode(uiContext: UIContext): FrameNode | null { this.node = new FrameNode(uiContext); this.node.commonAttribute.width('100%').height('100%') let image = typeNode.createNode(uiContext, 'Image'); image.initialize($r('app.media.img')).width('100%').height('100%').autoResize(true) this.imageNode = image; this.node.appendChild(image); return this.node; } } @Entry @Component struct SnapshotExample { private myNodeController: MyNodeController = new MyNodeController(); @State pixmap: image.PixelMap | undefined = undefined build() { Column() { Row() { Image(this.pixmap).width(200).height(200).border({ color: Color.Black, width: 2 }).margin(5) NodeContainer(this.myNodeController).width(200).height(200).margin(5) } Button("UniqueId getSync snapshot") .onClick(() => { try { this.pixmap = this.getUIContext() .getComponentSnapshot() .getSyncWithUniqueId(this.myNodeController.imageNode?.getUniqueId(), {scale: 2, waitUntilRenderFinished: true}) } catch (error) { console.error("UniqueId getSync snapshot Error: " + JSON.stringify(error)) } }).margin(10) } .width('100%') .height('100%') .alignItems(HorizontalAlign.Center) } } ``` ### createFromComponent18+ createFromComponent\(content: ComponentContent\, delay?: number, checkImageStatus?: boolean, options?: componentSnapshot.SnapshotOptions): Promise 将传入的content对象进行截图，并通过Promise返回结果。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | content | [ComponentContent\](./js-apis-arkui-ComponentContent.md) | 是 | 当前UIContext显示的组件内容。 | | delay | number | 否 | 指定触发截图指令的延迟时间。当布局中使用了图片组件时，需要指定延迟时间，以便系统解码图片资源。资源越大，解码需要的时间越长，建议尽量使用不需要解码的PixelMap资源。
当使用PixelMap资源或对Image组件设置syncload为true时，可以配置delay为0，强制不等待触发截图。该延迟时间并非指接口从调用到返回的时间，由于系统需要对传入的builder进行临时离屏构建，因此返回的时间通常要比该延迟时间长。
**说明：** 截图接口传入的builder中，不应使用状态变量控制子组件的构建，如果必须要使用，在调用截图接口时，也不应再有变化，以避免出现截图不符合预期的情况。
取值范围：[0,+∞) ，小于0时按默认值处理。
默认值：300
单位：毫秒| | checkImageStatus | boolean | 否 | 指定是否允许在截图之前，校验图片解码状态。如果为true，则会在截图之前检查所有Image组件是否已经解码完成，如果没有完成检查，则会放弃截图并返回异常。
默认值：false| | options | [componentSnapshot.SnapshotOptions](js-apis-arkui-componentSnapshot.md#snapshotoptions12) | 否 | 截图相关的自定义参数。可以指定截图时图形侧绘制pixelmap的缩放比例与是否强制等待系统执行截图指令前所有绘制指令都执行完成之后再截图。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码和[截图错误码](errorcode-snapshot.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | | 100001 | The builder is not a valid build function. | | 160001 | An image component in builder is not ready for taking a snapshot. The check for the ready state is required when the checkImageStatus option is enabled. | **示例：** ```ts import { image } from '@kit.ImageKit'; import { ComponentContent } from '@kit.ArkUI'; class Params { text: string | undefined | null = ""; constructor(text: string | undefined | null ) { this.text = text; } } @Builder function buildText(params: Params) { ReusableChildComponent({ text: params.text }); } @Component struct ReusableChildComponent { @Prop text: string | undefined | null = ""; aboutToReuse(params: Record) { console.log("ReusableChildComponent Reusable " + JSON.stringify(params)); } aboutToRecycle(): void { console.log("ReusableChildComponent aboutToRecycle " + this.text); } build() { Column() { Text(this.text) .fontSize(90) .fontWeight(FontWeight.Bold) .margin({ bottom: 36 }) .width('100%') .height('100%') }.backgroundColor('#FFF0F0F0') } } @Entry @Component struct Index { @State pixmap: image.PixelMap | undefined = undefined @State message: string | undefined | null = "hello" uiContext: UIContext = this.getUIContext(); build() { Row() { Column() { Button("点击生成组件截图") .onClick(() => { let uiContext = this.getUIContext(); let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), new Params(this.message)); this.uiContext.getComponentSnapshot() .createFromComponent(contentNode , 320, true, {scale : 2, waitUntilRenderFinished : true}) .then((pixmap: image.PixelMap) => { this.pixmap = pixmap }) .catch((err: Error) => { console.error("error: " + err) }) }) Image(this.pixmap) .margin(10) .height(200) .width(200) .border({ color: Color.Black, width: 2 }) }.width('100%').margin({ left: 10, top: 5, bottom: 5 }).height(300) } .width('100%') .height('100%') } } ``` ## FrameCallback12+ 用于设置下一帧渲染时需要执行的任务。需要配合[UIContext](#uicontext)中的[postFrameCallback](#postframecallback12)和[postDelayedFrameCallback](#postdelayedframecallback12)使用。开发者需要继承该类并重写[onFrame](#onframe12)或[onIdle](#onidle12)方法，实现具体的业务逻辑。 ### onFrame12+ onFrame(frameTimeInNano: number): void 在下一帧进行渲染时，该方法将被执行。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------------------- | ---- | ------------------------------------------------------- | | frameTimeInNano | number | 是 | 下一帧渲染开始执行的时间，以纳秒为单位。
取值范围：[0, +∞) | **示例：** ```ts import {FrameCallback } from '@kit.ArkUI'; class MyFrameCallback extends FrameCallback { private tag: string; constructor(tag: string) { super() this.tag = tag; } onFrame(frameTimeNanos: number) { console.info('MyFrameCallback ' + this.tag + ' ' + frameTimeNanos.toString()); } } @Entry @Component struct Index { build() { Row() { Column() { Button('点击触发postFrameCallback') .onClick(() => { this.getUIContext().postFrameCallback(new MyFrameCallback("normTask")); }) Button('点击触发postDelayedFrameCallback') .onClick(() => { this.getUIContext().postDelayedFrameCallback(new MyFrameCallback("delayTask"), 5); }) } .width('100%') } .height('100%') } } ``` ### onIdle12+ onIdle(timeLeftInNano: number): void 在下一帧渲染结束时，如果距离下一个Vsync信号到来还有1ms以上的剩余时间，该方法将被执行，否则将顺延至后面的帧。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------------------------------------------- | ---- | ------------------------------------------------------- | | timeLeftInNano | number | 是 | 这一帧剩余的空闲时间，以纳秒为单位。
取值范围：[0, +∞) | **示例：** ```ts import { FrameCallback } from '@ohos.arkui.UIContext'; class MyIdleCallback extends FrameCallback { private tag: string; constructor(tag: string) { super() this.tag = tag; } onIdle(timeLeftInNano: number) { console.info('MyIdleCallback ' + this.tag + ' ' + timeLeftInNano.toString()); } } @Entry @Component struct Index { build() { Row() { Column() { Button('点击触发postFrameCallback') .onClick(() => { this.getUIContext().postFrameCallback(new MyIdleCallback("normTask")); }) Button('点击触发postDelayedFrameCallback') .onClick(() => { this.getUIContext().postDelayedFrameCallback(new MyIdleCallback("delayTask"), 5); }) } .width('100%') } .height('100%') } } ``` ## DynamicSyncScene12+ 以下接口需先使用UIContext中的requireDynamicSyncScene()方法获取DynamicSyncScene对象，再通过此实例调用对应方法。 ### setFrameRateRange12+ setFrameRateRange(range: ExpectedFrameRateRange): void 设置期望帧率范围。 最终结果不一定是设置的帧率，会由系统能力做综合决策，尽量满足开发者的设置帧率。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------- | ---- | ---- | | range | [ExpectedFrameRateRange](../apis-arkui/arkui-ts/ts-explicit-animation.md#expectedframeraterange11)| 是 | 设置期望的帧率范围。
默认值:{min:0, max:120, expected: 120} | **示例：** ```ts import { SwiperDynamicSyncSceneType, SwiperDynamicSyncScene } from '@kit.ArkUI' @Entry @Component struct Frame { @State ANIMATION:ExpectedFrameRateRange = {min:0, max:120, expected: 90} @State GESTURE:ExpectedFrameRateRange = {min:0, max:120, expected: 30} private scenes: SwiperDynamicSyncScene[] = [] build() { Column() { Text("动画"+ JSON.stringify(this.ANIMATION)) Text("跟手"+ JSON.stringify(this.GESTURE)) Row(){ Swiper() { Text("one") Text("two") Text("three") } .width('100%') .height('300vp') .id("dynamicSwiper") .backgroundColor(Color.Blue) .autoPlay(true) .onAppear(()=>{ this.scenes = this.getUIContext().requireDynamicSyncScene("dynamicSwiper") as SwiperDynamicSyncScene[] }) } Button("set frame") .onClick(()=>{ this.scenes.forEach((scenes: SwiperDynamicSyncScene) => { if (scenes.type == SwiperDynamicSyncSceneType.ANIMATION) { scenes.setFrameRateRange(this.ANIMATION) } if (scenes.type == SwiperDynamicSyncSceneType.GESTURE) { scenes.setFrameRateRange(this.GESTURE) } }); }) } } } ``` ### getFrameRateRange12+ getFrameRateRange(): ExpectedFrameRateRange 获取期望帧率范围。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ------------------- | ------- | | [ExpectedFrameRateRange](../apis-arkui/arkui-ts/ts-explicit-animation.md#expectedframeraterange11) | 期望帧率范围。| **示例：** ```ts import { SwiperDynamicSyncSceneType, SwiperDynamicSyncScene } from '@kit.ArkUI' @Entry @Component struct Frame { @State ANIMATION:ExpectedFrameRateRange = {min:0, max:120, expected: 90} @State GESTURE:ExpectedFrameRateRange = {min:0, max:120, expected: 30} private scenes: SwiperDynamicSyncScene[] = [] build() { Column() { Text("动画"+ JSON.stringify(this.ANIMATION)) Text("跟手"+ JSON.stringify(this.GESTURE)) Row(){ Swiper() { Text("one") Text("two") Text("three") } .width('100%') .height('300vp') .id("dynamicSwiper") .backgroundColor(Color.Blue) .autoPlay(true) .onAppear(()=>{ this.scenes = this.getUIContext().requireDynamicSyncScene("dynamicSwiper") as SwiperDynamicSyncScene[] }) } Button("set frame") .onClick(()=>{ this.scenes.forEach((scenes: SwiperDynamicSyncScene) => { if (scenes.type == SwiperDynamicSyncSceneType.ANIMATION) { scenes.setFrameRateRange(this.ANIMATION) scenes.getFrameRateRange() } if (scenes.type == SwiperDynamicSyncSceneType.GESTURE) { scenes.setFrameRateRange(this.GESTURE) scenes.getFrameRateRange() } }); }) } } } ``` ## SwiperDynamicSyncScene12+ SwiperDynamicSyncScene继承自[DynamicSyncScene](#dynamicsyncscene12)，对应Swiper的动态帧率场景。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 只读 | 可选 | 说明 | | --------- | --------------------------------------------------------- | ---- | ---- | ---------------------------------- | | type | [SwiperDynamicSyncSceneType](#swiperdynamicsyncscenetype12) | 是 | 否 | Swiper的动态帧率场景。 | ## SwiperDynamicSyncSceneType12+ 枚举值，表示动态帧率场景的类型。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 值 | 说明 | | -------- | ---- | ---------------------- | | GESTURE | 0 | 手势操作场景 | | ANIMATION | 1 | 动画过度场景 | ## MarqueeDynamicSyncScene14+ MarqueeDynamicSyncScene继承自[DynamicSyncScene](#dynamicsyncscene12)，对应[Marquee](arkui-ts/ts-basic-components-marquee.md)的动态帧率场景。 **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 只读 | 可选 | 说明 | | --------- | --------------------------------------------------------- | ---- | ---- | ---------------------------------- | | type | [MarqueeDynamicSyncSceneType](#marqueedynamicsyncscenetype14) | 是 | 否 | Marquee的动态帧率场景。 | ## MarqueeDynamicSyncSceneType14+ 枚举值，表示Marquee的动态帧率场景的类型。 **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 值 | 说明 | | -------- | ---- | ---------------------- | | ANIMATION | 1 | 动画过度场景 | **示例：** ```ts import { MarqueeDynamicSyncSceneType, MarqueeDynamicSyncScene } from '@kit.ArkUI'; @Entry @Component struct MarqueeExample { @State start: boolean = false @State src: string = '' @State marqueeText: string = 'Running Marquee' private fromStart: boolean = true private step: number = 10 private loop: number = Number.POSITIVE_INFINITY controller: TextClockController = new TextClockController() convert2time(value: number): string{ let date = new Date(Number(value+'000')); let hours = date.getHours().toString().padStart(2, '0'); let minutes = date.getMinutes().toString().padStart(2, '0'); let seconds = date.getSeconds().toString().padStart(2, '0'); return hours+ ":" + minutes + ":" + seconds; } @State ANIMATION: ExpectedFrameRateRange = {min:0, max:120, expected:30} private scenes: MarqueeDynamicSyncScene[] = [] build() { Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { Marquee({ start: this.start, step: this.step, loop: this.loop, fromStart: this.fromStart, src: this.marqueeText + this.src }) .marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION) .width(300) .height(80) .fontColor('#FFFFFF') .fontSize(48) .fontWeight(700) .backgroundColor('#182431') .margin({ bottom: 40 }) .id('dynamicMarquee') .onAppear(()=>{ this.scenes = this.getUIContext().requireDynamicSyncScene('dynamicMarquee') as MarqueeDynamicSyncScene[] }) Button('Start') .onClick(() => { this.start = true this.controller.start() this.scenes.forEach((scenes: MarqueeDynamicSyncScene) => { if (scenes.type == MarqueeDynamicSyncSceneType.ANIMATION) { scenes.setFrameRateRange(this.ANIMATION) } }); }) .width(120) .height(40) .fontSize(16) .fontWeight(500) .backgroundColor('#007DFF') TextClock({ timeZoneOffset: -8, controller: this.controller }) .format('hms') .onDateChange((value: number) => { this.src = this.convert2time(value); }) .margin(20) .fontSize(30) } .width('100%') .height('100%') } } ``` ## TextMenuController16+ 以下API需先使用UIContext中的[getTextMenuController()](js-apis-arkui-UIContext.md#gettextmenucontroller16)方法获取TextMenuController实例，再通过此实例调用对应方法。 ### setMenuOptions16+ setMenuOptions(options: TextMenuOptions): void 设置菜单选项。 **原子化服务API：** 从API version 16开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------- | ---- | ---- | | options | [TextMenuOptions](../apis-arkui/arkui-ts/ts-text-common.md#textmenuoptions16对象说明)| 是 | 设置菜单选项。
默认值:{showMode: TextMenuShowMode.DEFAULT} | **示例：** ```ts // xxx.ets @Entry @Component struct Index { aboutToAppear(): void { // 设置在对应的UIContext下优先使用独立窗口显示文本选择菜单 this.getUIContext() .getTextMenuController() .setMenuOptions( { showMode: TextMenuShowMode.PREFER_WINDOW } ) } build() { Row() { Column() { TextInput({ text: "这是一个TextInput，长按弹出文本选择菜单" }) .height(60) .fontStyle(FontStyle.Italic) .fontWeight(FontWeight.Bold) .textAlign(TextAlign.Center) .caretStyle({ width: '4vp' }) Text("这是一个Text，长按弹出文本选择菜单") .height(60) .copyOption(CopyOptions.InApp) .fontStyle(FontStyle.Italic) .fontWeight(FontWeight.Bold) .textAlign(TextAlign.Center) }.width('100%') } .height('100%') } } ``` ## setPixelRoundMode18+ setPixelRoundMode(mode: PixelRoundMode): void 配置当前页面的像素取整模式。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------- | ---- | ---- | | mode | [PixelRoundMode](./arkui-ts/ts-appendix-enums.md#pixelroundmode18)| 是 | 像素取整模式。
默认值：PixelRoundMode.PIXEL_ROUND_ON_LAYOUT_FINISH | **示例：** ```ts // EntryAbility.ets import { UIContext } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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.setPixelRoundMode(PixelRoundMode.PIXEL_ROUND_ON_LAYOUT_FINISH); 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) ?? ''); }); } ``` ## getPixelRoundMode18+ getPixelRoundMode(): PixelRoundMode 获取当前页面的像素取整模式。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 | 说明 | | ---------- | ---- | | [PixelRoundMode](./arkui-ts/ts-appendix-enums.md#pixelroundmode18)| 当前页面的像素取整模式。| **示例：** ```ts // EntryAbility.ets import { UIContext } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; 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(); console.info("pixelRoundMode : " + uiContext.getPixelRoundMode().valueOf()); 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) ?? ''); }); }