1/* 2 * Copyright (C) 2021-2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit AccessibilityKit 19 */ 20 21import type { AsyncCallback } from './@ohos.base'; 22import type { Callback } from './@ohos.base'; 23 24/** 25 * Accessibility 26 * 27 * @namespace accessibility 28 * @syscap SystemCapability.BarrierFree.Accessibility.Core 29 * @since 7 30 */ 31/** 32 * Accessibility 33 * 34 * @namespace accessibility 35 * @syscap SystemCapability.BarrierFree.Accessibility.Core 36 * @atomicservice 37 * @since 11 38 */ 39declare namespace accessibility { 40 /** 41 * The type of the Ability app. 42 * 43 *{ 'audible' | 'generic' | 'haptic' | 'spoken' | 'visual' } 44 * @syscap SystemCapability.BarrierFree.Accessibility.Core 45 * @since 7 46 */ 47 /** 48 * The type of the Ability app. 49 * 50 * { 'audible' | 'generic' | 'haptic' | 'spoken' | 'visual' | 'all' } 51 * @syscap SystemCapability.BarrierFree.Accessibility.Core 52 * @since 9 53 */ 54 type AbilityType = 'audible' | 'generic' | 'haptic' | 'spoken' | 'visual' | 'all'; 55 56 /** 57 * The action that the ability can execute. 58 * 59 * @syscap SystemCapability.BarrierFree.Accessibility.Core 60 * @since 7 61 */ 62 type Action = 'accessibilityFocus' | 'clearAccessibilityFocus' | 'focus' | 'clearFocus' | 'clearSelection' | 63 'click' | 'longClick' | 'cut' | 'copy' | 'paste' | 'select' | 'setText' | 'delete' | 64 'scrollForward' | 'scrollBackward' | 'setSelection'; 65 66 /** 67 * The type of the accessibility event. 68 * windowsChange/windowContentChange/windowStateChange/announcement/notificationChange/textTraversedAtMove 69 * 70 * @syscap SystemCapability.BarrierFree.Accessibility.Core 71 * @since 7 72 */ 73 type EventType = 'accessibilityFocus' | 'accessibilityFocusClear' | 74 'click' | 'longClick' | 'focus' | 'select' | 'hoverEnter' | 'hoverExit' | 75 'textUpdate' | 'textSelectionUpdate' | 'scroll'; 76 77 /** 78 * The change type of the windowsChange event. 79 * It's used when received the {@code windowsChange} event. 80 * 81 * @syscap SystemCapability.BarrierFree.Accessibility.Core 82 * @since 7 83 */ 84 type WindowUpdateType = 'add' | 'remove' | 'bounds' | 'active' | 'focus'; 85 86 /** 87 * The type of the ability state. 88 * 89 * @syscap SystemCapability.BarrierFree.Accessibility.Core 90 * @since 7 91 */ 92 type AbilityState = 'enable' | 'disable' | 'install'; 93 94 /** 95 * The ability that accessibility subsystem support. 96 * touchExplorer: Describes the capability to talkback. 97 * magnification: Describes the capability to request to control the display magnification. 98 * gesturesSimulation: Describes the capability to request to simulate the gesture. 99 * windowContent: Describes the capability to search for the content of the active window. 100 * filterKeyEvents: Describes the capability to request to filter key events. 101 * fingerprintGesture: Describes the capability to request to fingerprint gesture. 102 * 103 * @syscap SystemCapability.BarrierFree.Accessibility.Core 104 * @since 7 105 */ 106 type Capability = 'retrieve' | 'touchGuide' | 'keyEventObserver' | 'zoom' | 'gesture'; 107 108 /** 109 * The granularity of text move. 110 * 111 * @syscap SystemCapability.BarrierFree.Accessibility.Core 112 * @since 7 113 */ 114 type TextMoveUnit = 'char' | 'word' | 'line' | 'page' | 'paragraph'; 115 116 /** 117 * Checks whether accessibility ability is enabled. 118 * 119 * @param { AsyncCallback<boolean> } callback Asynchronous callback interface. 120 * @syscap SystemCapability.BarrierFree.Accessibility.Core 121 * @since 7 122 * @deprecated since 10 123 * @useinstead ohos.accessibility#isOpenAccessibilitySync 124 */ 125 function isOpenAccessibility(callback: AsyncCallback<boolean>): void; 126 127 /** 128 * Checks whether accessibility ability is enabled. 129 * 130 * @returns { Promise<boolean> } Returns {@code true} if the accessibility is enabled; returns {@code false} otherwise. 131 * @syscap SystemCapability.BarrierFree.Accessibility.Core 132 * @since 7 133 * @deprecated since 10 134 * @useinstead ohos.accessibility#isOpenAccessibilitySync 135 */ 136 function isOpenAccessibility(): Promise<boolean>; 137 138 /** 139 * Checks whether accessibility ability is enabled. 140 * 141 * @returns { boolean } Returns true if the accessibility is enabled; returns false otherwise. 142 * @syscap SystemCapability.BarrierFree.Accessibility.Core 143 * @since 10 144 */ 145 /** 146 * Checks whether accessibility ability is enabled. 147 * 148 * @returns { boolean } Returns true if the accessibility is enabled; returns false otherwise. 149 * @syscap SystemCapability.BarrierFree.Accessibility.Core 150 * @atomicservice 151 * @since 11 152 */ 153 function isOpenAccessibilitySync(): boolean; 154 155 /** 156 * Checks touch browser ability (which is used by talkback) is enabled. 157 * 158 * @param { AsyncCallback<boolean> } callback Asynchronous callback interface. 159 * @syscap SystemCapability.BarrierFree.Accessibility.Vision 160 * @since 7 161 * @deprecated since 10 162 * @useinstead ohos.accessibility#isOpenTouchGuideSync 163 */ 164 function isOpenTouchGuide(callback: AsyncCallback<boolean>): void; 165 166 /** 167 * Checks touch browser ability (which is used by talkback) is enabled. 168 * 169 * @returns { Promise<boolean> } Returns {@code true} if the touch browser is enabled; returns {@code false} otherwise. 170 * @syscap SystemCapability.BarrierFree.Accessibility.Vision 171 * @since 7 172 * @deprecated since 10 173 * @useinstead ohos.accessibility#isOpenTouchGuideSync 174 */ 175 function isOpenTouchGuide(): Promise<boolean>; 176 177 /** 178 * Checks touch browser ability (which is used by talkback) is enabled. 179 * 180 * @returns { boolean } Returns true if the touch browser is enabled; returns false otherwise. 181 * @syscap SystemCapability.BarrierFree.Accessibility.Vision 182 * @since 10 183 */ 184 /** 185 * Checks touch browser ability (which is used by talkback) is enabled. 186 * 187 * @returns { boolean } Returns true if the touch browser is enabled; returns false otherwise. 188 * @syscap SystemCapability.BarrierFree.Accessibility.Vision 189 * @atomicservice 190 * @since 11 191 */ 192 function isOpenTouchGuideSync(): boolean; 193 194 /** 195 * Queries the list of accessibility abilities. 196 * 197 * @param { AbilityType } abilityType The type of the accessibility ability. {@code AbilityType} eg.spoken 198 * @param { AbilityState } stateType The state of the accessibility ability. {@code AbilityState} eg.installed 199 * @param { AsyncCallback<Array<AccessibilityAbilityInfo>> } callback 200 * @syscap SystemCapability.BarrierFree.Accessibility.Core 201 * @since 7 202 * @deprecated since 9 203 * @useinstead ohos.accessibility#getAccessibilityExtensionList 204 */ 205 function getAbilityLists( 206 abilityType: AbilityType, 207 stateType: AbilityState, 208 callback: AsyncCallback<Array<AccessibilityAbilityInfo>> 209 ): void; 210 211 /** 212 * Queries the list of accessibility abilities. 213 * 214 * @param { AbilityType } abilityType The type of the accessibility ability. {@code AbilityType} eg.spoken 215 * @param { AbilityState } stateType The state of the accessibility ability. {@code AbilityState} eg.installed 216 * @returns { Promise<Array<AccessibilityAbilityInfo>> } Returns the list of abilityInfos. 217 * @syscap SystemCapability.BarrierFree.Accessibility.Core 218 * @since 7 219 * @deprecated since 9 220 * @useinstead ohos.accessibility#getAccessibilityExtensionList 221 */ 222 function getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>>; 223 224 /** 225 * Queries the list of accessibility abilities. 226 * 227 * @param { AbilityType } abilityType The type of the accessibility ability. {@code AbilityType} eg.spoken 228 * @param { AbilityState } stateType The state of the accessibility ability. {@code AbilityState} eg.installed 229 * @returns { Promise<Array<AccessibilityAbilityInfo>> } Returns the list of abilityInfos. 230 * @throws { BusinessError } 401 - Input parameter error. 231 * @syscap SystemCapability.BarrierFree.Accessibility.Core 232 * @since 9 233 */ 234 function getAccessibilityExtensionList( 235 abilityType: AbilityType, 236 stateType: AbilityState 237 ): Promise<Array<AccessibilityAbilityInfo>>; 238 239 /** 240 * Queries the list of accessibility abilities. 241 * 242 * @param { AbilityType } abilityType The type of the accessibility ability. {@code AbilityType} eg.spoken 243 * @param { AbilityState } stateType The state of the accessibility ability. {@code AbilityState} eg.installed 244 * @param { AsyncCallback<Array<AccessibilityAbilityInfo>> } callback 245 * @throws { BusinessError } 401 - Input parameter error. 246 * @syscap SystemCapability.BarrierFree.Accessibility.Core 247 * @since 9 248 */ 249 function getAccessibilityExtensionList( 250 abilityType: AbilityType, 251 stateType: AbilityState, 252 callback: AsyncCallback<Array<AccessibilityAbilityInfo>> 253 ): void; 254 255 /** 256 * Send accessibility Event. 257 * 258 * @param { EventInfo } event The object of the accessibility {@code EventInfo} . 259 * @param { AsyncCallback<void> } callback Asynchronous callback interface. 260 * @syscap SystemCapability.BarrierFree.Accessibility.Core 261 * @since 7 262 * @deprecated since 9 263 * @useinstead ohos.accessibility#sendAccessibilityEvent 264 */ 265 function sendEvent(event: EventInfo, callback: AsyncCallback<void>): void; 266 267 /** 268 * Send accessibility Event. 269 * 270 * @param { EventInfo } event The object of the accessibility {@code EventInfo} . 271 * @returns { Promise<void> } Returns {@code true} if success ; returns {@code false} otherwise. 272 * @syscap SystemCapability.BarrierFree.Accessibility.Core 273 * @since 7 274 * @deprecated since 9 275 * @useinstead ohos.accessibility#sendAccessibilityEvent 276 */ 277 function sendEvent(event: EventInfo): Promise<void>; 278 279 /** 280 * Send accessibility event. 281 * 282 * @param { EventInfo } event The object of the accessibility {@code EventInfo} . 283 * @param { AsyncCallback<void> } callback Asynchronous callback interface. 284 * @throws { BusinessError } 401 - Input parameter error. 285 * @syscap SystemCapability.BarrierFree.Accessibility.Core 286 * @since 9 287 */ 288 function sendAccessibilityEvent(event: EventInfo, callback: AsyncCallback<void>): void; 289 290 /** 291 * Send accessibility event. 292 * 293 * @param { EventInfo } event The object of the accessibility {@code EventInfo} . 294 * @returns { Promise<void> } Returns {@code true} if success ; returns {@code false} otherwise. 295 * @throws { BusinessError } 401 - Input parameter error. 296 * @syscap SystemCapability.BarrierFree.Accessibility.Core 297 * @since 9 298 */ 299 function sendAccessibilityEvent(event: EventInfo): Promise<void>; 300 301 /** 302 * Register the observe of the accessibility state changed. 303 * 304 * @param { 'accessibilityStateChange' } type state event type. 305 * @param { Callback<boolean> } callback Asynchronous callback interface. 306 * @throws { BusinessError } 401 - Input parameter error. 307 * @syscap SystemCapability.BarrierFree.Accessibility.Core 308 * @since 7 309 */ 310 function on(type: 'accessibilityStateChange', callback: Callback<boolean>): void; 311 312 /** 313 * Register the observe of the touchGuide state changed. 314 * 315 * @param { 'touchGuideStateChange' } type state event type. 316 * @param { Callback<boolean> } callback Asynchronous callback interface. 317 * @throws { BusinessError } 401 - Input parameter error. 318 * @syscap SystemCapability.BarrierFree.Accessibility.Vision 319 * @since 7 320 */ 321 function on(type: 'touchGuideStateChange', callback: Callback<boolean>): void; 322 323 /** 324 * Unregister the observe of the accessibility state changed. 325 * 326 * @param { 'accessibilityStateChange' } type state event type 327 * @param { Callback<boolean> } callback Asynchronous callback interface. 328 * @throws { BusinessError } 401 - Input parameter error. 329 * @syscap SystemCapability.BarrierFree.Accessibility.Core 330 * @since 7 331 */ 332 function off(type: 'accessibilityStateChange', callback?: Callback<boolean>): void; 333 334 /** 335 * Unregister the observe of the touchGuide state changed. 336 * 337 * @param { 'touchGuideStateChange' } type state event type 338 * @param { Callback<boolean> } callback Asynchronous callback interface. 339 * @throws { BusinessError } 401 - Input parameter error. 340 * @syscap SystemCapability.BarrierFree.Accessibility.Core 341 * @since 7 342 */ 343 function off(type: 'touchGuideStateChange', callback?: Callback<boolean>): void; 344 345 /** 346 * Get the captions manager. 347 * 348 * @returns { CaptionsManager } Returns the captions manager. 349 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 350 * @since 8 351 */ 352 function getCaptionsManager(): CaptionsManager; 353 354 /** 355 * Indicates the captions manager. 356 * 357 * @typedef CaptionsManager 358 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 359 * @since 8 360 */ 361 interface CaptionsManager { 362 /** 363 * Indicates whether captions are enabled. 364 * 365 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 366 * @since 8 367 */ 368 enabled: boolean; 369 /** 370 * Indicates the style of captions. 371 * 372 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 373 * @since 8 374 */ 375 style: CaptionsStyle; 376 377 /** 378 * Register the observe of the enable state. 379 * 380 * @param { 'enableChange' } type 381 * @param { Callback<boolean> } callback 382 * @throws { BusinessError } 401 - Input parameter error. 383 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 384 * @since 8 385 */ 386 on(type: 'enableChange', callback: Callback<boolean>): void; 387 388 /** 389 * Register the observer of the style. 390 * 391 * @param { 'styleChange' } type 392 * @param { Callback<CaptionsStyle> } callback 393 * @throws { BusinessError } 401 - Input parameter error. 394 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 395 * @since 8 396 */ 397 on(type: 'styleChange', callback: Callback<CaptionsStyle>): void; 398 399 /** 400 * Unregister the observe of the enable state. 401 * 402 * @param { 'enableChange' } type 403 * @param { Callback<boolean> } callback 404 * @throws { BusinessError } 401 - Input parameter error. 405 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 406 * @since 8 407 */ 408 off(type: 'enableChange', callback?: Callback<boolean>): void; 409 410 /** 411 * Unregister the observer of the style. 412 * 413 * @param { 'styleChange' } type 414 * @param { Callback<CaptionsStyle> } callback 415 * @throws { BusinessError } 401 - Input parameter error. 416 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 417 * @since 8 418 */ 419 off(type: 'styleChange', callback?: Callback<CaptionsStyle>): void; 420 } 421 422 /** 423 * Indicates the edge type of the captions font. 424 * 425 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 426 * @since 8 427 */ 428 type CaptionsFontEdgeType = 'none' | 'raised' | 'depressed' | 'uniform' | 'dropShadow'; 429 /** 430 * Indicates the font family of captions. 431 * 432 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 433 * @since 8 434 */ 435 type CaptionsFontFamily = 'default' | 'monospacedSerif' | 'serif' | 436 'monospacedSansSerif' | 'sansSerif' | 'casual' | 'cursive' | 'smallCapitals'; 437 /** 438 * Indicates the style of captions. 439 * 440 * @typedef CaptionsStyle 441 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 442 * @since 8 443 */ 444 interface CaptionsStyle { 445 /** 446 * Indicates the font family of captions. 447 * 448 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 449 * @since 8 450 */ 451 fontFamily: CaptionsFontFamily; 452 /** 453 * Indicates the font scaling of captions. 454 * 455 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 456 * @since 8 457 */ 458 fontScale: number; 459 /** 460 * Indicates the font color of captions. 461 * 462 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 463 * @since 8 464 */ 465 fontColor: number | string; 466 /** 467 * Indicates the edge type of the captions font. 468 * 469 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 470 * @since 8 471 */ 472 fontEdgeType: CaptionsFontEdgeType; 473 /** 474 * Indicates the background color of captions. 475 * 476 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 477 * @since 8 478 */ 479 backgroundColor: number | string; 480 /** 481 * Indicates the window color of captions. 482 * 483 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 484 * @since 8 485 */ 486 windowColor: number | string; 487 } 488 489 /** 490 * Indicates the info of accessibility. 491 * 492 * @typedef AccessibilityAbilityInfo 493 * @syscap SystemCapability.BarrierFree.Accessibility.Core 494 * @since 7 495 */ 496 interface AccessibilityAbilityInfo { 497 /** 498 * The ability id. 499 * 500 * @syscap SystemCapability.BarrierFree.Accessibility.Core 501 * @since 7 502 */ 503 readonly id: string; 504 505 /** 506 * The ability name. 507 * 508 * @syscap SystemCapability.BarrierFree.Accessibility.Core 509 * @since 7 510 */ 511 readonly name: string; 512 513 /** 514 * The bundle name of the ability. 515 * 516 * @syscap SystemCapability.BarrierFree.Accessibility.Core 517 * @since 7 518 */ 519 readonly bundleName: string; 520 /** 521 * The target bundle name for the observation. 522 * 523 * @syscap SystemCapability.BarrierFree.Accessibility.Core 524 * @since 9 525 */ 526 readonly targetBundleNames: Array<string>; 527 528 /** 529 * The type of the ability. 530 * 531 * @syscap SystemCapability.BarrierFree.Accessibility.Core 532 * @since 7 533 */ 534 readonly abilityTypes: Array<AbilityType>; 535 536 /** 537 * The capabilities of the ability. 538 * 539 * @syscap SystemCapability.BarrierFree.Accessibility.Core 540 * @since 7 541 */ 542 readonly capabilities: Array<Capability>; 543 544 /** 545 * The description of the ability. 546 * 547 * @syscap SystemCapability.BarrierFree.Accessibility.Core 548 * @since 7 549 */ 550 readonly description: string; 551 552 /** 553 * The events which the accessibility ability wants to observe. 554 * 555 * @syscap SystemCapability.BarrierFree.Accessibility.Core 556 * @since 7 557 */ 558 readonly eventTypes: Array<EventType>; 559 } 560 561 /** 562 * Indicates the info of events. 563 * 564 * @syscap SystemCapability.BarrierFree.Accessibility.Core 565 * @since 7 566 */ 567 class EventInfo { 568 /** 569 * A constructor used to create a EventInfo object. 570 * 571 * @param jsonObject - Character string in JSON format required for creating an object. 572 * @syscap SystemCapability.BarrierFree.Accessibility.Core 573 * @since 7 574 */ 575 constructor(jsonObject); 576 /** 577 * A constructor used to create a EventInfo object. 578 * 579 * @param { EventType } type - The type of the accessibility event. 580 * @param { string } bundleName - The name of the bundle. 581 * @param { Action } triggerAction - The action that the ability can execute. 582 * @syscap SystemCapability.BarrierFree.Accessibility.Core 583 * @since 11 584 */ 585 constructor(type: EventType, bundleName: string, triggerAction: Action); 586 /** 587 * The type of an accessibility event. 588 * 589 * @syscap SystemCapability.BarrierFree.Accessibility.Core 590 * @since 7 591 */ 592 type: EventType; 593 594 /** 595 * The type of the window change event. 596 * 597 * @syscap SystemCapability.BarrierFree.Accessibility.Core 598 * @since 7 599 */ 600 windowUpdateType?: WindowUpdateType; 601 602 /** 603 * The bundle name of the target application. 604 * 605 * @syscap SystemCapability.BarrierFree.Accessibility.Core 606 * @since 7 607 */ 608 bundleName: string; 609 610 /** 611 * The type of the event source component,such as button, chart. 612 * 613 * @syscap SystemCapability.BarrierFree.Accessibility.Core 614 * @since 7 615 */ 616 componentType?: string; 617 618 /** 619 * The page id of the event source. 620 * 621 * @syscap SystemCapability.BarrierFree.Accessibility.Core 622 * @since 7 623 */ 624 pageId?: number; 625 626 /** 627 * The accessibility event description. 628 * 629 * @syscap SystemCapability.BarrierFree.Accessibility.Core 630 * @since 7 631 */ 632 description?: string; 633 634 /** 635 * The action that triggers the accessibility event, for example, clicking or focusing a view. 636 * 637 * @syscap SystemCapability.BarrierFree.Accessibility.Core 638 * @since 7 639 */ 640 triggerAction: Action; 641 642 /** 643 * The movement step used for reading texts. 644 * 645 * @syscap SystemCapability.BarrierFree.Accessibility.Core 646 * @since 7 647 */ 648 textMoveUnit?: TextMoveUnit; 649 650 /** 651 * The content list. 652 * 653 * @syscap SystemCapability.BarrierFree.Accessibility.Core 654 * @since 7 655 */ 656 contents?: Array<string>; 657 658 /** 659 * The content changed before. 660 * 661 * @syscap SystemCapability.BarrierFree.Accessibility.Core 662 * @since 7 663 */ 664 lastContent?: string; 665 666 /** 667 * The start index of listed items on the screen. 668 * 669 * @syscap SystemCapability.BarrierFree.Accessibility.Core 670 * @since 7 671 */ 672 beginIndex?: number; 673 674 /** 675 * The index of the current item on the screen. 676 * 677 * @syscap SystemCapability.BarrierFree.Accessibility.Core 678 * @since 7 679 */ 680 currentIndex?: number; 681 682 /** 683 * The end index of listed items on the screen. 684 * 685 * @syscap SystemCapability.BarrierFree.Accessibility.Core 686 * @since 7 687 */ 688 endIndex?: number; 689 690 /** 691 * The total of the items, talkback used it when scroll. 692 * 693 * @syscap SystemCapability.BarrierFree.Accessibility.Core 694 * @since 7 695 */ 696 itemCount?: number; 697 } 698} 699export default accessibility; 700