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| daltonizationColorFilter | [Config](#config)<[DaltonizationColorFilter](#daltonizationcolorfilter)>| 是 | 是 | 表示颜色滤镜功能配置。 | 25| contentTimeout | [Config](#config)\<number>| 是 | 是 | 表示内容显示建议时长配置。取值 0~5000，单位为毫秒。 | 26| animationOff | [Config](#config)\<boolean>| 是 | 是 | 表示关闭动画功能启用状态。 | 27| brightnessDiscount | [Config](#config)\<number>| 是 | 是 | 表示亮度折扣系统配置。取值 0~1.0。 | 28| mouseKey | [Config](#config)\<boolean>| 是 | 是 | 表示鼠标键功能启用状态。 | 29| mouseAutoClick | [Config](#config)\<number>| 是 | 是 | 表示鼠标自动点击功能启用状态。取值 0~5000，单位为毫秒。 | 30| shortkey | [Config](#config)\<boolean>| 是 | 是 | 表示辅助扩展快捷键功能启用状态。 | 31| shortkeyTarget | [Config](#config)\<string>| 是 | 是 | 表示辅助扩展快捷键的目标配置。取值为辅助应用的名称，格式为：'bundleName/abilityName'。 | 32| captions | [Config](#config)\<boolean>| 是 | 是 | 表示辅助字幕功能启用状态。 | 33| captionsStyle | [Config](#config)\<[accessibility.CaptionsStyle](js-apis-accessibility.md#captionsstyle8)>| 是 | 是 | 表示辅助字幕的配置。 | 34| audioMono<sup>10+</sup>| [Config](#config)\<boolean>| 是 | 是 | 表示音频单声道的配置。True表示打开单声道，False表示关闭单声道。 | 35| audioBalance<sup>10+</sup>| [Config](#config)\<number>| 是 | 是 | 表示左右声道音量平衡的配置。取值 -1.0~1.0。 | 36 37## enableAbility 38 39enableAbility(name: string, capability: Array<accessibility.Capability>): Promise<void>; 40 41启用辅助扩展，使用Promise异步回调。 42 43**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 44 45**参数：** 46 47| 参数名 | 类型 | 必填 | 说明 | 48| -------- | -------- | -------- | -------- | 49| name | string | 是 | 辅助应用的名称，格式为：'bundleName/abilityName'。 | 50| capability | Array<[accessibility.Capability](js-apis-accessibility.md#capability)> | 是 | 辅助应用的能力属性。 | 51 52**返回值：** 53 54| 类型 | 说明 | 55| -------- | -------- | 56| Promise<void> | 无返回结果的Promise对象。 | 57 58**错误码：** 59 60以下错误码的详细介绍请参见[无障碍子系统错误码](../errorcodes/errorcode-accessibility.md)。 61 62| 错误码ID | 错误信息 | 63| ------- | -------------------------------- | 64| 9300001 | Invalid bundle name or ability name. | 65| 9300002 | Target ability already enabled. | 66 67**示例：** 68 69```ts 70import accessibility from '@ohos.accessibility'; 71import config from '@ohos.accessibility.config'; 72 73let name: string = 'com.ohos.example/axExtension'; 74let capability : accessibility.Capability[] = ['retrieve']; 75try { 76 config.enableAbility(name, capability).then(() => { 77 console.info('enable ability succeed'); 78 }).catch((err: object) => { 79 console.error('failed to enable ability, because ' + JSON.stringify(err)); 80 }); 81} catch (exception) { 82 console.error('failed to enable ability, because ' + JSON.stringify(exception)); 83}; 84``` 85 86## enableAbility 87 88enableAbility(name: string, capability: Array<accessibility.Capability>, callback: AsyncCallback<void>): void; 89 90启用辅助扩展，使用callback异步回调。 91 92**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| -------- | -------- | -------- | -------- | 98| name | string | 是 | 辅助应用的名称，格式为：'bundleName/abilityName'。 | 99| capability | Array<[accessibility.Capability](js-apis-accessibility.md#capability)> | 是 | 辅助应用的能力属性。 | 100| callback | AsyncCallback<void> | 是 | 回调函数。 | 101 102**错误码：** 103 104以下错误码的详细介绍请参见[无障碍子系统错误码](../errorcodes/errorcode-accessibility.md)。 105 106| 错误码ID | 错误信息 | 107| ------- | -------------------------------- | 108| 9300001 | Invalid bundle name or ability name. | 109| 9300002 | Target ability already enabled. | 110 111**示例：** 112 113```ts 114import accessibility from '@ohos.accessibility'; 115import config from '@ohos.accessibility.config'; 116import { BusinessError } from '@ohos.base'; 117 118let name: string = 'com.ohos.example/axExtension'; 119let capability: accessibility.Capability[] = ['retrieve']; 120try { 121 config.enableAbility(name, capability, (err: BusinessError<void>) => { 122 if (err) { 123 console.error('failed to enable ability, because ' + JSON.stringify(err)); 124 return; 125 } 126 console.info('enable ability succeed'); 127 }); 128} catch (exception) { 129 console.error('failed to enable ability, because ' + JSON.stringify(exception)); 130}; 131``` 132 133## disableAbility 134 135disableAbility(name: string): Promise<void>; 136 137关闭辅助扩展，使用Promise异步回调。 138 139**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 140 141**参数：** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| -------- | -------- | -------- | -------- | 145| name | string | 是 | 辅助应用的名称，格式为：'bundleName/abilityName'。 | 146 147**返回值：** 148 149| 类型 | 说明 | 150| -------- | -------- | 151| Promise<void> | 无返回结果的Promise对象。 | 152 153**错误码：** 154 155以下错误码的详细介绍请参见[无障碍子系统错误码](../errorcodes/errorcode-accessibility.md)。 156 157| 错误码ID | 错误信息 | 158| ------- | -------------------------------- | 159| 9300001 | Invalid bundle name or ability name. | 160 161**示例：** 162 163```ts 164import accessibility from '@ohos.accessibility'; 165import config from '@ohos.accessibility.config'; 166 167let name: string = 'com.ohos.example/axExtension'; 168try { 169 config.disableAbility(name).then(() => { 170 console.info('disable ability succeed'); 171 }).catch((err: object) => { 172 console.error('failed to disable ability, because ' + JSON.stringify(err)); 173 }); 174} catch (exception) { 175 console.error('failed to disable ability, because ' + JSON.stringify(exception)); 176}; 177``` 178 179## disableAbility 180 181disableAbility(name: string, callback: AsyncCallback<void>): void; 182 183关闭辅助扩展，使用callback异步回调。 184 185**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 186 187**参数：** 188 189| 参数名 | 类型 | 必填 | 说明 | 190| -------- | -------- | -------- | -------- | 191| name | string | 是 | 辅助应用的名称，格式为：'bundleName/abilityName'。 | 192| callback | AsyncCallback<void> | 是 | 回调函数。 | 193 194**错误码：** 195 196以下错误码的详细介绍请参见[无障碍子系统错误码](../errorcodes/errorcode-accessibility.md)。 197 198| 错误码ID | 错误信息 | 199| ------- | -------------------------------- | 200| 9300001 | Invalid bundle name or ability name. | 201 202**示例：** 203 204```ts 205import accessibility from '@ohos.accessibility'; 206import config from '@ohos.accessibility.config'; 207import { BusinessError } from '@ohos.base'; 208 209let name: string = 'com.ohos.example/axExtension'; 210try { 211 config.disableAbility(name, (err: BusinessError<void>) => { 212 if (err) { 213 console.error('failed to enable ability, because ' + JSON.stringify(err)); 214 return; 215 } 216 console.info('disable succeed'); 217 }); 218} catch (exception) { 219 console.error('failed to enable ability, because ' + JSON.stringify(exception)); 220}; 221``` 222 223## on('enabledAccessibilityExtensionListChange') 224 225on(type: 'enabledAccessibilityExtensionListChange', callback: Callback<void>): void; 226 227添加启用的辅助扩展的列表变化监听，使用callback异步回调。 228 229**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 230 231**参数：** 232 233| 参数名 | 类型 | 必填 | 说明 | 234| -------- | -------- | -------- | -------- | 235| type | string | 是 | 参数固定为enabledAccessibilityExtensionListChange，监听启用的辅助扩展的列表变化。 | 236| callback | Callback<void> | 是 | 回调函数，在启用的辅助扩展的列表变化时通过此函数进行通知。 | 237 238**示例：** 239 240```ts 241import config from '@ohos.accessibility.config'; 242 243try { 244 config.on('enabledAccessibilityExtensionListChange', () => { 245 console.info('subscribe enabled accessibility extension list change state success'); 246 }); 247} catch (exception) { 248 console.error('failed to subscribe enabled accessibility extension list change state, because ' + 249 JSON.stringify(exception)); 250}; 251``` 252 253## off('enabledAccessibilityExtensionListChange') 254 255off(type: 'enabledAccessibilityExtensionListChange', callback?: Callback<void>): void; 256 257取消启用的辅助扩展的列表变化监听，使用callback异步回调。 258 259**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 260 261**参数：** 262 263| 参数名 | 类型 | 必填 | 说明 | 264| -------- | -------- | -------- | -------- | 265| type | string | 是 | 参数固定为enabledAccessibilityExtensionListChange，监听启用的辅助扩展的列表变化。 | 266| callback | Callback<void> | 否 | 取消指定callback对象的事件响应。需与on('enabledAccessibilityExtensionListChange')的callback一致。缺省时，表示注销所有已注册事件。 | 267 268**示例：** 269 270```ts 271import config from '@ohos.accessibility.config'; 272 273try { 274 config.off('enabledAccessibilityExtensionListChange', () => { 275 console.info('Unsubscribe enabled accessibility extension list change state success'); 276 }); 277} catch (exception) { 278 console.error('failed to Unsubscribe enabled accessibility extension list change state, because ' + 279 JSON.stringify(exception)); 280}; 281``` 282 283## Config 284 285用于属性的设置、获取与监听。 286 287### set 288 289set(value: T): Promise<void>; 290 291设置属性，使用Promise异步回调。 292 293**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 294 295**参数：** 296 297| 参数名 | 类型 | 必填 | 说明 | 298| -------- | -------- | -------- | -------- | 299| value | T | 是 | 设置的属性值。 | 300 301**返回值：** 302 303| 类型 | 说明 | 304| -------- | -------- | 305| Promise<void> | 无返回结果的Promise对象。 | 306 307**示例：** 308 309```ts 310import config from '@ohos.accessibility.config'; 311 312let value: boolean = true; 313try { 314 config.highContrastText.set(value).then(() => { 315 console.info('set highContrastText succeed'); 316 }).catch((err: object) => { 317 console.error('failed to set highContrastText, because ' + JSON.stringify(err)); 318 }); 319} catch (exception) { 320 console.error('failed to set config, because ' + JSON.stringify(exception)); 321}; 322``` 323 324### set 325 326set(value: T, callback: AsyncCallback<void>): void; 327 328设置属性，使用callback异步回调。 329 330**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 331 332**参数：** 333 334| 参数名 | 类型 | 必填 | 说明 | 335| -------- | -------- | -------- | -------- | 336| value | T | 是 | 设置的属性值。 | 337| callback | AsyncCallback<void> | 是 | 回调函数。 | 338 339**示例：** 340 341```ts 342import config from '@ohos.accessibility.config'; 343import { BusinessError } from '@ohos.base'; 344 345let value: boolean = true; 346try { 347 config.highContrastText.set(value, (err: BusinessError<void>) => { 348 if (err) { 349 console.error('failed to set highContrastText, because ' + JSON.stringify(err)); 350 return; 351 } 352 console.info('set highContrastText succeed'); 353 }); 354} catch (exception) { 355 console.error('failed to set config, because ' + JSON.stringify(exception)); 356}; 357``` 358 359### get 360 361get(): Promise<T>; 362 363获取属性，使用Promise异步回调。 364 365**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 366 367**返回值：** 368 369| 类型 | 说明 | 370| -------- | -------- | 371| Promise<T> | Promise对象，返回对应属性值。 | 372 373**示例：** 374 375```ts 376import config from '@ohos.accessibility.config'; 377import { BusinessError } from '@ohos.base'; 378 379let value: boolean; 380config.highContrastText.get().then((data: boolean) => { 381 value = data; 382 console.info('get highContrastText success'); 383}).catch((err: object) => { 384 console.error('failed to get highContrastText, because ' + JSON.stringify(err)); 385}); 386``` 387 388### get 389 390get(callback: AsyncCallback<T>): void; 391 392获取属性，使用callback异步回调。 393 394**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 395 396**参数：** 397 398| 参数名 | 类型 | 必填 | 说明 | 399| -------- | -------- | -------- | -------- | 400| callback | AsyncCallback<T> | 是 | 回调函数，返回属性值。 | 401 402**示例：** 403 404```ts 405import config from '@ohos.accessibility.config'; 406import { BusinessError } from '@ohos.base'; 407 408let value: boolean; 409config.highContrastText.get((err: BusinessError<void>, data: boolean) => { 410 if (err) { 411 console.error('failed to get highContrastText, because ' + JSON.stringify(err)); 412 return; 413 } 414 value = data; 415 console.info('get highContrastText success'); 416}); 417``` 418 419### on 420 421on(callback: Callback<T>): void; 422 423添加属性变化监听，使用callback异步回调。 424 425**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 426 427**参数：** 428 429| 参数名 | 类型 | 必填 | 说明 | 430| -------- | -------- | -------- | -------- | 431| callback | Callback<T> | 是 | 回调函数，在属性变化时通过此函数进行通知。 | 432 433**示例：** 434 435```ts 436import config from '@ohos.accessibility.config'; 437 438try { 439 config.highContrastText.on((data: boolean) => { 440 console.info('subscribe highContrastText success, result: ' + JSON.stringify(data)); 441 }); 442} catch (exception) { 443 console.error('failed subscribe highContrastText, because ' + JSON.stringify(exception)); 444} 445``` 446 447### off 448 449off(callback?: Callback<T>): void; 450 451取消属性变化监听，使用callback异步回调。 452 453**系统能力**：SystemCapability.BarrierFree.Accessibility.Core 454 455**参数：** 456 457| 参数名 | 类型 | 必填 | 说明 | 458| -------- | -------- | -------- | -------- | 459| callback | Callback<T> | 否 | 取消指定callback对象的事件响应。需与on()的callback一致。缺省时，表示注销所有已注册事件。 | 460 461**示例：** 462 463```ts 464import config from '@ohos.accessibility.config'; 465 466config.highContrastText.off((data: boolean) => { 467 console.info('Unsubscribe highContrastText success, result: ' + JSON.stringify(data)); 468}); 469``` 470 471## DaltonizationColorFilter 472 473用于不同弱视类型的校正颜色滤镜。 474 475**系统能力**：以下各项对应的系统能力均为 SystemCapability.BarrierFree.Accessibility.Core 476 477| 名称 | 说明 | 478| -------- | -------- | 479| Normal | 表示正常类型。 | 480| Protanomaly | 表示红色弱视类型。 | 481| Deuteranomaly | 表示绿色弱视类型。 | 482| Tritanomaly | 表示蓝色弱视类型。 | 483