1# @ohos.accessibility.config (System Accessibility Configuration) 2 3The **accessibility.config** module provides APIs for configuring system accessibility features, including accessibility extension, high-contrast text, mouse buttons, and captions. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - The APIs provided by this module are system APIs. 9 10## Modules to Import 11 12```ts 13import config from '@ohos.accessibility.config'; 14``` 15 16## Attributes 17 18**System capability**: SystemCapability.BarrierFree.Accessibility.Core 19 20| Name | Type | Readable| Writable| Description | 21|------------------------------------|--------------------------------------------------------------------------------------------| -------- | -------- |-----------------------------------------------------------| 22| highContrastText | [Config](#config)\<boolean> | Yes| Yes| Whether to enable high-contrast text. | 23| invertColor | [Config](#config)\<boolean> | Yes| Yes| Whether to enable color inversion. | 24| daltonizationState<sup>11+</sup> | [Config](#config)\<boolean> | Yes| Yes| Whether to enable daltonization. It must be used with **daltonizationColorFilter**. | 25| daltonizationColorFilter | [Config](#config)<[DaltonizationColorFilter](#daltonizationcolorfilter)> | Yes| Yes| Configuration of the daltonization filter. | 26| contentTimeout | [Config](#config)\<number> | Yes| Yes| Recommended duration for content display. The value ranges from 0 to 5000, in milliseconds. | 27| animationOff | [Config](#config)\<boolean> | Yes| Yes| Whether to disable animation. | 28| brightnessDiscount | [Config](#config)\<number> | Yes| Yes| Brightness discount. The value ranges from 0 to 1.0. | 29| mouseKey | [Config](#config)\<boolean> | Yes| Yes| Whether to enable the mouse button feature. | 30| mouseAutoClick | [Config](#config)\<number> | Yes| Yes| Interval for automatic mouse clicks. The value ranges from 0 to 5000, in milliseconds. | 31| shortkey | [Config](#config)\<boolean> | Yes| Yes| Whether to enable the accessibility extension shortcut key. | 32| shortkeyTarget | [Config](#config)\<string> | Yes| Yes| Target application for the accessibility extension shortcut key. The value format is 'bundleName/abilityName'. | 33| captions | [Config](#config)\<boolean> | Yes| Yes| Whether to enable captions. | 34| captionsStyle | [Config](#config)\<[accessibility.CaptionsStyle](js-apis-accessibility.md#captionsstyle8)> | Yes| Yes| Captions style. | 35| audioMono<sup>10+</sup> | [Config](#config)\<boolean> | Yes| Yes| Whether to enable mono audio. | 36| audioBalance<sup>10+</sup> | [Config](#config)\<number> | Yes| Yes| Audio balance for the left and right audio channels. The value ranges from -1.0 to +1.0. | 37| shortkeyMultiTargets<sup>11+</sup> | [Config](#config)<Array\<string>> | Yes| Yes| List of target applications for the accessibility shortcut keys. The value format is ['bundleName/abilityName'].| 38| clickResponseTime<sup>11+</sup> | [Config](#config)<[ClickResponseTime](#clickresponsetime11)> | Yes| Yes| Length of time required for a click. | 39| ignoreRepeatClick<sup>11+</sup> | [Config](#config)\<boolean> | Yes| Yes| Whether to ignore repeated clicks. This parameter must be used together with **repeatClickInterval**. | 40| repeatClickInterval<sup>11+</sup> | [Config](#config)<[RepeatClickInterval](#repeatclickinterval11)> | Yes| Yes| Interval between repeated clicks. | 41 42For a Boolean return value, **True** means that the feature is enabled, and **False** means the opposite. 43 44## enableAbility 45 46enableAbility(name: string, capability: Array<accessibility.Capability>): Promise<void>; 47 48**Required permissions**: ohos.permission.WRITE_ACCESSIBILITY_CONFIG 49 50Enables an accessibility extension ability. This API uses a promise to return the result. 51 52**System capability**: SystemCapability.BarrierFree.Accessibility.Core 53 54**Parameters** 55 56| Name| Type| Mandatory| Description| 57| -------- | -------- | -------- | -------- | 58| name | string | Yes| Name of the accessibility extension ability. The format is 'bundleName/abilityName'.| 59| capability | Array<[accessibility.Capability](js-apis-accessibility.md#capability)> | Yes| Capability of the accessibility extension ability.| 60 61**Return value** 62 63| Type| Description| 64| -------- | -------- | 65| Promise<void> | Promise that returns no value.| 66 67**Error codes** 68 69For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). 70 71| ID| Error Message| 72| ------- | -------------------------------- | 73| 9300001 | Invalid bundle name or ability name. | 74| 9300002 | Target ability already enabled. | 75 76**Example** 77 78```ts 79import accessibility from '@ohos.accessibility'; 80import config from '@ohos.accessibility.config'; 81import { BusinessError } from '@ohos.base'; 82 83let name: string = 'com.ohos.example/axExtension'; 84let capability: accessibility.Capability[] = ['retrieve']; 85 86config.enableAbility(name, capability).then(() => { 87 console.info(`Succeeded in enable ability, name is ${name}, capability is ${capability}`); 88}).catch((err: BusinessError) => { 89 console.error(`failed to enable ability, Code is ${err.code}, message is ${err.message}`); 90}); 91``` 92 93## enableAbility 94 95enableAbility(name: string, capability: Array<[accessibility.Capability](js-apis-accessibility.md#capability)>, callback: AsyncCallback<void>): void; 96 97**Required permissions**: ohos.permission.WRITE_ACCESSIBILITY_CONFIG 98 99Enables an accessibility extension ability. This API uses an asynchronous callback to return the result. 100 101**System capability**: SystemCapability.BarrierFree.Accessibility.Core 102 103**Parameters** 104 105| Name| Type| Mandatory| Description| 106| -------- | -------- | -------- | -------- | 107| name | string | Yes| Name of the accessibility extension ability. The format is 'bundleName/abilityName'.| 108| capability | Array<[accessibility.Capability](js-apis-accessibility.md#capability)> | Yes| Capability of the accessibility extension ability.| 109| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 110 111**Error codes** 112 113For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). 114 115| ID| Error Message| 116| ------- | -------------------------------- | 117| 9300001 | Invalid bundle name or ability name. | 118| 9300002 | Target ability already enabled. | 119 120**Example** 121 122```ts 123import accessibility from '@ohos.accessibility'; 124import config from '@ohos.accessibility.config'; 125import { BusinessError } from '@ohos.base'; 126 127let name: string = 'com.ohos.example/axExtension'; 128let capability: accessibility.Capability[] = ['retrieve']; 129 130config.enableAbility(name, capability, (err: BusinessError) => { 131 if (err) { 132 console.error(`failed to enable ability, Code is ${err.code}, message is ${err.message}`); 133 return; 134 } 135 console.info(`Succeeded in enable ability, name is ${name}, capability is ${capability}`); 136}); 137``` 138 139## disableAbility 140 141disableAbility(name: string): Promise<void>; 142 143**Required permissions**: ohos.permission.WRITE_ACCESSIBILITY_CONFIG 144 145Disables an accessibility extension ability. This API uses a promise to return the result. 146 147**System capability**: SystemCapability.BarrierFree.Accessibility.Core 148 149**Parameters** 150 151| Name| Type| Mandatory| Description| 152| -------- | -------- | -------- | -------- | 153| name | string | Yes| Name of the accessibility extension ability. The format is 'bundleName/abilityName'.| 154 155**Return value** 156 157| Type| Description| 158| -------- | -------- | 159| Promise<void> | Promise that returns no value.| 160 161**Error codes** 162 163For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). 164 165| ID| Error Message| 166| ------- | -------------------------------- | 167| 9300001 | Invalid bundle name or ability name. | 168 169**Example** 170 171```ts 172import accessibility from '@ohos.accessibility'; 173import config from '@ohos.accessibility.config'; 174import { BusinessError } from '@ohos.base'; 175 176let name: string = 'com.ohos.example/axExtension'; 177 178config.disableAbility(name).then(() => { 179 console.info(`Succeeded in disable ability, name is ${name}`); 180}).catch((err: BusinessError) => { 181 console.error(`failed to disable ability, Code is ${err.code}, message is ${err.message}`); 182}) 183``` 184 185## disableAbility 186 187disableAbility(name: string, callback: AsyncCallback<void>): void; 188 189**Required permissions**: ohos.permission.WRITE_ACCESSIBILITY_CONFIG 190 191Disables an accessibility extension ability. This API uses an asynchronous callback to return the result. 192 193**System capability**: SystemCapability.BarrierFree.Accessibility.Core 194 195**Parameters** 196 197| Name| Type| Mandatory| Description| 198| -------- | -------- | -------- | -------- | 199| name | string | Yes| Name of the accessibility extension ability. The format is 'bundleName/abilityName'.| 200| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 201 202**Error codes** 203 204For details about the error codes, see [Accessibility Error Codes](../errorcodes/errorcode-accessibility.md). 205 206| ID| Error Message| 207| ------- | -------------------------------- | 208| 9300001 | Invalid bundle name or ability name. | 209 210**Example** 211 212```ts 213import accessibility from '@ohos.accessibility'; 214import config from '@ohos.accessibility.config'; 215import { BusinessError } from '@ohos.base'; 216 217let name: string = 'com.ohos.example/axExtension'; 218 219config.disableAbility(name, (err: BusinessError) => { 220 if (err) { 221 console.error(`failed to enable ability, Code is ${err.code}, message is ${err.message}`); 222 return; 223 } 224 console.info(`Succeeded in disable, name is ${name}`); 225}); 226``` 227 228## on('enabledAccessibilityExtensionListChange') 229 230on(type: 'enabledAccessibilityExtensionListChange', callback: Callback<void>): void; 231 232**Required permissions**: ohos.permission.READ_ACCESSIBILITY_CONFIG 233 234Adds a listener for changes in the list of enabled accessibility extension abilities. This API uses an asynchronous callback to return the result. 235 236**System capability**: SystemCapability.BarrierFree.Accessibility.Core 237 238**Parameters** 239 240| Name| Type| Mandatory| Description| 241| -------- | -------- | -------- | -------- | 242| type | string | Yes| Listening type. The value is fixed at **'enabledAccessibilityExtensionListChange'**, indicating listening for changes in the list of enabled accessibility extension abilities.| 243| callback | Callback<void> | Yes| Callback invoked when the list of enabled accessibility extension abilities changes.| 244 245**Example** 246 247```ts 248import config from '@ohos.accessibility.config'; 249 250config.on('enabledAccessibilityExtensionListChange', () => { 251 console.info('subscribe enabled accessibility extension list change state success'); 252}); 253``` 254 255## off('enabledAccessibilityExtensionListChange') 256 257off(type: 'enabledAccessibilityExtensionListChange', callback?: Callback<void>): void; 258 259**Required permissions**: ohos.permission.READ_ACCESSIBILITY_CONFIG 260 261Cancels the listener for changes in the list of enabled accessibility extension abilities. This API uses an asynchronous callback to return the result. 262 263**System capability**: SystemCapability.BarrierFree.Accessibility.Core 264 265**Parameters** 266 267| Name| Type| Mandatory| Description| 268| -------- | -------- | -------- | -------- | 269| type | string | Yes| Listening type. The value is fixed at **'enabledAccessibilityExtensionListChange'**, indicating listening for changes in the list of enabled accessibility extension abilities.| 270| callback | Callback<void> | No| Callback for the event. The value must be the same as the value of **callback** in **on('enabledAccessibilityExtensionListChange')**. If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.| 271 272**Example** 273 274```ts 275import config from '@ohos.accessibility.config'; 276 277config.off('enabledAccessibilityExtensionListChange', () => { 278 console.info('Unsubscribe enabled accessibility extension list change state success'); 279}); 280``` 281 282## Config 283 284Implements configuration, acquisition, and listening for attributes. 285 286### set 287 288set(value: T): Promise<void>; 289 290**Required permissions**: ohos.permission.WRITE_ACCESSIBILITY_CONFIG 291 292Sets the attribute value. This API uses a promise to return the result. 293 294**System capability**: SystemCapability.BarrierFree.Accessibility.Core 295 296**Parameters** 297 298| Name| Type| Mandatory| Description| 299| -------- | -------- | -------- | -------- | 300| value | T | Yes| Attribute value to set.| 301 302**Return value** 303 304| Type| Description| 305| -------- | -------- | 306| Promise<void> | Promise that returns no value.| 307 308**Example** 309 310```ts 311import config from '@ohos.accessibility.config'; 312import { BusinessError } from '@ohos.base'; 313 314let value: boolean = true; 315 316config.highContrastText.set(value).then(() => { 317 console.info(`Succeeded in set highContrastText value is ${value}`); 318}).catch((err: BusinessError) => { 319 console.error(`failed to set highContrastText, Code is ${err.code}, message is ${err.message}`); 320}); 321``` 322 323### set 324 325set(value: T, callback: AsyncCallback<void>): void; 326 327**Required permissions**: ohos.permission.WRITE_ACCESSIBILITY_CONFIG 328 329Sets the attribute value. This API uses an asynchronous callback to return the result. 330 331**System capability**: SystemCapability.BarrierFree.Accessibility.Core 332 333**Parameters** 334 335| Name| Type| Mandatory| Description| 336| -------- | -------- | -------- | -------- | 337| value | T | Yes| Attribute value to set.| 338| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 339 340**Example** 341 342```ts 343import config from '@ohos.accessibility.config'; 344import { BusinessError } from '@ohos.base'; 345 346let value: boolean = true; 347 348config.highContrastText.set(value, (err: BusinessError) => { 349 if (err) { 350 console.error(`Failed to set highContrastText. Code: ${err.code}, message: ${err.message}`); 351 return; 352 } 353 console.info(`Succeeded in setting highContrastText. Value: ${value}`); 354}); 355``` 356 357### get 358 359get(): Promise<T>; 360 361Obtains the attribute value. This API uses a promise to return the result. 362 363**System capability**: SystemCapability.BarrierFree.Accessibility.Core 364 365**Return value** 366 367| Type| Description| 368| -------- | -------- | 369| Promise<T> | Promise used to return the value obtained.| 370 371**Example** 372 373```ts 374import config from '@ohos.accessibility.config'; 375import { BusinessError } from '@ohos.base'; 376 377config.highContrastText.get().then((data: boolean) => { 378 console.info(`Succeeded in getting highContrastText. Data: ${data}`); 379}).catch((err: BusinessError) => { 380 console.error(`Failed to get highContrastText. Code: ${err.code}, message: ${err.message}`); 381}); 382``` 383 384### get 385 386get(callback: AsyncCallback<T>): void; 387 388Obtains the attribute value. This API uses an asynchronous callback to return the result. 389 390**System capability**: SystemCapability.BarrierFree.Accessibility.Core 391 392**Parameters** 393 394| Name| Type| Mandatory| Description| 395| -------- | -------- | -------- | -------- | 396| callback | AsyncCallback<T> | Yes| Callback used to return the attribute value.| 397 398**Example** 399 400```ts 401import config from '@ohos.accessibility.config'; 402import { BusinessError } from '@ohos.base'; 403 404config.highContrastText.get((err: BusinessError, data: boolean) => { 405 if (err) { 406 console.error(`Failed to get highContrastText. Code: ${err.code}, message: ${err.message}`); 407 return; 408 } 409 console.info(`Succeeded in getting highContrastText. Data: ${data}`); 410}); 411``` 412 413### on 414 415on(callback: Callback<T>): void; 416 417**Required permissions**: ohos.permission.READ_ACCESSIBILITY_CONFIG 418 419Adds a listener for attribute changes. This API uses an asynchronous callback to return the result. 420 421**System capability**: SystemCapability.BarrierFree.Accessibility.Core 422 423**Parameters** 424 425| Name| Type| Mandatory| Description| 426| -------- | -------- | -------- | -------- | 427| callback | Callback<T> | Yes| Callback invoked when the attribute changes.| 428 429**Example** 430 431```ts 432import config from '@ohos.accessibility.config'; 433 434config.highContrastText.on((data: boolean) => { 435 console.info(`Succeeded in subscribing to highContrastText. Result: ${JSON.stringify(data)}`); 436}); 437``` 438 439### off 440 441off(callback?: Callback<T>): void; 442 443**Required permissions**: ohos.permission.READ_ACCESSIBILITY_CONFIG 444 445Cancels the listener for attribute changes. This API uses an asynchronous callback to return the result. 446 447**System capability**: SystemCapability.BarrierFree.Accessibility.Core 448 449**Parameters** 450 451| Name| Type| Mandatory| Description| 452| -------- | -------- | -------- | -------- | 453| callback | Callback<T> | No| Callback for the event. The value must be the same as the value of **callback** in **on()**. If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.| 454 455**Example** 456 457```ts 458import config from '@ohos.accessibility.config'; 459 460config.highContrastText.off((data: boolean) => { 461 console.info(`Succeeded in unsubscribing from highContrastText. Result: ${JSON.stringify(data)}`); 462}); 463``` 464 465## DaltonizationColorFilter 466 467Enumerates the daltonization filters. 468When daltonization is enabled (with [daltonizationState](#attributes) set to **true**), the filter set for users with disabilities is used; otherwise, the filter for normal uses is used.<sup>11+</sup> 469 470**System capability**: SystemCapability.BarrierFree.Accessibility.Core 471 472| Name| Description| 473| -------- | -------- | 474| Normal | Filter for normal users.| 475| Protanomaly | Filter for protanomaly.| 476| Deuteranomaly | Filter for deuteranomaly.| 477| Tritanomaly | Filter for tritanomaly.| 478 479## ClickResponseTime<sup>11+</sup> 480 481Defines the length of time for a click. 482 483**System capability**: SystemCapability.BarrierFree.Accessibility.Core 484 485| Name | Description | 486|-------------|------------| 487| Short | Short (default). | 488| Medium | Medium. | 489| Long | Long. | 490 491## RepeatClickInterval<sup>11+</sup> 492 493Defines the interval between repeated clicks. 494**RepeatClickInterval** takes effect only when repeated clicks are ignored ([ignoreRepeatClick](#attributes) set to **true**). 495 496**System capability**: SystemCapability.BarrierFree.Accessibility.Core 497 498| Name | Description | 499|----------|-------| 500| Shortest | Shortest.| 501| Short | Short. | 502| Medium | Medium. | 503| Long | Long. | 504| Longest | Longest.| 505