1# @ohos.accessibility.config (系统辅助功能配置)(系统接口) 2 3本模块提供系统辅助功能的配置，包括辅助扩展的启用与关闭、高对比度文字显示、鼠标键、无障碍字幕配置等。 4 5> **说明：** 6> 7> - 本模块首批接口从 API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口为系统接口。 9 10## 导入模块 11 12```ts 13import config from '@ohos.accessibility.config'; 14``` 15 16## 属性 17 18**系统能力**：以下各项对应的系统能力均为SystemCapability.BarrierFree.Accessibility.Core 19 20| 名称 | 类型 | 可读 | 可写 | 说明 | 21|------------------------------------|--------------------------------------------------------------------------------------------| -------- | -------- |-----------------------------------------------------------| 22| highContrastText | [Config](#config)\<boolean> | 是 | 是 | 表示高对比度文字功能启用状态。 | 23| invertColor | [Config](#config)\<boolean> | 是 | 是 | 表示颜色反转功能启用状态。 | 24| daltonizationState<sup>11+</sup> | [Config](#config)\<boolean> | 是 | 是 | 表示颜色滤镜功能启动状态。配合daltonizationColorFilter使用。 | 25| daltonizationColorFilter | [Config](#config)<[DaltonizationColorFilter](#daltonizationcolorfilter)> | 是 | 是 | 表示颜色滤镜功能配置。 | 26| contentTimeout | [Config](#config)\<number> | 是 | 是 | 表示内容显示建议时长配置。取值 0~5000，单位为毫秒。 | 27| animationOff | [Config](#config)\<boolean> | 是 | 是 | 表示关闭动画功能启用状态。 | 28| brightnessDiscount | [Config](#config)\<number> | 是 | 是 | 表示亮度折扣系统配置。取值 0~1.0。 | 29| mouseKey | [Config](#config)\<boolean> | 是 | 是 | 表示鼠标键功能启用状态。 | 30| mouseAutoClick | [Config](#config)\<number> | 是 | 是 | 表示鼠标自动点击功能启用状态。取值 0~5000，单位为毫秒。 | 31| shortkey | [Config](#config)\<boolean> | 是 | 是 | 表示辅助扩展快捷键功能启用状态。 | 32| shortkeyTarget | [Config](#config)\<string> | 是 | 是 | 表示辅助扩展快捷键的目标配置。取值为辅助应用的名称，格式为：'bundleName/abilityName'。 | 33| captions | [Config](#config)\<boolean> | 是 | 是 | 表示辅助字幕功能启用状态。 | 34| captionsStyle | [Config](#config)\<[accessibility.CaptionsStyle](js-apis-accessibility.md#captionsstyle8)> | 是 | 是 | 表示辅助字幕的配置。 | 35| audioMono<sup>10+</sup> | [Config](#config)\<boolean> | 是 | 是 | 表示音频单声道的配置。 | 36| audioBalance<sup>10+</sup> | [Config](#config)\<number> | 是 | 是 | 表示左右声道音量平衡的配置。取值 -1.0~1.0。 | 37| shortkeyMultiTargets<sup>11+</sup> | [Config](#config)<Array\<string>> | 是 | 是 | 表示辅助扩展快捷键的列表配置。取值为辅助应用的名称，格式为：['bundleName/abilityName']。 | 38| clickResponseTime<sup>11+</sup> | [Config](#config)<[ClickResponseTime](#clickresponsetime11)> | 是 | 是 | 表示点击持续时间功能配置。 | 39| ignoreRepeatClick<sup>11+</sup> | [Config](#config)\<boolean> | 是 | 是 | 表示忽略重复点击功能启用状态。配合repeatClickInterval使用。 | 40| repeatClickInterval<sup>11+</sup> | [Config](#config)<[RepeatClickInterval](#repeatclickinterval11)> | 是 | 是 | 表示忽略重复点击功能配置。 | 41 42boolean返回值的含义：True表示开启，False表示关闭。 43[]() 44## enableAbility 45 46enableAbility(name: string, capability: Array<accessibility.Capability>): Promise<void>; 47 48需要权限：ohos.permission.WRITE_ACCESSIBILITY_CONFIG 49 50启用辅助扩展，使用Promise异步回调。 51 52**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 53 54**参数：** 55 56| 参数名 | 类型 | 必填 | 说明 | 57| -------- |------------------------------------------------------------------------------| -------- | -------- | 58| name | string | 是 | 辅助应用的名称，格式为：'bundleName/abilityName'。 | 59| capability | Array<[accessibility.Capability](js-apis-accessibility.md#capability)> | 是 | 辅助应用的能力属性。 | 60 61**返回值：** 62 63| 类型 | 说明 | 64| -------- | -------- | 65| Promise<void> | 无返回结果的Promise对象。 | 66 67**错误码：** 68 69以下错误码的详细介绍请参见[无障碍子系统错误码](errorcode-accessibility.md)。 70 71| 错误码ID | 错误信息 | 72| ------- | -------------------------------- | 73| 9300001 | Invalid bundle name or ability name. | 74| 9300002 | Target ability already enabled. | 75 76**示例：** 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需要权限：ohos.permission.WRITE_ACCESSIBILITY_CONFIG 98 99启用辅助扩展，使用callback异步回调。 100 101**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| -------- |---------------------------------------------------------------------------------| -------- | -------- | 107| name | string | 是 | 辅助应用的名称，格式为：'bundleName/abilityName'。 | 108| capability | Array<[accessibility.Capability](js-apis-accessibility.md#capability)> | 是 | 辅助应用的能力属性。 | 109| callback | AsyncCallback<void> | 是 | 回调函数。 | 110 111**错误码：** 112 113以下错误码的详细介绍请参见[无障碍子系统错误码](errorcode-accessibility.md)。 114 115| 错误码ID | 错误信息 | 116| ------- | -------------------------------- | 117| 9300001 | Invalid bundle name or ability name. | 118| 9300002 | Target ability already enabled. | 119 120**示例：** 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需要权限：ohos.permission.WRITE_ACCESSIBILITY_CONFIG 144 145关闭辅助扩展，使用Promise异步回调。 146 147**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 148 149**参数：** 150 151| 参数名 | 类型 | 必填 | 说明 | 152| -------- | -------- | -------- | -------- | 153| name | string | 是 | 辅助应用的名称，格式为：'bundleName/abilityName'。 | 154 155**返回值：** 156 157| 类型 | 说明 | 158| -------- | -------- | 159| Promise<void> | 无返回结果的Promise对象。 | 160 161**错误码：** 162 163以下错误码的详细介绍请参见[无障碍子系统错误码](errorcode-accessibility.md)。 164 165| 错误码ID | 错误信息 | 166| ------- | -------------------------------- | 167| 9300001 | Invalid bundle name or ability name. | 168 169**示例：** 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需要权限：ohos.permission.WRITE_ACCESSIBILITY_CONFIG 190 191关闭辅助扩展，使用callback异步回调。 192 193**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 194 195**参数：** 196 197| 参数名 | 类型 | 必填 | 说明 | 198| -------- | -------- | -------- | -------- | 199| name | string | 是 | 辅助应用的名称，格式为：'bundleName/abilityName'。 | 200| callback | AsyncCallback<void> | 是 | 回调函数。 | 201 202**错误码：** 203 204以下错误码的详细介绍请参见[无障碍子系统错误码](errorcode-accessibility.md)。 205 206| 错误码ID | 错误信息 | 207| ------- | -------------------------------- | 208| 9300001 | Invalid bundle name or ability name. | 209 210**示例：** 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需要权限：ohos.permission.READ_ACCESSIBILITY_CONFIG 233 234添加启用的辅助扩展的列表变化监听，使用callback异步回调。 235 236**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| -------- | -------- | -------- | -------- | 242| type | string | 是 | 参数固定为enabledAccessibilityExtensionListChange，监听启用的辅助扩展的列表变化。 | 243| callback | Callback<void> | 是 | 回调函数，在启用的辅助扩展的列表变化时通过此函数进行通知。 | 244 245**示例：** 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需要权限：ohos.permission.READ_ACCESSIBILITY_CONFIG 260 261取消启用的辅助扩展的列表变化监听，使用callback异步回调。 262 263**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 264 265**参数：** 266 267| 参数名 | 类型 | 必填 | 说明 | 268| -------- | -------- | -------- | -------- | 269| type | string | 是 | 参数固定为enabledAccessibilityExtensionListChange，监听启用的辅助扩展的列表变化。 | 270| callback | Callback<void> | 否 | 取消指定callback对象的事件响应。需与on('enabledAccessibilityExtensionListChange')的callback一致。缺省时，表示注销所有已注册事件。 | 271 272**示例：** 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 284用于属性的设置、获取与监听。 285 286### set 287 288set(value: T): Promise<void>; 289 290需要权限：ohos.permission.WRITE_ACCESSIBILITY_CONFIG 291 292设置属性，使用Promise异步回调。 293 294**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 295 296**参数：** 297 298| 参数名 | 类型 | 必填 | 说明 | 299| -------- | -------- | -------- | -------- | 300| value | T | 是 | 设置的属性值。 | 301 302**返回值：** 303 304| 类型 | 说明 | 305| -------- | -------- | 306| Promise<void> | 无返回结果的Promise对象。 | 307 308**示例：** 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需要权限：ohos.permission.WRITE_ACCESSIBILITY_CONFIG 328 329设置属性，使用callback异步回调。 330 331**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 332 333**参数：** 334 335| 参数名 | 类型 | 必填 | 说明 | 336| -------- | -------- | -------- | -------- | 337| value | T | 是 | 设置的属性值。 | 338| callback | AsyncCallback<void> | 是 | 回调函数。 | 339 340**示例：** 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 is ${err.code}, message is ${err.message}`); 351 return; 352 } 353 console.info(`Succeeded in set highContrastText, value is ${value}`); 354}); 355``` 356 357### get 358 359get(): Promise<T>; 360 361获取属性，使用Promise异步回调。 362 363**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 364 365**返回值：** 366 367| 类型 | 说明 | 368| -------- | -------- | 369| Promise<T> | Promise对象，返回对应属性值。 | 370 371**示例：** 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 get highContrastText, data is ${data}`); 379}).catch((err: BusinessError) => { 380 console.error(`failed to get highContrastText, Code is ${err.code}, message is ${err.message}`); 381}); 382``` 383 384### get 385 386get(callback: AsyncCallback<T>): void; 387 388获取属性，使用callback异步回调。 389 390**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 391 392**参数：** 393 394| 参数名 | 类型 | 必填 | 说明 | 395| -------- | -------- | -------- | -------- | 396| callback | AsyncCallback<T> | 是 | 回调函数，返回属性值。 | 397 398**示例：** 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 is ${err.code}, message is ${err.message}`); 407 return; 408 } 409 console.info(`Succeeded in get highContrastText, data is ${data}`); 410}); 411``` 412 413### on 414 415on(callback: Callback<T>): void; 416 417需要权限：ohos.permission.READ_ACCESSIBILITY_CONFIG 418 419添加属性变化监听，使用callback异步回调。 420 421**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 422 423**参数：** 424 425| 参数名 | 类型 | 必填 | 说明 | 426| -------- | -------- | -------- | -------- | 427| callback | Callback<T> | 是 | 回调函数，在属性变化时通过此函数进行通知。 | 428 429**示例：** 430 431```ts 432import config from '@ohos.accessibility.config'; 433 434config.highContrastText.on((data: boolean) => { 435 console.info(`subscribe highContrastText success, result: ${JSON.stringify(data)}`); 436}); 437``` 438 439### off 440 441off(callback?: Callback<T>): void; 442 443需要权限：ohos.permission.READ_ACCESSIBILITY_CONFIG 444 445取消属性变化监听，使用callback异步回调。 446 447**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 448 449**参数：** 450 451| 参数名 | 类型 | 必填 | 说明 | 452| -------- | -------- | -------- | -------- | 453| callback | Callback<T> | 否 | 取消指定callback对象的事件响应。需与on()的callback一致。缺省时，表示注销所有已注册事件。 | 454 455**示例：** 456 457```ts 458import config from '@ohos.accessibility.config'; 459 460config.highContrastText.off((data: boolean) => { 461 console.info(`Unsubscribe highContrastText success, result: ${JSON.stringify(data)}`); 462}); 463``` 464 465## DaltonizationColorFilter 466 467用于不同弱视类型的校正颜色滤镜。 468颜色滤镜功能开启时（[daltonizationState](#属性)设置为true)，颜色滤镜的配置(即设置的DaltonizationColorFilter的值)生效；颜色滤镜功能关闭时（[daltonizationState](#属性)设置为false)，显示为正常类型<sup>11+</sup>。 469 470**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 471 472| 名称 | 说明 | 473| -------- | -------- | 474| Normal | 表示正常类型。 | 475| Protanomaly | 表示红色弱视类型。 | 476| Deuteranomaly | 表示绿色弱视类型。 | 477| Tritanomaly | 表示蓝色弱视类型。 | 478 479## ClickResponseTime<sup>11+</sup> 480 481用于不同时间长短的点击重复时间。 482 483**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 484 485| 名称 | 说明 | 486|-------------|------------| 487| Short | 表示短 (默认)。 | 488| Medium | 表示中。 | 489| Long | 表示长。 | 490 491## RepeatClickInterval<sup>11+</sup> 492 493用于不同时间间隔的忽略重复点击。 494忽略重复点击功能开启时（[ignoreRepeatClick](#属性)设置为true)，忽略重复点击的配置(即设置的RepeatClickInterval的值)生效；忽略重复点击功能关闭时（[ignoreRepeatClick](#属性)设置为false)，显示为正常类型。 495 496**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 497 498| 名称 | 说明 | 499|----------|-------| 500| Shortest | 表示最短。 | 501| Short | 表示短。 | 502| Medium | 表示中。 | 503| Long | 表示长。 | 504| Longest | 表示最长。 | 505 506