@ohos.accessibility.config (SystemAPI)

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 '@kit.AccessibilityKit';

Attributes

System capability: SystemCapability.BarrierFree.Accessibility.Core

Name	Type	Readable	Writable	Description
highContrastText	Config<boolean>	Yes	Yes	Whether to enable high-contrast text. The value true indicates that high-contrast text is enabled, and false indicates the opposite. Default value: false.
invertColor	Config<boolean>	Yes	Yes	Whether to enable color inversion. The value true indicates that color inversion is enabled, and false indicates the opposite. Default value: false.
daltonizationState11+	Config<boolean>	Yes	Yes	Whether to enable daltonization. It must be used with daltonizationColorFilter. The value true indicates that daltonization is enabled, and false indicates the opposite. Default value: false.
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. Default value: 0.
animationOff	Config<boolean>	Yes	Yes	Whether to disable animation. The value true indicates that animation is disabled, and false indicates the opposite. Default value: 0.
brightnessDiscount	Config<number>	Yes	Yes	Brightness discount. The value ranges from 0 to 1.0. Default value: 0.0.
mouseKey	Config<boolean>	Yes	Yes	Whether to enable the mouse button. The value true indicates that the mouse button is enabled, and false indicates the opposite. Default value: 0.
mouseAutoClick	Config<number>	Yes	Yes	Configuration of the automatic mouse click operation. The value ranges from 0 to 5000, in milliseconds. The value 0 indicates that the automatic mouse click is not triggered; other values indicate that the operation is triggered when the mouse pointer is hovered for a specified period of time. Default value: 0.
shortkey	Config<boolean>	Yes	Yes	Whether to enable the accessibility extension shortcut key. The value true indicates that the auxiliary extension shortcut key is enabled, and false indicates the opposite. Default value: false.
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. The value true indicates that caption is enabled, and false indicates the opposite. Default value: false.
captionsStyle	Config<accessibility.CaptionsStyle>	Yes	Yes	Captions style.
audioMono10+	Config<boolean>	Yes	Yes	Whether to enable mono audio. The value true indicates that mono audio is enabled, and false indicates the opposite. Default value: false.
audioBalance10+	Config<number>	Yes	Yes	Audio balance for the left and right audio channels. The value ranges from -1.0 to 1.0. Default value: 0.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. The value true indicates that the feature of ignoring repeated clicks is enabled, and false indicates the opposite. Default value: false.
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.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
9300001	Invalid bundle name or ability name.
9300002	Target ability already enabled.

Example

import { accessibility, config } from '@kit.AccessibilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
9300001	Invalid bundle name or ability name.
9300002	Target ability already enabled.

Example

import { accessibility, config } from '@kit.AccessibilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
9300001	Invalid bundle name or ability name.

Example

import { accessibility, config } from '@kit.AccessibilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
9300001	Invalid bundle name or ability name.

Example

import { accessibility, config } from '@kit.AccessibilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { config } from '@kit.AccessibilityKit';

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 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>	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.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { config } from '@kit.AccessibilityKit';

config.off('enabledAccessibilityExtensionListChange', () => {
  console.info('Unsubscribe enabled accessibility extension list change state success');
});

on('installedAccessibilityListChange')¹²⁺

on(type: 'installedAccessibilityListChange', callback: Callback<void>): void;

Required permissions: ohos.permission.READ_ACCESSIBILITY_CONFIG

Adds a listener for changes in the list of installed 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 'installedAccessibilityListChange', indicating listening for changes in the list of enabled accessibility extension abilities.
callback	Callback<void>	Yes	Callback invoked when the list of installed accessibility extension abilities changes.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { config } from '@kit.AccessibilityKit';

config.on('installedAccessibilityListChange', () => {
  console.info('subscribe installed accessibility extension list change state success');
});

off('installedAccessibilityListChange')¹²⁺

off(type: 'installedAccessibilityListChange', callback?: Callback<void>): void;

Required permissions: ohos.permission.READ_ACCESSIBILITY_CONFIG

Cancels a listener for changes in the list of installed 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 'installedAccessibilityListChange', 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('installedAccessibilityListChange'). If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { config } from '@kit.AccessibilityKit';

config.off('installedAccessibilityListChange', () => {
  console.info('Unsubscribe installed 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.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { config } from '@kit.AccessibilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { config } from '@kit.AccessibilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let value: boolean = true;

config.highContrastText.set(value, (err: BusinessError) => {
  if (err) {
    console.error(`failed to set highContrastText, Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`Succeeded in set highContrastText, value is ${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.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

import { config } from '@kit.AccessibilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

config.highContrastText.get().then((data: boolean) => {
  console.info(`Succeeded in get highContrastText, data is ${data}`);
}).catch((err: BusinessError) => {
  console.error(`failed to get highContrastText, Code is ${err.code}, message is ${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.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
202	Permission verification failed. A non-system application calls a system API.

Example

import { config } from '@kit.AccessibilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

config.highContrastText.get((err: BusinessError, data: boolean) => {
  if (err) {
    console.error(`failed to get highContrastText, Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`Succeeded in get highContrastText, data is ${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.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { config } from '@kit.AccessibilityKit';

config.highContrastText.on((data: boolean) => {
  console.info(`subscribe highContrastText success, 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.

Error codes

For details about the error codes, see Accessibility Error Codes.

Error Code	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.

Example

import { config } from '@kit.AccessibilityKit';

config.highContrastText.off((data: boolean) => {
  console.info(`Unsubscribe highContrastText success, result: ${JSON.stringify(data)}`);
});

DaltonizationColorFilter

Enumerates the daltonization filters. DaltonizationColorFilter takes effect only when the daltonization filter is enabled (daltonizationState set to true).

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.

ClickResponseTime¹¹⁺

Defines the length of time for a click.

System capability: SystemCapability.BarrierFree.Accessibility.Core

Name	Description
Short	Short (default).
Medium	Medium.
Long	Long.

RepeatClickInterval¹¹⁺

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.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Accessibility Kit

harmony 鸿蒙Accessibility Error Codes

harmony 鸿蒙@ohos.accessibility.GesturePath (Gesture Path)

harmony 鸿蒙@ohos.accessibility.GesturePoint (Gesture Point)

harmony 鸿蒙@ohos.accessibility (Accessibility)

harmony 鸿蒙@ohos.application.AccessibilityExtensionAbility (AccessibilityExtensionAbility)

harmony 鸿蒙AccessibilityExtensionContext (System API)

harmony 鸿蒙AccessibilityExtensionContext (Accessibility Extension Context)