!6329 增加无障碍Extension接口指导文档

Merge pull request !6329 from Mupceet/master

!6329 增加无障碍Extension接口指导文档
Merge pull request !6329 from Mupceet/master
18fdccaa · openharmony_ci · Gitee · de8dd534 · ec14b1c8 · 18fdccaa
3 changed file
--- 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
+# 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<accessibility.EventType>): Promise\<boolean>;
+
+设置关注的事件类型。
+
+**系统能力：**  SystemCapability.BarrierFree.Accessibility.Core
+
+**参数：**
+
+| 参数名 | 参数类型 | 必填 | 说明 |
+| ----- | ------ | ------ | ------ |
+| type | Array&lt;[EventType](js-apis-accessibility.md#EventType)&gt; | 是 | 关注的事件类型。 |
+
+**返回值：**
+
+| 类型                             | 说明                                    |
+| -------------------------------- | --------------------------------------- |
+| Promise&lt;boolean&gt; | Promise对象。返回当前设置是否成功。 |
+
+**示例：**
+
+```ts
+this.context.setEventTypeFilter(['click', 'longClick']);
+```
+
+## AccessibilityExtensionContext.setTargetBundleName
+
+setTargetBundleName(targetNames: Array\<string>): Promise\<boolean>;
+
+设置关注的事件类型。
+
+**系统能力：**  SystemCapability.BarrierFree.Accessibility.Core
+
+**参数：**
+
+| 参数名 | 参数类型 | 必填 | 说明 |
+| ----- | ------ | ------ | ------ |
+| targetNames | Array&lt;string&gt; | 是 | 关注的目标包名。 |
+
+**返回值：**
+
+| 类型                             | 说明                                    |
+| -------------------------------- | --------------------------------------- |
+| Promise&lt;boolean&gt; | Promise对象。返回当前设置是否成功。 |
+
+**示例：**
+
+```ts
+this.context.setTargetBundleName(['com.ohos.mms']);
+```
+
+## AccessibilityExtensionContext.getFocusElement
+
+getFocusElement(isAccessibilityFocus?: boolean): Promise\<AccessibilityElement>;
+
+获取焦点元素。
+
+**系统能力：**  SystemCapability.BarrierFree.Accessibility.Core
+
+**参数：**
+
+| 参数名 | 参数类型 | 必填 | 说明 |
+| ----- | ------ | ------ | ------ |
+| isAccessibilityFocus | boolean | 否 | 获取的是否是无障碍焦点元素，默认为否。 |
+
+**返回值：**
+
+| 类型                             | 说明                                    |
+| -------------------------------- | --------------------------------------- |
+| Promise&lt;AccessibilityElement&gt; | Promise对象。返回当前对应的焦点元素。 |
+
+**示例：**
+
+```ts
+this.context.getFocusElement().then(focusElement => {
+    console.log("AxExtensionAbility getFocusElement success");
+})
+```
+
+## AccessibilityExtensionContext.getWindowRootElement
+
+getWindowRootElement(windowId?: number): Promise\<AccessibilityElement>;
+
+获取窗口的根节点元素。
+
+**系统能力：**  SystemCapability.BarrierFree.Accessibility.Core
+
+**参数：**
+
+| 参数名 | 参数类型 | 必填 | 说明 |
+| ----- | ------ | ------ | ------ |
+| windowId | number | 否 | 指定获取根节点元素的窗口，未指定则从当前活跃窗口获取。 |
+
+**返回值：**
+
+| 类型                             | 说明                                    |
+| -------------------------------- | --------------------------------------- |
+| Promise&lt;AccessibilityElement&gt; | Promise对象。返回当前对应的根节点元素。 |
+
+**示例：**
+
+```ts
+this.context.getWindowRootElement().then(rootElement => {
+    console.log("AxExtensionAbility getWindowRootElement success");
+})
+```
+
+## AccessibilityExtensionContext.getWindows
+
+getWindows(displayId?: number): Promise<Array\<AccessibilityElement>>;
+
+获取用户可见的窗口列表。
+
+**系统能力：**  SystemCapability.BarrierFree.Accessibility.Core
+
+**参数：**
+
+| 参数名 | 参数类型 | 必填 | 说明 |
+| ----- | ------ | ------ | ------ |
+| displayId | number | 否 | 指定获取窗口信息的屏幕，未指定则从默认主屏幕获取。 |
+
+**返回值：**
+
+| 类型                             | 说明                                    |
+| -------------------------------- | --------------------------------------- |
+| Promise&lt;Array&lt;AccessibilityElement&gt;&gt; | Promise对象。返回当前对应的窗口列表信息。 |
+
+**示例：**
+
+```ts
+this.context.getWindows().then(windows => {
+    console.log("AxExtensionAbility getWindows success");
+})
+```
+
+## AccessibilityExtensionContext.gestureInject
+
+gestureInject(gesturePath: GesturePath, listener: Callback\<boolean>): Promise\<boolean
+
+注入手势。
+
+**系统能力：**  SystemCapability.BarrierFree.Accessibility.Core
+
+**参数：**
+
+| 参数名 | 参数类型 | 必填 | 说明 |
+| ----- | ------ | ------ | ------ |
+| gesturePath | [GesturePath](js-apis-application-AccessibilityExtensionAbility.md#GesturePath) | 是 | 表示手势的路径信息。 |
+| listener | Callback&lt;boolean&gt; | 是 | 表示注入手势执行结果的回调。 |
+
+**返回值：**
+
+| 类型                             | 说明                                    |
+| -------------------------------- | --------------------------------------- |
+| Promise&lt;boolean&gt; | Promise对象。返回注入手势的调用结果。 |
+
+**示例：**
+
+```ts
+let gesturePath = new GesturePath(100);
+for (let i = 0; i < 10; i++) {
+    let gesturePoint = new GesturePosition(100, i * 200);
+    gesturePath.positions.push(gesturePoint);
+}
+this.context.gestureInject(gesturePath, (result) => {
+    console.info('gestureInject result: ' + result);
+})
+```
--- a/zh-cn/application-dev/reference/apis/js-apis-accessibility.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-accessibility.md
 # 辅助功能

+本模块提供辅助功能查询能力，包括获取辅助应用列表、辅助应用启用状态、无障碍字幕配置等。
+
 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
 > 本模块首批接口从 API version 7 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

@@ -34,6 +36,7 @@ import accessibility from '@ohos.accessibility';
 | haptic | 表示具有触觉反馈。 |
 | spoken  | 表示具有语音反馈。 |
 | visual | 表示具有视觉反馈。 |
+| all<sup>9+</sup> | 表示以上所有类别。 |

 ## AccessibilityAbilityInfo

@@ -48,6 +51,7 @@ import accessibility from '@ohos.accessibility';
 | id | number | 是 | 否 | ability&nbsp;id。 |
 | name | string | 是 | 否 | ability 名。 |
 | bundleName | string | 是 | 否 | 包名。 |
+| targetBundleNames<sup>9+</sup> | Array&lt;string&gt; | 是 | 否 | 关注的目标包名。 |
 | abilityTypes | Array&lt;[AbilityType](#abilitytype)&gt; | 是 | 否 | 辅助应用类型。 |
 | capabilities | Array&lt;[Capability](#capability)&gt; | 是 | 否 | 辅助应用能力列表。 |
 | description | string | 是 | 否 | 辅助应用描述。 |

--- a/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-application-AccessibilityExtensionAbility.md
+# 辅助功能扩展能力
+
+**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&lt;[GesturePoint](gesturepoint)&gt; | 是 | 是 | 手势。 |
+| 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;
+}
+```