From ec14b1c87e3bc8920248f4a3f7c31e836113ed04 Mon Sep 17 00:00:00 2001 From: laiguizhong Date: Tue, 5 Jul 2022 14:35:44 +0800 Subject: [PATCH] add accessibility extension api doc Signed-off-by: laiguizhong Change-Id: I9d2a96b956f90d76556ac25b2693b91311dfe474 --- ...js-apis-accessibility-extension-context.md | 238 ++++++++++++++++++ .../reference/apis/js-apis-accessibility.md | 4 + ...plication-AccessibilityExtensionAbility.md | 235 +++++++++++++++++ 3 files changed, 477 insertions(+) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md diff --git a/zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md b/zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md new file mode 100644 index 0000000000..a9c61d030a --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-accessibility-extension-context.md @@ -0,0 +1,238 @@ +# AccessibilityExtensionContext + +AccessibilityExtensionContext是AccessibilityExtensionAbility上下文环境，继承自ExtensionContext。 + +AccessibilityExtensionContext模块提供扩展的上下文的能力，包括允许配置辅助应用关注信息类型、查询节点信息、手势注入等。 + +> **说明：** +> +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> 本模块接口仅可在Stage模型下使用。 + +## 导入模块 + +```js +import AccessibilityExtensionAbility from './@ohos.application.AccessibilityExtensionAbility' +``` + +## FocusDirection + +表示查询下一焦点元素的方向。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +| 名称 | 描述 | +| -------- | -------- | +| up | 表示向上查询。 | +| down | 表示向上查询。 | +| left | 表示向左查询。 | +| right | 表示向右查询。 | +| forward | 表示向前查询。 | +| backward | 表示向后查询。 | + +## FocusType + +表示查询焦点元素的类型。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +| 名称 | 描述 | +| -------- | -------- | +| accessibility | 表示无障碍的焦点类型。 | +| normal | 表示普通的焦点类型。 | + +## Rect + +表示矩形区域。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +### 参数 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ------ | -------- | ---- | ---- | ------------------ | +| left | number | 是 | 否 | 矩形区域的左边界。 | +| top | number | 是 | 否 | 矩形区域的上边界。 | +| width | number | 是 | 否 | 矩形区域的宽度。 | +| height | number | 是 | 否 | 矩形区域的高度。 | + +## WindowType + +表示窗口的类型。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +| 名称 | 描述 | +| -------- | -------- | +| application | 表示应用窗口类型。 | +| system | 表示系统窗口类型。 | + +## AccessibilityExtensionContext.setEventTypeFilter + +setEventTypeFilter(type: Array): Promise\; + +设置关注的事件类型。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ------ | ------ | +| type | Array<[EventType](js-apis-accessibility.md#EventType)> | 是 | 关注的事件类型。 | + +**返回值：** + +| 类型 | 说明 | +| -------------------------------- | --------------------------------------- | +| Promise<boolean> | Promise对象。返回当前设置是否成功。 | + +**示例：** + +```ts +this.context.setEventTypeFilter(['click', 'longClick']); +``` + +## AccessibilityExtensionContext.setTargetBundleName + +setTargetBundleName(targetNames: Array\): Promise\; + +设置关注的事件类型。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ------ | ------ | +| targetNames | Array<string> | 是 | 关注的目标包名。 | + +**返回值：** + +| 类型 | 说明 | +| -------------------------------- | --------------------------------------- | +| Promise<boolean> | Promise对象。返回当前设置是否成功。 | + +**示例：** + +```ts +this.context.setTargetBundleName(['com.ohos.mms']); +``` + +## AccessibilityExtensionContext.getFocusElement + +getFocusElement(isAccessibilityFocus?: boolean): Promise\; + +获取焦点元素。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ------ | ------ | +| isAccessibilityFocus | boolean | 否 | 获取的是否是无障碍焦点元素，默认为否。 | + +**返回值：** + +| 类型 | 说明 | +| -------------------------------- | --------------------------------------- | +| Promise<AccessibilityElement> | Promise对象。返回当前对应的焦点元素。 | + +**示例：** + +```ts +this.context.getFocusElement().then(focusElement => { + console.log("AxExtensionAbility getFocusElement success"); +}) +``` + +## AccessibilityExtensionContext.getWindowRootElement + +getWindowRootElement(windowId?: number): Promise\; + +获取窗口的根节点元素。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ------ | ------ | +| windowId | number | 否 | 指定获取根节点元素的窗口，未指定则从当前活跃窗口获取。 | + +**返回值：** + +| 类型 | 说明 | +| -------------------------------- | --------------------------------------- | +| Promise<AccessibilityElement> | Promise对象。返回当前对应的根节点元素。 | + +**示例：** + +```ts +this.context.getWindowRootElement().then(rootElement => { + console.log("AxExtensionAbility getWindowRootElement success"); +}) +``` + +## AccessibilityExtensionContext.getWindows + +getWindows(displayId?: number): Promise>; + +获取用户可见的窗口列表。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ------ | ------ | +| displayId | number | 否 | 指定获取窗口信息的屏幕，未指定则从默认主屏幕获取。 | + +**返回值：** + +| 类型 | 说明 | +| -------------------------------- | --------------------------------------- | +| Promise<Array<AccessibilityElement>> | Promise对象。返回当前对应的窗口列表信息。 | + +**示例：** + +```ts +this.context.getWindows().then(windows => { + console.log("AxExtensionAbility getWindows success"); +}) +``` + +## AccessibilityExtensionContext.gestureInject + +gestureInject(gesturePath: GesturePath, listener: Callback\): Promise\ { + console.info('gestureInject result: ' + result); +}) +``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-accessibility.md b/zh-cn/application-dev/reference/apis/js-apis-accessibility.md index b10175b813..401e5ac410 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-accessibility.md +++ b/zh-cn/application-dev/reference/apis/js-apis-accessibility.md @@ -1,5 +1,7 @@ # 辅助功能 +本模块提供辅助功能查询能力，包括获取辅助应用列表、辅助应用启用状态、无障碍字幕配置等。 + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从 API version 7 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -34,6 +36,7 @@ import accessibility from '@ohos.accessibility'; | haptic | 表示具有触觉反馈。 | | spoken | 表示具有语音反馈。 | | visual | 表示具有视觉反馈。 | +| all9+ | 表示以上所有类别。 | ## AccessibilityAbilityInfo @@ -48,6 +51,7 @@ import accessibility from '@ohos.accessibility'; | id | number | 是 | 否 | ability id。 | | name | string | 是 | 否 | ability 名。 | | bundleName | string | 是 | 否 | 包名。 | +| targetBundleNames9+ | Array<string> | 是 | 否 | 关注的目标包名。 | | abilityTypes | Array<[AbilityType](#abilitytype)> | 是 | 否 | 辅助应用类型。 | | capabilities | Array<[Capability](#capability)> | 是 | 否 | 辅助应用能力列表。 | | description | string | 是 | 否 | 辅助应用描述。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md b/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md new file mode 100644 index 0000000000..586b0c7e0b --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md @@ -0,0 +1,235 @@ +# 辅助功能扩展能力 + +**AccessibilityExtensionAbility**基于ExtensionAbility框架，提供辅助功能业务的能力。 + +>**说明：** +> +>本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> +>本模块接口仅可在Stage模型下使用。 + +## 导入模块 + +```ts +import AccessibilityExtensionAbility from './@ohos.application.AccessibilityExtensionAbility' +``` + +## AccessibilityEvent + +辅助事件信息。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +### 属性 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| eventType | [EventType](js-apis-accessibility.md#EventType) \| [WindowUpdateType](js-apis-accessibility.md#WindowUpdateType) \| [TouchGuideType](touchguidetype) \| [GestureType](gesturetype) \| [PageUpdateType](pageupdatetype) | 是 | 否 | 具体事件类型。 | +| target | AccessibilityElement | 是 | 否 | 发生事件的目标组件。 | +| timeStamp | number | 是 | 否 | 事件时间戳。 | + +## GesturePath + +表示手势路径信息。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +### 属性 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| points | Array<[GesturePoint](gesturepoint)> | 是 | 是 | 手势。 | +| durationTime | number | 是 | 是 | 手势总耗时。 | + +### 方法 + +#### constructor + +constructor(durationTime: number) + +构造函数。 + +- 参数： + + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | durationTime | number | 是 | 手势总耗时。 | + +- 示例 + + ```typescript + let gesturePath = new GesturePath(100); + ``` + +## GesturePoint + +表示手势触摸点。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +### 属性 + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| positionX | number | 是 | 是 | 触摸点X坐标。 | +| positionY | number | 是 | 是 | 触摸点Y坐标。 | + +### 方法 + +#### constructor + +constructor(positionX: number, positionY: number) + +构造函数。 + +- 参数： + + | 参数名 | 参数类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | positionX | number | 是 | 触摸点X坐标。 | + | positionY | number | 是 | 触摸点Y坐标。 | + +- 示例 + + ```typescript + let gesturePoint = new GesturePoint(100, 200); + ``` + +## GestureType + +手势事件类型。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +| 名称 | 描述 | +| -------- | -------- | +| left | 表示向左的手势。 | +| leftThenRight | 表示先向左再向右的手势。 | +| leftThenUp | 表示先向左再向上的手势。 | +| leftThenDown | 表示先向左再向下的手势。 | +| right | 表示向右的手势。 | +| rightThenLeft | 表示先向右再向左的手势。 | +| rightThenUp | 表示先向右再向上的手势。 | +| rightThenDown | 表示先向右再向下的手势。 | +| up | 表示向上的手势。 | +| upThenLeft | 表示先向上再向左的手势。 | +| upThenRight | 表示先向上再向右的手势。 | +| upThenDown | 表示先向上再向下的手势。 | +| down | 表示向下的手势。 | +| downThenLeft | 表示先向下再向左的手势。 | +| downThenRight | 表示先向下再向右的手势。 | +| downThenUp | 表示先向下再向上的手势。 | + +## PageUpdateType + +页面刷新类型。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +| 名称 | 描述 | +| -------- | -------- | +| pageContentUpdate | 表示页面内容刷新。 | +| pageStateUpdate | 表示页面状态刷新。 | + +## TouchGuideType + +触摸浏览事件类型。 + +**系统能力**：以下各项对应的系统能力均为 SystemCapability.Barrierfree.Accessibility.Core + +| 名称 | 描述 | +| -------- | -------- | +| touchBegin | 表示触摸浏览时开始触摸。 | +| touchEnd | 表示触摸浏览时结束触摸。 | + +## AccessibilityExtensionAbility.onConnect + +onConnect(): void; + +用户启用AccessibilityExtensionAbility时，系统服务完成连接后，回调此接口，可以该方法中执行初始化业务逻辑操作。该方法可以选择性重写。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +无 + +**示例：** + +```ts +onConnect(): void { + console.log("AxExtensionAbility onConnect"); +} +``` + +## AccessibilityExtensionAbility.onDisconnect + +onDisconnect(): void; + +用户停用AccessibilityExtensionAbility时，系统服务完成断开连接后，回调此接口，可以该方法中执行资源回收退出业务逻辑操作。该方法可以选择性重写。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +无 + +**示例：** + +```ts +onDisconnect(): void { + console.log("AxExtensionAbility onDisconnect"); +} +``` + +## AccessibilityExtensionAbility.onAccessibilityEvent + +onAccessibilityEvent(event: AccessibilityEvent): void; + +在关注的应用及事件类型对应的事件发生时回调此接口，可以在该方法中根据事件信息进行业务逻辑处理。一般情况下需要重写该方法完成业务。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ------ | ------ | +| event | [AccessibilityEvent](accessibilityevent) | 是 | 无障碍事件回调函数。无返回值。 | + +**示例：** + +```ts +onAccessibilityEvent(event: AccessibilityEvent): void { + console.log("AxExtensionAbility onAccessibilityEvent"); + if (event.eventType == 'click') { + console.log("AxExtensionAbility onAccessibilityEvent: click"); + } +} +``` + +## AccessibilityExtensionAbility.onKeyEvent + +onKeyEvent(keyEvent: inputEventClient.KeyEvent): boolean; + +在物理按键按下时回调此方法，可以在该方法中根据业务判断是否对事件进行拦截。 + +**系统能力：** SystemCapability.BarrierFree.Accessibility.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ------ | ------ | +| keyEvent | [KeyEvent](js-apis-inputeventclient.md#KeyEvent) | 是 | 按键事件回调函数。返回true表示拦截此按键。 | + +**示例：** + +```ts +onKeyEvent(keyEvent: inputEventClient.KeyEvent): boolean { + console.log("AxExtensionAbility onKeyEvent"); + if (keyEvent.keyCode == 22) { + console.log("AxExtensionAbility onKeyEvent: intercept 22"); + return true; + } + return false; +} +``` -- GitLab