@ohos.accessibility.config (System Accessibility Configuration) (System API)
The accessibility.config module provides APIs for configuring system accessibility features, including accessibility extension, high-contrast text, mouse buttons, and captions.
NOTE
- 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.
- The APIs provided by this module are system APIs.
Modules to Import
import config from '@ohos.accessibility.config';
Attributes
System capability: SystemCapability.BarrierFree.Accessibility.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
highContrastText | Config<boolean> | Yes | Yes | Whether to enable high-contrast text. |
invertColor | Config<boolean> | Yes | Yes | Whether to enable color inversion. |
daltonizationState11+ | Config<boolean> | Yes | Yes | Whether to enable daltonization. It must be used with daltonizationColorFilter. |
daltonizationColorFilter | Config<DaltonizationColorFilter> | Yes | Yes | Configuration of the daltonization filter. |
contentTimeout | Config<number> | Yes | Yes | Recommended duration for content display. The value ranges from 0 to 5000, in milliseconds. |
animationOff | Config<boolean> | Yes | Yes | Whether to disable animation. |
brightnessDiscount | Config<number> | Yes | Yes | Brightness discount. The value ranges from 0 to 1.0. |
mouseKey | Config<boolean> | Yes | Yes | Whether to enable the mouse button feature. |
mouseAutoClick | Config<number> | Yes | Yes | Interval for automatic mouse clicks. The value ranges from 0 to 5000, in milliseconds. |
shortkey | Config<boolean> | Yes | Yes | Whether to enable the accessibility extension shortcut key. |
shortkeyTarget | Config<string> | Yes | Yes | Target application for the accessibility extension shortcut key. The value format is 'bundleName/abilityName'. |
captions | Config<boolean> | Yes | Yes | Whether to enable captions. |
captionsStyle | Config<accessibility.CaptionsStyle> | Yes | Yes | Captions style. |
audioMono10+ | Config<boolean> | Yes | Yes | Whether to enable mono audio. |
audioBalance10+ | Config<number> | Yes | Yes | Audio balance for the left and right audio channels. The value ranges from -1.0 to +1.0. |
shortkeyMultiTargets11+ | Config<Array<string>> | Yes | Yes | List of target applications for the accessibility shortcut keys. The value format is ['bundleName/abilityName']. |
clickResponseTime11+ | Config<ClickResponseTime> | Yes | Yes | Length of time required for a click. |
ignoreRepeatClick11+ | Config<boolean> | Yes | Yes | Whether to ignore repeated clicks. This parameter must be used together with repeatClickInterval. |
repeatClickInterval11+ | Config<RepeatClickInterval> | Yes | Yes | Interval between repeated clicks. |
For a Boolean return value, True means that the feature is enabled, and False means the opposite.
enableAbility
enableAbility(name: string, capability: Array<accessibility.Capability>): Promise<void>;
Required permissions: ohos.permission.WRITE_ACCESSIBILITY_CONFIG
Enables an accessibility extension ability. This API uses a promise to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Name of the accessibility extension ability. The format is 'bundleName/abilityName'. |
capability | Array<accessibility.Capability> | Yes | Capability of the accessibility extension ability. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Accessibility Error Codes.
ID | Error Message |
---|---|
9300001 | Invalid bundle name or ability name. |
9300002 | Target ability already enabled. |
Example
import accessibility from '@ohos.accessibility';
import config from '@ohos.accessibility.config';
import { BusinessError } from '@ohos.base';
let name: string = 'com.ohos.example/axExtension';
let capability: accessibility.Capability[] = ['retrieve'];
config.enableAbility(name, capability).then(() => {
console.info(`Succeeded in enable ability, name is ${name}, capability is ${capability}`);
}).catch((err: BusinessError) => {
console.error(`failed to enable ability, Code is ${err.code}, message is ${err.message}`);
});
enableAbility
enableAbility(name: string, capability: Array<accessibility.Capability>, callback: AsyncCallback<void>): void;
Required permissions: ohos.permission.WRITE_ACCESSIBILITY_CONFIG
Enables an accessibility extension ability. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Name of the accessibility extension ability. The format is 'bundleName/abilityName'. |
capability | Array<accessibility.Capability> | Yes | Capability of the accessibility extension ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Accessibility Error Codes.
ID | Error Message |
---|---|
9300001 | Invalid bundle name or ability name. |
9300002 | Target ability already enabled. |
Example
import accessibility from '@ohos.accessibility';
import config from '@ohos.accessibility.config';
import { BusinessError } from '@ohos.base';
let name: string = 'com.ohos.example/axExtension';
let capability: accessibility.Capability[] = ['retrieve'];
config.enableAbility(name, capability, (err: BusinessError) => {
if (err) {
console.error(`failed to enable ability, Code is ${err.code}, message is ${err.message}`);
return;
}
console.info(`Succeeded in enable ability, name is ${name}, capability is ${capability}`);
});
disableAbility
disableAbility(name: string): Promise<void>;
Required permissions: ohos.permission.WRITE_ACCESSIBILITY_CONFIG
Disables an accessibility extension ability. This API uses a promise to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Name of the accessibility extension ability. The format is 'bundleName/abilityName'. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Accessibility Error Codes.
ID | Error Message |
---|---|
9300001 | Invalid bundle name or ability name. |
Example
import accessibility from '@ohos.accessibility';
import config from '@ohos.accessibility.config';
import { BusinessError } from '@ohos.base';
let name: string = 'com.ohos.example/axExtension';
config.disableAbility(name).then(() => {
console.info(`Succeeded in disable ability, name is ${name}`);
}).catch((err: BusinessError) => {
console.error(`failed to disable ability, Code is ${err.code}, message is ${err.message}`);
})
disableAbility
disableAbility(name: string, callback: AsyncCallback<void>): void;
Required permissions: ohos.permission.WRITE_ACCESSIBILITY_CONFIG
Disables an accessibility extension ability. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Name of the accessibility extension ability. The format is 'bundleName/abilityName'. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Accessibility Error Codes.
ID | Error Message |
---|---|
9300001 | Invalid bundle name or ability name. |
Example
import accessibility from '@ohos.accessibility';
import config from '@ohos.accessibility.config';
import { BusinessError } from '@ohos.base';
let name: string = 'com.ohos.example/axExtension';
config.disableAbility(name, (err: BusinessError) => {
if (err) {
console.error(`failed to enable ability, Code is ${err.code}, message is ${err.message}`);
return;
}
console.info(`Succeeded in disable, name is ${name}`);
});
on('enabledAccessibilityExtensionListChange')
on(type: 'enabledAccessibilityExtensionListChange', callback: Callback<void>): void;
Required permissions: ohos.permission.READ_ACCESSIBILITY_CONFIG
Adds a listener for changes in the list of enabled accessibility extension abilities. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Listening type. The value is fixed at 'enabledAccessibilityExtensionListChange', indicating listening for changes in the list of enabled accessibility extension abilities. |
callback | Callback<void> | Yes | Callback invoked when the list of enabled accessibility extension abilities changes. |
Example
import config from '@ohos.accessibility.config';
config.on('enabledAccessibilityExtensionListChange', () => {
console.info('subscribe enabled accessibility extension list change state success');
});
off('enabledAccessibilityExtensionListChange')
off(type: 'enabledAccessibilityExtensionListChange', callback?: Callback<void>): void;
Required permissions: ohos.permission.READ_ACCESSIBILITY_CONFIG
Cancels the listener for changes in the list of enabled accessibility extension abilities. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Listening type. The value is fixed at 'enabledAccessibilityExtensionListChange', indicating listening for changes in the list of enabled accessibility extension abilities. |
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. |
Example
import config from '@ohos.accessibility.config';
config.off('enabledAccessibilityExtensionListChange', () => {
console.info('Unsubscribe enabled accessibility extension list change state success');
});
Config
Implements configuration, acquisition, and listening for attributes.
set
set(value: T): Promise<void>;
Required permissions: ohos.permission.WRITE_ACCESSIBILITY_CONFIG
Sets the attribute value. This API uses a promise to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
value | T | Yes | Attribute value to set. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Example
import config from '@ohos.accessibility.config';
import { BusinessError } from '@ohos.base';
let value: boolean = true;
config.highContrastText.set(value).then(() => {
console.info(`Succeeded in set highContrastText value is ${value}`);
}).catch((err: BusinessError) => {
console.error(`failed to set highContrastText, Code is ${err.code}, message is ${err.message}`);
});
set
set(value: T, callback: AsyncCallback<void>): void;
Required permissions: ohos.permission.WRITE_ACCESSIBILITY_CONFIG
Sets the attribute value. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
value | T | Yes | Attribute value to set. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
import config from '@ohos.accessibility.config';
import { BusinessError } from '@ohos.base';
let value: boolean = true;
config.highContrastText.set(value, (err: BusinessError) => {
if (err) {
console.error(`Failed to set highContrastText. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in setting highContrastText. Value: ${value}`);
});
get
get(): Promise<T>;
Obtains the attribute value. This API uses a promise to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Return value
Type | Description |
---|---|
Promise<T> | Promise used to return the value obtained. |
Example
import config from '@ohos.accessibility.config';
import { BusinessError } from '@ohos.base';
config.highContrastText.get().then((data: boolean) => {
console.info(`Succeeded in getting highContrastText. Data: ${data}`);
}).catch((err: BusinessError) => {
console.error(`Failed to get highContrastText. Code: ${err.code}, message: ${err.message}`);
});
get
get(callback: AsyncCallback<T>): void;
Obtains the attribute value. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<T> | Yes | Callback used to return the attribute value. |
Example
import config from '@ohos.accessibility.config';
import { BusinessError } from '@ohos.base';
config.highContrastText.get((err: BusinessError, data: boolean) => {
if (err) {
console.error(`Failed to get highContrastText. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in getting highContrastText. Data: ${data}`);
});
on
on(callback: Callback<T>): void;
Required permissions: ohos.permission.READ_ACCESSIBILITY_CONFIG
Adds a listener for attribute changes. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | Callback<T> | Yes | Callback invoked when the attribute changes. |
Example
import config from '@ohos.accessibility.config';
config.highContrastText.on((data: boolean) => {
console.info(`Succeeded in subscribing to highContrastText. Result: ${JSON.stringify(data)}`);
});
off
off(callback?: Callback<T>): void;
Required permissions: ohos.permission.READ_ACCESSIBILITY_CONFIG
Cancels the listener for attribute changes. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
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. |
Example
import config from '@ohos.accessibility.config';
config.highContrastText.off((data: boolean) => {
console.info(`Succeeded in unsubscribing from highContrastText. Result: ${JSON.stringify(data)}`);
});
DaltonizationColorFilter
Enumerates the daltonization filters. When daltonization is enabled (with daltonizationState set to true), the filter set for users with disabilities is used; otherwise, the filter for normal uses is used.11+
System capability: SystemCapability.BarrierFree.Accessibility.Core
Name | Description |
---|---|
Normal | Filter for normal users. |
Protanomaly | Filter for protanomaly. |
Deuteranomaly | Filter for deuteranomaly. |
Tritanomaly | Filter for tritanomaly. |
ClickResponseTime11+
Defines the length of time for a click.
System capability: SystemCapability.BarrierFree.Accessibility.Core
Name | Description |
---|---|
Short | Short (default). |
Medium | Medium. |
Long | Long. |
RepeatClickInterval11+
Defines the interval between repeated clicks. RepeatClickInterval takes effect only when repeated clicks are ignored (ignoreRepeatClick set to true).
System capability: SystemCapability.BarrierFree.Accessibility.Core
Name | Description |
---|---|
Shortest | Shortest. |
Short | Short. |
Medium | Medium. |
Long | Long. |
Longest | Longest. |