@ohos.accessibility.config (System Accessibility Configuration)

The System Accessibility Configuration module allows you to configure 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.
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. The value True means to enable mono audio, and False means the opposite.
audioBalance10+ Config<number> Yes Yes Audio balance for the left and right audio channels. The value ranges from -1.0 to 1.0.

enableAbility

enableAbility(name: string, capability: Array<accessibility.Capability>): Promise<void>;

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';

let name: string = 'com.ohos.example/axExtension';
let capability : accessibility.Capability[] = ['retrieve'];
try {
    config.enableAbility(name, capability).then(() => {
      console.info('enable ability succeed');
    }).catch((err: object) => {
      console.error('failed to enable ability, because ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('failed to enable ability, because ' + JSON.stringify(exception));
};

enableAbility

enableAbility(name: string, capability: Array<accessibility.Capability>, callback: AsyncCallback<void>): void;

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'];
try {
    config.enableAbility(name, capability, (err: BusinessError<void>) => {
        if (err) {
            console.error('failed to enable ability, because ' + JSON.stringify(err));
            return;
        }
        console.info('enable ability succeed');
    });
} catch (exception) {
    console.error('failed to enable ability, because ' + JSON.stringify(exception));
};

disableAbility

disableAbility(name: string): Promise<void>;

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';

let name: string = 'com.ohos.example/axExtension';
try {
    config.disableAbility(name).then(() => {
      console.info('disable ability succeed');
    }).catch((err: object) => {
      console.error('failed to disable ability, because ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('failed to disable ability, because ' + JSON.stringify(exception));
};

disableAbility

disableAbility(name: string, callback: AsyncCallback<void>): void;

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';
try {
    config.disableAbility(name, (err: BusinessError<void>) => {
        if (err) {
            console.error('failed to enable ability, because ' + JSON.stringify(err));
            return;
        }
        console.info('disable succeed');
    });
} catch (exception) {
    console.error('failed to enable ability, because ' + JSON.stringify(exception));
};

on('enabledAccessibilityExtensionListChange')

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

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';

try {
    config.on('enabledAccessibilityExtensionListChange', () => {
        console.info('subscribe enabled accessibility extension list change state success');
    });
} catch (exception) {
    console.error('failed to subscribe enabled accessibility extension list change state, because ' +
    JSON.stringify(exception));
};

off('enabledAccessibilityExtensionListChange')

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

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.

Example

import config from '@ohos.accessibility.config';

try {
    config.off('enabledAccessibilityExtensionListChange', () => {
        console.info('Unsubscribe enabled accessibility extension list change state success');
    });
} catch (exception) {
    console.error('failed to Unsubscribe enabled accessibility extension list change state, because ' +
    JSON.stringify(exception));
};

Config

Implements configuration, acquisition, and listening for attributes.

set

set(value: T): Promise<void>;

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';

let value: boolean = true;
try {
    config.highContrastText.set(value).then(() => {
        console.info('set highContrastText succeed');
    }).catch((err: object) => {
        console.error('failed to set highContrastText, because ' + JSON.stringify(err));
    });
} catch (exception) {
    console.error('failed to set config, because ' + JSON.stringify(exception));
};

set

set(value: T, callback: AsyncCallback<void>): void;

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;
try {
    config.highContrastText.set(value, (err: BusinessError<void>) => {
        if (err) {
            console.error('failed to set highContrastText, because ' + JSON.stringify(err));
            return;
        }
        console.info('set highContrastText succeed');
    });
} catch (exception) {
    console.error('failed to set config, because ' + JSON.stringify(exception));
};

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';

let value: boolean;
config.highContrastText.get().then((data: boolean) => {
    value = data;
    console.info('get highContrastText success');
}).catch((err: object) => {
    console.error('failed to get highContrastText, because ' + JSON.stringify(err));
});

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';

let value: boolean;
config.highContrastText.get((err: BusinessError<void>, data: boolean) => {
    if (err) {
        console.error('failed to get highContrastText, because ' + JSON.stringify(err));
        return;
    }
    value = data;
    console.info('get highContrastText success');
});

on

on(callback: Callback<T>): void;

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';

try {
    config.highContrastText.on((data: boolean) => {
        console.info('subscribe highContrastText success, result: ' + JSON.stringify(data));
    });
} catch (exception) {
    console.error('failed subscribe highContrastText, because ' + JSON.stringify(exception));
}

off

off(callback?: Callback<T>): void;

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.

Example

import config from '@ohos.accessibility.config';

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

DaltonizationColorFilter

Enumerates the daltonization filters.

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.