1# 辅助功能 2 3>  **说明：** 4> 本模块首批接口从 API version 7 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5 6## 导入模块 7 8```typescript 9import accessibility from '@ohos.accessibility'; 10``` 11 12## AbilityState 13 14辅助应用状态类型。 15 16**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 17 18| 名称 | 描述 | 19| -------- | -------- | 20| enable | 辅助应用已启用。 | 21| disable | 辅助应用已禁用。 | 22| install | 辅助应用已安装。 | 23 24## AbilityType 25 26无障碍辅助应用类型。 27 28**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 29 30| 名称 | 描述 | 31| -------- | -------- | 32| audible | 表示具有听觉反馈。 | 33| generic | 表示具有通用反馈。 | 34| haptic | 表示具有触觉反馈。 | 35| spoken | 表示具有语音反馈。 | 36| visual | 表示具有视觉反馈。 | 37 38## AccessibilityAbilityInfo 39 40辅助应用信息。 41 42**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 43 44### 属性 45 46| 名称 | 参数类型 | 可读 | 可写 | 说明 | 47| -------- | -------- | -------- | -------- | -------- | 48| id | number | 是 | 否 | ability id。 | 49| name | string | 是 | 否 | ability 名。 | 50| bundleName | string | 是 | 否 | 包名。 | 51| abilityTypes | Array<[AbilityType](#abilitytype)> | 是 | 否 | 辅助应用类型。 | 52| capabilities | Array<[Capability](#capability)> | 是 | 否 | 辅助应用能力列表。 | 53| description | string | 是 | 否 | 辅助应用描述。 | 54| eventTypes | Array<[EventType](#eventtype)> | 是 | 否 | 辅助应用关注的无障碍事件列表。 | 55 56## Action 57 58应用所支持的目标动作。 59 60**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 61 62| 名称 | 描述 | 63| -------- | -------- | 64| click | 表示点击操作。 | 65| longClick | 表示长按操作。 | 66| scrollForward | 表示向前滚动操作。 | 67| scrollBackward | 表示向后滚动操作。 | 68| focus | 表示获得焦点操作。 | 69| clearFocus | 表示清除焦点操作。 | 70| clearSelection | 表示清除选择操作。 | 71| accessibilityFocus | 表示获得无障碍焦点操作。 | 72| clearAccessibilityFocus | 表示清除无障碍焦点操作。 | 73| cut | 表示剪切操作。 | 74| copy | 表示复制操作。 | 75| paste | 表示粘贴操作。 | 76| select | 表示选择操作。 | 77| setText | 表示设置文本操作。 | 78| delete | 表示删除操作。 | 79| setSelection | 表示选择操作。 | 80 81## Capability 82 83辅助应用能力类型。 84 85**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 86 87| 名称 | 描述 | 88| -------- | -------- | 89| retrieve | 具有检索窗口内容的能力。 | 90| touchGuide | 具有触摸探索模式的能力。 | 91| keyEventObserver | 具有过滤按键事件的能力。 | 92| zoom | 具有控制显示放大的能力。 | 93| gesture | 具有执行手势动作的能力。 | 94 95## CaptionsFontEdgeType<sup>8+</sup> 96 97字幕字体边缘类型。 98 99**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Hearing 100 101| 名称 | 描述 | 102| -------- | -------- | 103| none | 无效果。 | 104| raised | 凸起效果。 | 105| depressed | 凹陷效果。 | 106| uniform | 轮廓效果。 | 107| dropShadow | 阴影效果。 | 108 109## CaptionsFontFamily<sup>8+</sup> 110 111字幕字体。 112 113**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Hearing 114 115| 名称 | 描述 | 116| -------- | -------- | 117| default | 默认字体。 | 118| monospacedSerif | 等宽 Serif 字体。 | 119| serif | Serif 字体。 | 120| monospacedSansSerif | 等宽 Sans Serif 字体。 | 121| sansSerif | Sans Serif 字体。 | 122| casual | 非正式字体。 | 123| cursive | 手写字体。 | 124| smallCapitals | 小型大写字母字体。 | 125 126## CaptionsStyle<sup>8+</sup> 127 128字幕风格。 129 130**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Hearing 131 132| 名称 | 参数类型 | 可读 | 可写 | 说明 | 133| -------- | -------- | -------- | -------- | -------- | 134| fontFamily | [CaptionsFontFamily](#captionsfontfamily8) | 是 | 否 | 描述字幕字体。 | 135| fontScale | number | 是 | 否 | 描述字幕字体缩放系数。 | 136| fontColor | number \| string | 是 | 否 | 描述字幕字体颜色。 | 137| fontEdgeType | [CaptionsFontEdgeType](#captionsfontedgetype8) | 是 | 否 | 描述字幕字体边缘。 | 138| backgroundColor | number \| string | 是 | 否 | 描述字幕背景颜色。 | 139| windowColor | number \| string | 是 | 否 | 描述字幕窗口颜色。 | 140 141## CaptionsManager<sup>8+</sup> 142 143字幕配置。 144 145### 属性 146 147| 名称 | 参数类型 | 可读 | 可写 | 说明 | 148| -------- | -------- | -------- | -------- | -------- | 149| enabled | boolean | 是 | 否 | 表示是否启用字幕配置。 | 150| style | [CaptionsStyle](#captionsstyle8) | 是 | 否 | 表示字幕风格。 | 151 152### 方法 153 154下列 API 示例中都需要使用 [accessibility.getCaptionsManager()](#accessibilitygetcaptionsmanager8) 获取 captionsManager 实例，再通过此实例调用对应的方法。 155 156#### on('enableChange') 157 158on(type: 'enableChange', callback: Callback<boolean>): void; 159 160注册字幕配置启用的监听函数。 161 162**系统能力**：SystemCapability.BarrierFree.Accessibility.Hearing 163 164- 参数： 165 166 | 参数名 | 参数类型 | 必填 | 说明 | 167 | -------- | -------- | -------- | -------- | 168 | type | string | 是 | 监听字幕配置启用状态。 | 169 | callback | Callback<boolean> | 是 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 | 170 171- 示例 172 173 ```typescript 174 captionsManager.on('enableChange',(data) => { 175 console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) 176 }) 177 ``` 178 179#### on('styleChange') 180 181on(type: 'styleChange', callback: Callback<CaptionsStyle>): void; 182 183注册字幕风格变化的监听函数。 184 185**系统能力**：SystemCapability.BarrierFree.Accessibility.Hearing 186 187- 参数： 188 189 | 参数名 | 参数类型 | 必填 | 说明 | 190 | -------- | -------- | -------- | -------- | 191 | type | string | 是 | 监听字幕风格变化。 | 192 | callback | Callback<[CaptionsStyle](#captionsstyle8)> | 是 | 回调函数，在字幕风格变化时通过此函数进行通知。 | 193 194- 示例 195 196 ```typescript 197 captionsManager.on('styleChange',(data) => { 198 console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) 199 }) 200 ``` 201 202#### off('enableChange') 203 204off(type: 'enableChange', callback?: Callback<boolean>): void; 205 206移除字幕配置启用的监听函数。 207 208**系统能力**：SystemCapability.BarrierFree.Accessibility.Hearing 209 210- 参数： 211 212 | 参数名 | 参数类型 | 必填 | 说明 | 213 | -------- | -------- | -------- | -------- | 214 | type | string | 是 | 监听字幕配置启用状态。 | 215 | callback | Callback<boolean> | 否 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 | 216 217- 示例 218 219 ```typescript 220 captionsManager.off('enableChange') 221 ``` 222 223#### off('styleChange') 224 225off(type: 'styleChange', callback?: Callback<CaptionsStyle>): void; 226 227移除字幕风格变化的监听函数。 228 229**系统能力**：SystemCapability.BarrierFree.Accessibility.Hearing 230 231- 参数： 232 233 | 参数名 | 参数类型 | 必填 | 说明 | 234 | -------- | -------- | -------- | -------- | 235 | type | string | 是 | 字幕风格变化。 | 236 | callback | Callback<[CaptionsStyle](#captionsstyle8)> | 否 | 回调函数，在字幕风格变化时通过此函数进行通知。 | 237 238- 示例 239 240 ```typescript 241 captionsManager.off('styleChange') 242 ``` 243 244## EventInfo 245 246界面变更事件。 247 248**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 249 250### 属性 251 252| 名称 | 参数类型 | 可读 | 可写 | 说明 | 253| -------- | -------- | -------- | -------- | -------- | 254| type | [EventType](#eventtype) | 是 | 是 | 无障碍事件类型。 | 255| windowUpdateType | [WindowUpdateType](#windowupdatetype) | 是 | 是 | 窗口变化类型。 | 256| bundleName | string | 是 | 是 | 目标应用名。 | 257| componentType | string | 是 | 是 | 事件源组件类型，如按钮、图表。 | 258| pageId | number | 是 | 是 | 事件源的页面 ID。 | 259| description | string | 是 | 是 | 事件描述。 | 260| triggerAction | [Action](#action) | 是 | 是 | 触发事件的 Action。 | 261| textMoveUnit | [TextMoveUnit](#textmoveunit) | 是 | 是 | 文本移动粒度。 | 262| contents | Array<string> | 是 | 是 | 内容列表。 | 263| lastContent | string | 是 | 是 | 最新内容。 | 264| beginIndex | number | 是 | 是 | 画面显示条目的开始序号。 | 265| currentIndex | number | 是 | 是 | 当前条目序号。 | 266| endIndex | number | 是 | 是 | 画面显示条目的结束序号。 | 267| itemCount | number | 是 | 是 | 条目总数。 | 268 269## EventType 270 271无障碍事件类型。 272 273**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 274 275| 名称 | 描述 | 276| -------- | -------- | 277| click | 描述点击组件的事件。 | 278| longClick | 描述长按组件的事件。 | 279| select | 描述选择组件的事件。 | 280| focus | 描述组件获得焦点的事件。 | 281| textUpdate | 描述组件文本已更改的事件。 | 282| hoverEnter | 描述悬停进入组件的事件。 | 283| hoverExit | 描述悬停离开组件的事件。 | 284| scroll | 描述滚动视图的事件。 | 285| textSelectionUpdate | 描述选定文本已更改的事件。 | 286| accessibilityFocus | 描述获得无障碍焦点的事件。 | 287| accessibilityFocusClear | 描述清除无障碍焦点的事件。 | 288 289## TextMoveUnit 290 291文本无障碍导航移动粒度。 292 293**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 294 295| 名称 | 描述 | 296| -------- | -------- | 297| char | 以字符为移动粒度遍历节点文本。 | 298| word | 以词为移动粒度遍历节点文本。 | 299| line | 以行为移动粒度遍历节点文本。 | 300| page | 以页为移动粒度遍历节点文本。 | 301| paragraph | 以段落为移动粒度遍历节点文本。 | 302 303## WindowUpdateType 304 305窗口变化类型。 306 307**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 308 309| 名称 | 描述 | 310| -------- | -------- | 311| add | 添加窗口的窗口变化事件。 | 312| remove | 一个窗口被删除的窗口变化事件。 | 313| title | 窗口标题已更改的窗口变化事件。 | 314| bounds | 窗口边界已更改的窗口变化事件。 | 315| layer | 窗口层级发生变化的窗口变化事件。 | 316| active | 窗口变为活动或不活动的窗口变化事件。 | 317| focus | 窗口焦点发生变化的窗口变化事件。 | 318| accessibilityFocus | 窗口无障碍焦点发生变化的窗口更改事件。 | 319| parent | 父窗口已更改的窗口变化事件。 | 320| children | 子窗口已更改的窗口变化事件。 | 321| pip | 窗口进入或退出画中画（PIP）模式的窗口变化事件。 | 322 323## accessibility.getAbilityLists 324 325getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>> 326 327查询辅助应用列表。 328 329**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 330 331- 参数： 332 333 | 参数名 | 参数类型 | 必填 | 说明 | 334 | -------- | -------- | -------- | -------- | 335 | abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 | 336 | stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 | 337 338- 返回值： 339 340 | 类型 | 说明 | 341 | -------- | -------- | 342 | Promise<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | 返回辅助应用信息列表。 | 343 344- 示例 345 346 ```typescript 347 accessibility.getAbilityLists("spoken", "enable") 348 .then((data) => { 349 console.info('success data:getAbilityList1 : ' + JSON.stringify(data)); 350 for (let item of data) { 351 console.info(item.id); 352 console.info(item.name); 353 console.info(item.description); 354 console.info(item.abilityTypes); 355 console.info(item.eventTypes); 356 console.info(item.capabilities); 357 console.info(item.packageName); 358 console.info(item.filterBundleNames); 359 console.info(item.bundleName); 360 } 361 }).catch((error) => { 362 console.error('failed to getAbilityList1 because ' + JSON.stringify(error)); 363 }) 364 ``` 365 366## accessibility.getAbilityLists 367 368getAbilityLists(abilityType: AbilityType, stateType: AbilityState,callback: AsyncCallback<Array<AccessibilityAbilityInfo>>): void 369 370查询辅助应用列表。 371 372**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 373 374- 参数： 375 376 | 参数名 | 参数类型 | 必填 | 说明 | 377 | -------- | -------- | -------- | -------- | 378 | abilityType | [AbilityType](#abilitytype) | 是 | 辅助应用的类型。 | 379 | stateType | [AbilityState](#abilitystate) | 是 | 辅助应用的状态。 | 380 | callback | AsyncCallback<Array<[AccessibilityAbilityInfo](#accessibilityabilityinfo)>> | 是 | 回调函数，返回辅助应用信息列表。 | 381 382- 示例 383 384 ```typescript 385 accessibility.getAbilityLists("visual", "enable", (err, data) => { 386 if (err) { 387 console.error('failed to getAbilityList2 because ' + JSON.stringify(err)); 388 return; 389 } 390 console.info('success data:getAbilityList2 : ' + JSON.stringify(data)); 391 for (let item of data) { 392 console.info(item.id); 393 console.info(item.name); 394 console.info(item.description); 395 console.info(item.abilityTypes); 396 console.info(item.eventTypes); 397 console.info(item.capabilities); 398 console.info(item.packageName); 399 console.info(item.filterBundleNames); 400 console.info(item.bundleName); 401 } 402 }) 403 ``` 404 405## accessibility.getCaptionsManager<sup>8+</sup> 406 407getCaptionsManager(): CaptionsManager 408 409获取无障碍字幕配置。 410 411**系统能力**：SystemCapability.BarrierFree.Accessibility.Hearing 412 413- 返回值： 414 415 | 类型 | 说明 | 416 | -------- | -------- | 417 | [CaptionsManager](#captionsmanager8) | 无障碍字幕配置管理。 | 418 419- 示例 420 421 ```typescript 422 captionsManager = accessibility.getCaptionsManager() 423 ``` 424 425## accessibility.on('accessibilityStateChange' | 'touchGuideStateChange') 426 427on(type: 'accessibilityStateChange' | 'touchGuideStateChange', callback: Callback<boolean>): void 428 429启用辅助应用和触摸浏览功能的状态变化监听。 430 431**系统能力**：以下各项对应的系统能力有所不同，详见下表。 432 433- 参数： 434 435 | 参数名 | 参数类型 | 必填 | 说明 | 436 | -------- | -------- | -------- | -------- | 437 | type | string | 是 | 监听的事件类型。<br/>- type 为'accessibilityStateChange'时表示监听类型为辅助功能启用状态变化监听；<br/>**系统能力**：SystemCapability.BarrierFree.Accessibility.Core<br/>- type 为'touchGuideStateChange'时表示监听类型为触摸浏览启用状态变化监听。<br/>**系统能力**：SystemCapability.BarrierFree.Accessibility.Vision | 438 | callback | Callback<boolean> | 是 | 回调函数，在启用状态变化时将状态通过此函数进行通知。 | 439 440- 示例 441 442 ```typescript 443 accessibility.on('accessibilityStateChange',(data) => { 444 console.info('success data:subscribeStateObserver : ' + JSON.stringify(data)) 445 }) 446 ``` 447 448## accessibility.off('accessibilityStateChange' | 'touchGuideStateChange') 449 450off(type: ‘accessibilityStateChange ’ | ‘touchGuideStateChange’, callback?: Callback<boolean>): void 451 452关闭辅助应用和触摸浏览功能的状态变化监听。 453 454**系统能力**：以下各项对应的系统能力有所不同，详见下表。 455 456- 参数： 457 458 | 参数名 | 参数类型 | 必填 | 说明 | 459 | -------- | -------- | -------- | -------- | 460 | type | string | 否 | 监听的事件类型。<br/>- type 为'accessibilityStateChange'时表示监听类型为辅助功能启用状态变化监听；<br/>**系统能力**：SystemCapability.BarrierFree.Accessibility.Core<br/>- type 为'touchGuideStateChange'时表示监听类型为触摸浏览启用状态变化监听。<br/>**系统能力**：SystemCapability.BarrierFree.Accessibility.Vision | 461 | callback | Callback<boolean> | 否 | 要取消的监听回调函数。 | 462 463- 示例 464 465 ```typescript 466 accessibility.off('accessibilityStateChange',(data) => { 467 console.info('success data:unSubscribeStateObserver : ' + JSON.stringify(data)) 468 }) 469 ``` 470 471## accessibility.isOpenAccessibility 472 473isOpenAccessibility(): Promise<boolean> 474 475判断是否启用了辅助功能。 476 477**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 478 479- 返回值： 480 481 | 类型 | 说明 | 482 | -------- | -------- | 483 | Promise<boolean> | 如果辅助功能已启用，则返回 true；否则返回 false。 | 484 485- 示例 486 487 ```typescript 488 accessibility.isOpenAccessibility() 489 .then((data) => { 490 console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) 491 }).catch((error) => { 492 console.error('failed to isOpenAccessibility because ' + JSON.stringify(error)); 493 }) 494 ``` 495 496## accessibility.isOpenAccessibility 497 498isOpenAccessibility(callback: AsyncCallback<boolean>): void 499 500判断是否启用了辅助功能。 501 502**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 503 504- 参数 505 506 | 参数名 | 参数类型 | 必填 | 说明 | 507 | -------- | -------- | -------- | -------- | 508 | callback | AsyncCallback<boolean> | 是 | 回调函数，如果辅助功能已启用，则返回 true；否则返回 false。 | 509 510- 示例 511 512 ```typescript 513 accessibility.isOpenAccessibility((err, data) => { 514 if (err) { 515 console.error('failed to isOpenAccessibility because ' + JSON.stringify(err)); 516 return; 517 } 518 console.info('success data:isOpenAccessibility : ' + JSON.stringify(data)) 519 }) 520 ``` 521 522## accessibility.isOpenTouchGuide 523 524isOpenTouchGuide(): Promise<boolean> 525 526判断触摸浏览模式是否开启。 527 528**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 529 530- 返回值： 531 532 | 类型 | 说明 | 533 | -------- | -------- | 534 | Promise<boolean> | 如果触摸浏览模式已开启，则返回 true；否则返回 false。 | 535 536- 示例 537 538 ```typescript 539 accessibility.isOpenTouchGuide() 540 .then((data) => { 541 console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) 542 }).catch((error) => { 543 console.error('failed to isOpenTouchGuide because ' + JSON.stringify(error)); 544 }) 545 ``` 546 547## accessibility.isOpenTouchGuide 548 549isOpenTouchGuide(callback: AsyncCallback<boolean>): void 550 551判断触摸浏览模式是否开启。 552 553**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 554 555- 参数 556 557 | 参数名 | 参数类型 | 必填 | 说明 | 558 | -------- | -------- | -------- | -------- | 559 | callback | AsyncCallback<boolean> | 是 | 回调函数，如果触摸浏览模式已开启，则返回 true；否则返回 false。 | 560 561- 示例 562 563 ```typescript 564 accessibility.isOpenTouchGuide((err, data) => { 565 if (err) { 566 console.error('failed to isOpenTouchGuide because ' + JSON.stringify(err)); 567 return; 568 } 569 console.info('success data:isOpenTouchGuide : ' + JSON.stringify(data)) 570 }) 571 ``` 572 573## accessibility.sendEvent 574 575sendEvent(event: EventInfo): Promise<void> 576 577发送无障碍事件。 578 579**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 580 581- 参数： 582 583 | 参数名 | 参数类型 | 必填 | 说明 | 584 | -------- | -------- | -------- | -------- | 585 | event | [EventInfo](#eventinfo) | 是 | 无障碍事件对象。 | 586 587- 返回值： 588 589 | 类型 | 说明 | 590 | -------- | -------- | 591 | Promise<void> | 以 Promise 形式返回结果，如果发送无障碍事件成功，则 data 有数据返回；如果发送无障碍事件失败，则 err 有数据返回。 | 592 593- 示例 594 595 ```typescript 596 accessibility.sendEvent(this.eventInfo) 597 .then((data) => { 598 console.info('success data:sendEvent : ' + JSON.stringify(data)) 599 }).catch((error) => { 600 console.error('failed to sendEvent because ' + JSON.stringify(error)); 601 }) 602 ``` 603 604## accessibility.sendEvent 605 606sendEvent(event: EventInfo, callback: AsyncCallback<void>): void 607 608发送无障碍事件。 609 610**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 611 612- 参数： 613 614 | 参数名 | 参数类型 | 必填 | 说明 | 615 | -------- | -------- | -------- | -------- | 616 | event | [EventInfo](#eventinfo) | 是 | 辅助事件对象。 | 617 | callback | AsyncCallback<void> | 是 | 回调函数，如果发送无障碍事件成功，则 AsyncCallback 中 data 有数据返回；如果发送无障碍事件失败，则 AsyncCallback 中 err 有数据返回。 | 618 619- 示例 620 621 ```typescript 622 accessibility.sendEvent(this.eventInfo,(err, data) => { 623 if (err) { 624 console.error('failed to sendEvent because ' + JSON.stringify(err)); 625 return; 626 } 627 console.info('success data:sendEvent : ' + JSON.stringify(data)) 628 }) 629 ``` 630
