@ohos.settings (Data Item Settings)

The settings module provides APIs for setting data items.

NOTE

• The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

• If no value is obtained for the accessed data item, it indicates that the current system app does not add the value of the data item to the database.

Modules to Import

import { settings } from '@kit.BasicServicesKit';

domainName

Provides the domain name.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
DEVICE_SHARED11+	string	Yes	Shared device domain. All configurations in this domain are not distinguished between multiple users.
USER_PROPERTY11+	string	Yes	User attribute domain. All configurations in this domain are distinguished between multiple users.

date

Provides data items for setting the time and date formats.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
DATE_FORMAT(deprecated21)	string	Yes	Date format. The value can be mm/dd/yyyy, dd/mm/yyyy, or yyyy/mm/dd, where mm indicates the month, dd indicates the day, and yyyy indicates the year. (This constant is deprecated.)
TIME_FORMAT	string	Yes	Time format. The options are as follows: - 12: 12-hour format. - 24: 24-hour format.
AUTO_GAIN_TIME(deprecated21)	string	Yes	Whether the date, time, and time zone are automatically obtained from the Network Identity and Time Zone (NITZ). - true: Information is automatically obtained. - false: Information is not automatically obtained. (This constant is deprecated.)
AUTO_GAIN_TIME_ZONE(deprecated21)	string	Yes	Whether the time zone is automatically obtained from NITZ. - true: Time zone is automatically obtained. - false: Time zone is not automatically obtained. (This constant is deprecated.)

display

Provides data items for setting the display effects.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
FONT_SCALE	string	Yes	Scale factor of the font (domainName: USER_PROPERTY). The value is a floating point number. The standard scale factor is 1, and allowed scale factors include 0.85, 1.15, 1.3, and 1.45. In care mode, 1.75, 2, and 3.2 are available.
SCREEN_BRIGHTNESS_STATUS	string	Yes	Screen brightness, with the value ranging from 0 to 255.
AUTO_SCREEN_BRIGHTNESS	string	Yes	Whether automatic screen brightness adjustment is enabled. - AUTO_SCREEN_BRIGHTNESS_MODE: Automatic screen brightness adjustment is enabled. - MANUAL_SCREEN_BRIGHTNESS_MODE: Automatic screen brightness adjustment is disabled.
AUTO_SCREEN_BRIGHTNESS_MODE	number	Yes	Value of AUTO_SCREEN_BRIGHTNESS when automatic screen brightness adjustment is enabled.
MANUAL_SCREEN_BRIGHTNESS_MODE	number	Yes	Value of AUTO_SCREEN_BRIGHTNESS when automatic screen brightness adjustment is disabled.
SCREEN_OFF_TIMEOUT	string	Yes	Waiting time for the device to enter the sleep state when not in use (unit: ms).
DEFAULT_SCREEN_ROTATION(deprecated21)	string	Yes	This attribute is invalid when screen auto-rotation is enabled; otherwise, the following options are available: - 0: The screen rotates by 0 degrees. - 1: The screen rotates by 90 degrees. - 2: The screen rotates by 180 degrees. - 3: The screen rotates by 270 degrees. (This constant is deprecated.)
ANIMATOR_DURATION_SCALE(deprecated21)	string	Yes	Scale factor for the animation duration, which affects the start delay and duration of all such animations. - 0: The animation ends immediately. - 1: default value. (This constant is deprecated.)
TRANSITION_ANIMATION_SCALE(deprecated21)	string	Yes	Scale factor for transition animations. - 0: Transition animations are disabled. (This constant is deprecated.)
WINDOW_ANIMATION_SCALE(deprecated21)	string	Yes	Scale factor for normal window animations. - 0: Window animations are disabled (This constant is deprecated.)
DISPLAY_INVERSION_STATUS(deprecated21)	string	Yes	Whether display color inversion is enabled. - 1: Display color inversion is enabled. - 0: Display color inversion is disabled. (This constant is deprecated.)

general

Provides data items for setting the general information about the device.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
SETUP_WIZARD_FINISHED(deprecated21)	string	Yes	Whether the startup wizard has been run. - 0: The startup wizard is not run. - non-zero value: The startup wizard has been run. (This constant is deprecated.)
END_BUTTON_ACTION(deprecated21)	string	Yes	Action after the call end button is pressed if the user is not in a call. - 0: Nothing happens. - 1: The home screen is displayed. - 2: The device enters the sleep state and the screen is locked. - 3: The home screen is displayed. If the user is on the home screen, the device will enter sleep mode automatically. (This constant is deprecated.)
ACCELEROMETER_ROTATION_STATUS	string	Yes	Whether the accelerometer is used to change screen orientation, that is, whether to enable auto-rotation. - 1: The accelerometer is used. - 0: The accelerometer is not used.
DEVICE_PROVISION_STATUS(deprecated21)	string	Yes	Whether the device is preconfigured. On a multi-user device with a single system user, the screen may be locked when the value is true. In addition, other features cannot be started on the system user unless they are marked to display on the lock screen. (This constant is deprecated.)
HDC_STATUS(deprecated21)	string	Yes	Whether the hard disk controller (HDC) on the USB device is enabled. - true: HDC is enabled. - false: HDC is disabled. (This constant is deprecated.)
BOOT_COUNTING(deprecated21)	string	Yes	Number of boot operations after the device is powered on. (This constant is deprecated.)
CONTACT_METADATA_SYNC_STATUS(deprecated21)	string	Yes	Whether contacts metadata synchronization is enabled. - true: Contacts metadata synchronization is enabled. - false: Contacts metadata synchronization is disabled. (This constant is deprecated.)
DEVICE_NAME	string	Yes	Device name.
USB_STORAGE_STATUS(deprecated21)	string	Yes	Whether USB mass storage is enabled. - true: USB mass storage is enabled. - false: USB mass storage is disabled. (This constant is deprecated.)
DEBUGGER_WAITING(deprecated21)	string	Yes	Whether the device waits for the debugger when starting an application to debug. - 1: The device waits for the debugger. - 0: The device does not wait for the debugger and the application runs normally. (This constant is deprecated.)
DEBUG_APP_PACKAGE(deprecated21)	string	Yes	Bundle name of the application to be debugged. (This constant is deprecated.)
ACCESSIBILITY_STATUS(deprecated21)	string	Yes	Whether accessibility is enabled. - 1: Accessibility is enabled. - 0: Accessibility is disabled. (This constant is deprecated.)
ACTIVATED_ACCESSIBILITY_SERVICES(deprecated21)	string	Yes	List of activated accessibility features. (This constant is deprecated.)
GEOLOCATION_ORIGINS_ALLOWED(deprecated21)	string	Yes	Default geographic location that can be used by the browser. Multiple geographical locations are separated by spaces. (This constant is deprecated.)
SKIP_USE_HINTS(deprecated21)	string	Yes	Whether the application should attempt to skip all introductory hints at the first startup. This feature is intended for temporary or experienced users. - 1: The application will skip all introductory hints at the first startup. - 0: The application will not skip introductory hints at the first startup. (This constant is deprecated.)
TOUCH_EXPLORATION_STATUS(deprecated21)	string	Yes	Whether touch exploration is enabled. - 1: Touch exploration is enabled. - 0: Touch exploration is disabled. (This constant is deprecated.)

input

Provides data items for setting input methods.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
DEFAULT_INPUT_METHOD(deprecated21)	string	Yes	Default input method and its ID. (This constant is deprecated.)
ACTIVATED_INPUT_METHOD_SUB_MODE	string	Yes	Type and ID of the default input method keyboard.
ACTIVATED_INPUT_METHODS(deprecated21)	string	Yes	List of activated input methods. The list is a string that contains the IDs and keyboard types of activated input methods. The IDs are separated by colons (😃, and keyboard types are separated by semicolons (😉. An example format is ima0:keyboardType0;keyboardType1;ima1:ima2:keyboardTypes0, where ima indicates the ID of an input method, and keyboardType indicates the keyboard type. (This constant is deprecated.)
SELECTOR_VISIBILITY_FOR_INPUT_METHOD(deprecated21)	string	Yes	Whether the input method selector is visible. - 1: The input method selector is visible. - 0: The input method selector is invisible. (This constant is deprecated.)
AUTO_CAPS_TEXT_INPUT(deprecated21)	string	Yes	Whether automatic capitalization is enabled for the text editor. - 0: Automatic capitalization is disabled. - 1: Automatic capitalization is enabled. (This constant is deprecated.)
AUTO_PUNCTUATE_TEXT_INPUT(deprecated21)	string	Yes	Whether automatic punctuation is enabled for the text editor. Automatic punctuation enables the text editor to convert two spaces into a period (.) and a space. - 0: Automatic punctuation is disabled. - 1: Automatic punctuation is enabled. (This constant is deprecated.)
AUTO_REPLACE_TEXT_INPUT(deprecated21)	string	Yes	Whether autocorrect is enabled for the text editor. Autocorrect enables the text editor to correct typos. - 0: Autocorrect is disabled. - 1: Autocorrect is enabled. (This constant is deprecated.)
SHOW_PASSWORD_TEXT_INPUT(deprecated21)	string	Yes	Whether password presentation is enabled in the text editor. Password presentation enables the text editor to show password characters when the user types them. - 0: Password presentation is disabled. - 1: Password presentation is enabled. (This constant is deprecated.)

network

Provides data items for setting network information.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
DATA_ROAMING_STATUS(deprecated21)	string	Yes	Whether data roaming is enabled. - true: Data roaming is enabled. - false: Data roaming is disabled. (This constant is deprecated.)
HTTP_PROXY_CFG(deprecated21)	string	Yes	Host name and port number of the global HTTP proxy. The host name and port number are separated by a colon (😃. (This constant is deprecated.)
NETWORK_PREFERENCE_USAGE(deprecated21)	string	Yes	User preferences for the network to use. (This constant is deprecated.)

phone

Provides data items for setting the modes of answering incoming and outgoing calls.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
RTT_CALLING_STATUS(deprecated21)	string	Yes	Whether the real-time text (RTT) call feature is enabled. If this feature is enabled, incoming and outgoing calls are answered as RTT calls when supported by the device and carrier. - 1: RTT is enabled. - 0: RTT is disabled. (This constant is deprecated.)

sound

Provides data items for setting the sound effects.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
VIBRATE_WHILE_RINGING(deprecated21)	string	Yes	Whether the device vibrates when it is ringing for an incoming call. This property is applicable to the phone and settings applications and affects only the scenario where the device rings for an incoming call. It does not affect any other application or scenario. (This constant is deprecated.)
DEFAULT_ALARM_ALERT(deprecated21)	string	Yes	Storage area of the system default alarms and alerts. (This constant is deprecated.)
DTMF_TONE_TYPE_WHILE_DIALING(deprecated21)	string	Yes	Type of the dual tone multi-frequency (DTMF) tone played while dialing. - 0: normal short tone. - 1: long tone. (This constant is deprecated.)
DTMF_TONE_WHILE_DIALING(deprecated21)	string	Yes	Whether the DTMF tone is played when dialing. - 1: DTMF tone is played when dialing. - 0: DTMF tone is not played when dialing. (This constant is deprecated.)
AFFECTED_MODE_RINGER_STREAMS(deprecated21)	string	Yes	Effect on audio streams determined by changes in the ringing mode and Do Not Disturb (DND) mode. If you want a specific audio stream to be affected by changes of the ringing mode and DND mode, set the corresponding bit to 1. (This constant is deprecated.)
AFFECTED_MUTE_STREAMS(deprecated21)	string	Yes	Audio streams affected by the mute mode. If you want a specific audio stream to remain muted in mute mode, set the corresponding bit to 1. (This constant is deprecated.)
DEFAULT_NOTIFICATION_SOUND(deprecated21)	string	Yes	Storage area of the system default notification tone. (This constant is deprecated.)
DEFAULT_RINGTONE(deprecated21)	string	Yes	Storage area of the system default ringtone. (This constant is deprecated.)
SOUND_EFFECTS_STATUS(deprecated21)	string	Yes	Whether the sound feature is available. - 0: The sound feature is not available. - 1: The sound feature is available. (This constant is deprecated.)
VIBRATE_STATUS(deprecated21)	string	Yes	Whether the device vibrates for an event. This attribute is used inside the system. - 1: The device vibrates for an event. - 0: The device does not vibrate for an event. (This constant is deprecated.)
HAPTIC_FEEDBACK_STATUS(deprecated21)	string	Yes	Whether haptic feedback is enabled. - true: Haptic feedback is enabled. - false: Haptic feedback is disabled. (This constant is deprecated.)

TTS

Provides data items for setting text-to-speech (TTS) information.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
DEFAULT_TTS_PITCH(deprecated21)	string	Yes	Default pitch of the TTS engine. 100 = 1x. If the value is set to 200, the frequency is twice the normal sound frequency. (This constant is deprecated.)
DEFAULT_TTS_RATE(deprecated21)	string	Yes	Default voice rate of the TTS engine. 100 = 1x. (This constant is deprecated.)
DEFAULT_TTS_SYNTH(deprecated21)	string	Yes	Default TTS engine. (This constant is deprecated.)
ENABLED_TTS_PLUGINS(deprecated21)	string	Yes	List of activated plug-in packages used for TTS. Multiple plug-in packages are separated by spaces. (This constant is deprecated.)

wireless

Provides data items for setting wireless network information.

Constants

System capability: SystemCapability.Applications.Settings.Core

Name	Type	Read-Only	Description
BLUETOOTH_DISCOVER_ABILITY_STATUS(deprecated21)	string	Yes	Whether the device can be discovered or connected by other devices through Bluetooth. - 0: The device cannot be discovered or connected. - 1: The device can be connected but cannot be discovered. - 2: The device can be connected and discovered. (This constant is deprecated.)
BLUETOOTH_DISCOVER_TIMEOUT(deprecated21)	string	Yes	Duration for discovering a device through Bluetooth, in seconds. After the duration expires, the device cannot be discovered through Bluetooth. (This constant is deprecated.)
AIRPLANE_MODE_RADIOS(deprecated21)	string	Yes	List of radio signals to be disabled when airplane mode is enabled. Multiple radio signals are separated by commas (,). The list can include the following: BLUETOOTH_RADIO, CELL_RADIO, NFC_RADIO, and WIFI_RADIO. (This constant is deprecated.)
BLUETOOTH_RADIO(deprecated21)	string	Yes	A value of AIRPLANE_MODE_RADIOS, indicating that Bluetooth is disabled in airplane mode. (This constant is deprecated.)
CELL_RADIO(deprecated21)	string	Yes	A value of AIRPLANE_MODE_RADIOS, indicating that cellular radio is disabled in airplane mode. (This constant is deprecated.)
NFC_RADIO(deprecated21)	string	Yes	A value of AIRPLANE_MODE_RADIOS, indicating that NFC is disabled in airplane mode (This constant is deprecated.)
WIFI_RADIO(deprecated21)	string	Yes	A value of AIRPLANE_MODE_RADIOS, indicating that Wi-Fi is disabled in airplane mode (This constant is deprecated.)
BLUETOOTH_STATUS(deprecated21)	string	Yes	Whether Bluetooth is available. - true: Bluetooth is available. - false: Bluetooth is unavailable. (This constant is deprecated.)
OWNER_LOCKDOWN_WIFI_CFG(deprecated21)	string	Yes	Whether the Wi-Fi configuration created by the application of the device owner should be locked down. - true: The Wi-Fi configuration should be locked down. - false: The Wi-Fi configuration should not be locked down. (This constant is deprecated.)
WIFI_DHCP_MAX_RETRY_COUNT(deprecated21)	string	Yes	Maximum number of attempts to obtain an IP address from the DHCP server. (This constant is deprecated.)
WIFI_TO_MOBILE_DATA_AWAKE_TIMEOUT(deprecated21)	string	Yes	Maximum duration to hold a wake lock when waiting for the mobile data connection after the Wi-Fi connection is disconnected. (This constant is deprecated.)
WIFI_STATUS(deprecated21)	string	Yes	Whether Wi-Fi is available. - true: Wi-Fi is available. - false: Wi-Fi is unavailable. (This constant is deprecated.)
WIFI_WATCHDOG_STATUS(deprecated21)	string	Yes	Whether Wi-Fi watchdog is available. - true: Wi-Fi watchdog is available. - false: Wi-Fi watchdog is unavailable. (This constant is deprecated.)

settings.setValue¹⁰⁺

setValue(context: Context, name: string, value: string, callback: AsyncCallback<boolean>): void

Sets the value for a data item in the DEVICE_SHARED domain of the database. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Required permissions: ohos.permission.MANAGE_SETTINGS (available only to system applications)

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
value	string	Yes	Value of the data item. The value range varies by service.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. The value true means that the operation is successful, and false means the opposite.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValue API will update its value.)
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.setValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', (status) => {
  console.info('Callback return whether value is set.');
});

settings.setValue¹⁰⁺

setValue(context: Context, name: string, value: string): Promise<boolean>

Sets the value for a data item in the DEVICE_SHARED domain of the database. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Required permissions: ohos.permission.MANAGE_SETTINGS (available only to system applications)

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
value	string	Yes	Value of the data item. The value range varies by service.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the operation is successful, and false means the opposite.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValue API will update its value.)
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.setValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100').then((status) => {
  console.info('Callback return whether value is set.');
});

settings.setValue¹¹⁺

setValue(context: Context, name: string, value: string, domainName: string): Promise<boolean>

Sets the value for a data item. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Required permissions:

• ohos.permission.MANAGE_SETTINGS for writing the DEVICE_SHARED and USER_PROPERTY fields (available only to system applications);
• ohos.permission.MANAGE_SECURE_SETTINGS for writing the USER_SECURITY field (available only to system applications)

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
value	string	Yes	Value of the data item. The value range varies by service.
domainName	string	Yes	Domain name to set. - domainName.DEVICE_SHARED:    shared device domain - domainName.USER_PROPERTY:    user property domain - domainName.USER_SECURITY:    user security domain (for system applications only)

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the operation is successful, and false means the opposite.

Error codes

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

ID	Error Message
201	Permission denied.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValue API will update its value.)
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.setValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', settings.domainName.DEVICE_SHARED).then((status) => {
  console.info(`callback:return whether value is set.`)
});

settings.getValue¹⁰⁺

getValue(context: Context, name: string, callback: AsyncCallback<string>): void

Obtains the value of a data item in the DEVICE_SHARD domain of the database. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
callback	AsyncCallback<string>	Yes	Callback used to return the value of the data item.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.getValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, (err, value) => {
  if (err) {
    console.error(`Failed to get the setting. ${err.message} `);
    return;
  }
  console.info(`callback:value -> ${value}`)
});

settings.getValue¹⁰⁺

getValue(context: Context, name: string): Promise<string>

Obtains the value of a data item in the DEVICE_SHARD domain of the database. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items

Return value

Type	Description
Promise<string>	Promise used to return the result.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.getValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value) => {
  console.info(`promise:value -> ${value}`)
});

settings.getValue¹¹⁺

getValue(context: Context, name: string, domainName: string): Promise<string>

Obtains the value of a data item in the database. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Required permissions:

• ohos.permission.MANAGE_SECURE_SETTINGS for reading the USER_SECURITY field (available only to system applications)

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
domainName	string	Yes	Domain name to set. - domainName.DEVICE_SHARED:    shared device domain - domainName.USER_PROPERTY:    user property domain - domainName.USER_SECURITY:    user security domain (for system applications only)

Return value

Type	Description
Promise<string>	Promise used to return the result.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the getValue API will update its value.)
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.getValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, settings.domainName.DEVICE_SHARED).then((value) => {
  console.info(`Promise:value -> ${value}`);
});

settings.getValueSync¹⁰⁺

getValueSync(context: Context, name: string, defValue: string): string

Obtains the value of a data item in the DEVICE_SHARED domain of the database. Unlike getValue, this API returns the result synchronously.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
defValue	string	Yes	Default value, which is returned when the value of a data item is not found in the database. Set this parameter as needed.

Return value

Type	Description
string	Value of the data item.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the value of SCREEN_BRIGHTNESS_STATUS (this data item already exists in the database).
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let value = settings.getValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '10');

settings.getValueSync¹¹⁺

getValueSync(context: Context, name: string, defValue: string, domainName: string): string

Obtains the value of a data item. Unlike getValue, this API returns the result synchronously.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Required permissions:

• ohos.permission.MANAGE_SECURE_SETTINGS for reading the USER_SECURITY field (available only to system applications)

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
defValue	string	Yes	Default value, which is returned when the value of a data item is not found in the database. Set this parameter as needed.
domainName	string	Yes	Domain name to set. - domainName.DEVICE_SHARED:    shared device domain - domainName.USER_PROPERTY:    user property domain - domainName.USER_SECURITY:    user security domain (for system applications only)

Return value

Type	Description
string	Value of the data item.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Update the value of SCREEN_BRIGHTNESS_STATUS (this data item already exists in the database).
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let value = settings.getValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100',  settings.domainName.DEVICE_SHARED);

settings.setValueSync¹⁰⁺

setValueSync(context: Context, name: string, value: string): boolean

Sets the value for a data item in the DEVICE_SHARED domain of the database. Unlike setValue, this API returns the result synchronously.

• If the specified data item exists in the database, the setValueSync method updates the value of the data item.
• If the data item does not exist in the database, the setValueSync method inserts the data item into the database.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Required permissions: ohos.permission.MANAGE_SETTINGS (available only to system applications)

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
value	string	Yes	Value of the data item. The value range varies by service.

Return value

Type	Description
boolean	Result indicating whether the value is set successfully. Returns true if the operation is successful; returns false otherwise.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValueSync API will update its value.)
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let ret = settings.setValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100');

settings.setValueSync¹¹⁺

setValueSync(context: Context, name: string, value: string, domainName: string): boolean

Sets the value for a data item. Unlike setValue, this API returns the result synchronously.

• If the specified data item exists in the database, the setValueSync method updates the value of the data item.
• If the data item does not exist in the database, the setValueSync method inserts the data item into the database.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Required permissions:

• ohos.permission.MANAGE_SETTINGS for writing the DEVICE_SHARED and USER_PROPERTY fields (available only to system applications);
• ohos.permission.MANAGE_SECURE_SETTINGS for writing the USER_SECURITY field (available only to system applications)

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
value	string	Yes	Value of the data item. The value range varies by service.
domainName	string	Yes	Domain name to set. - domainName.DEVICE_SHARED:    shared device domain - domainName.USER_PROPERTY:    user property domain - domainName.USER_SECURITY:    user security domain (for system applications only)

Return value

Type	Description
boolean	Result indicating whether the value is set successfully. Returns true if the operation is successful; returns false otherwise.

Error codes

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

ID	Error Message
201	Permission denied.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValueSync API will update its value.)
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let ret = settings.setValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', settings.domainName.DEVICE_SHARED);

settings.registerKeyObserver¹¹⁺

registerKeyObserver(context: Context, name: string, domainName: string, observer:AsyncCallback<void>): boolean

Registers an observer in the specified context so that the specified data item can be observed in the specified domain name. When the data item value changes, the registered callback is called. Returns true if the operation is successful; returns false otherwise.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
domainName	string	Yes	Domain name to set. - domainName.DEVICE_SHARED:    shared device domain - domainName.USER_PROPERTY:    user property domain - domainName.USER_SECURITY:    user security domain (for system applications only)
observer	AsyncCallback<void>	Yes	Callback used to return the value of the data item.

Return value

Type	Description
boolean	Result indicating whether an observer is successfully registered. Returns true if the operation is successful; returns false otherwise.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.registerKeyObserver(context, settings.display.SCREEN_BRIGHTNESS_STATUS, settings.domainName.DEVICE_SHARED, () => {
  let value:string = settings.getValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '10');
  console.info(`Promise:value -> ${value}`);
});

settings.unregisterKeyObserver¹¹⁺

unregisterKeyObserver(context: Context, name: string, domainName: string): boolean

Unregisters the observer under the specified domain name. This API returns the result synchronously.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
domainName	string	Yes	Domain name to set. - domainName.DEVICE_SHARED:    shared device domain - domainName.USER_PROPERTY:    user property domain - domainName.USER_SECURITY:    user security domain (for system applications only)

Return value

Type	Description
boolean	Result indicating whether the observer under the specified domain name is successfully unregistered. Returns true if the operation is successful; returns false otherwise.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let ret = settings.unregisterKeyObserver(context, settings.display.SCREEN_BRIGHTNESS_STATUS,  settings.domainName.DEVICE_SHARED);

settings.openNetworkManagerSettings¹⁸⁺

openNetworkManagerSettings(context: Context): Promise<boolean>

Opens the WLAN settings window. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Applications.Settings.Core

Devices supported: This API can be called on phones, PCs/2-in-1 devices, and tablets.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the operation is successful, and false means the opposite.

Error codes

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

ID	Error Message
14800000	Parameter error.
14800010	Original service error.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Redirect to the network manager settings page.
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.openNetworkManagerSettings(context).then((status) => {
  console.info(`callback:return whether settings is open.`);
});

settings.enableAirplaneMode

enableAirplaneMode(enable: boolean, callback: AsyncCallback<void>): void

Enables or disables airplane mode. This API uses an asynchronous callback to return the result. (Not supported yet.)

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether airplane mode is enabled. The value true means that airplane mode is enabled, and false means the opposite.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let isEnabled :boolean = true;
settings.enableAirplaneMode(isEnabled, (err:Error) => {
    if (err) {
        console.error('Failed to enable AirplaneMode.');
        return;
    }
    console.info('Return true if enable.');
})

settings.enableAirplaneMode

enableAirplaneMode(enable: boolean): Promise<void>

Enables or disables airplane mode. This API uses a promise to return the result. (Not supported yet.)

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether airplane mode is enabled. The value true means that airplane mode is enabled, and false means the opposite.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let isEnabled :boolean = true;
settings.enableAirplaneMode(isEnabled).then(() => {
  console.info('Succeeded in enabling AirplaneMode.');
}).catch((err:Error) => {
  console.error(`Failed to enable AirplaneMode. Cause: ${err}`);
})

settings.canShowFloating

canShowFloating(callback: AsyncCallback<boolean>): void

Checks whether the application can be displayed in a floating window. This API uses an asynchronous callback to return the result. (Not supported yet.)

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. The value true means that the application can be displayed in a floating window, and false means the opposite.

Example

settings.canShowFloating((err:Error, status: boolean) => {
  if (err) {
    console.error(`Failed to Checks whether a specified application can show as float window ${err.message} `);
    return;
  }
  console.info('Checks whether a specified application can show as float window.');
});

settings.canShowFloating

canShowFloating(): Promise<boolean>

Checks whether the application can be displayed in a floating window. This API uses a promise to return the result. (Not supported yet.)

System capability: SystemCapability.Applications.Settings.Core

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the application can be displayed in a floating window, and false means the opposite.

Example

settings.canShowFloating().then((status:boolean) => {
    console.info('Checks whether a specified application can show as float window.');
});

settings.getUriSync⁸⁺

getUriSync(name: string): string

Obtains the URI of a data item. (Not supported yet.)

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items

Return value

Type	Description
string	URI of the data item.

Example

// Obtain the URI of a data item.
let uriVar:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);

settings.getURI^(deprecated)

getURI(name: string, callback: AsyncCallback<object>): void

Obtains the URI of a data item. This API uses an asynchronous callback to return the result. (Not supported yet.)

NOTE

This API is supported since API version 7 and deprecated since API version 9. No substitute API is provided.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
callback	AsyncCallback<object>	Yes	Callback used to return the result. Obtains the URI of a data item.

Example

settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS, (uri:string) => {
    console.info(`callback:uri -> ${JSON.stringify(uri)}`)
})

settings.getURI^(deprecated)

getURI(name: string): Promise<object>

Obtains the URI of a data item. This API uses a promise to return the result. (Not supported yet.)

NOTE

This API is supported since API version 7 and deprecated since API version 9. No substitute API is provided.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items

Return value

Type	Description
Promise<object>	Promise used to return the result.

Example

settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS).then((uri:string) => {
    console.info(`promise:uri -> ${JSON.stringify(uri)}`)
})

settings.getValue^(deprecated)

getValue(dataAbilityHelper: DataAbilityHelper, name: string, callback: AsyncCallback<object>): void

Obtains the value of a data item in the DEVICE_SHARD domain of the database. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use getValue() instead.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
dataAbilityHelper	DataAbilityHelper	Yes	DataAbilityHelper class.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
callback	AsyncCallback<object>	Yes	Callback used to return the value of the data item.

Example

import featureAbility from '@ohos.ability.featureAbility';

let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let helper = featureAbility.acquireDataAbilityHelper(uri);
settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, (err:Error, value:string) => {
    if (err) {
        console.error(`Failed to get the setting. ${err.message} `);
        return;
    }
    console.info(`callback:value -> ${JSON.stringify(value)}`)
});

settings.getValue^(deprecated)

getValue(dataAbilityHelper: DataAbilityHelper, name: string): Promise<object>

Obtains the value of a data item in the DEVICE_SHARD domain of the database. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use getValue() instead.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
dataAbilityHelper	DataAbilityHelper	Yes	DataAbilityHelper class.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items

Return value

Type	Description
Promise<object>	Promise used to return the result.

Example

import featureAbility from '@ohos.ability.featureAbility';

let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let helper = featureAbility.acquireDataAbilityHelper(uri);
settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value:string) => {
    console.info(`promise:value -> ${JSON.stringify(value)}`)
});

settings.getValueSync^(deprecated)

getValueSync(dataAbilityHelper: DataAbilityHelper, name: string, defValue: string): string

Obtains the value of a data item. Unlike getValue, this API returns the result synchronously.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getValueSync() instead.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
dataAbilityHelper	DataAbilityHelper	Yes	DataAbilityHelper class.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
defValue	string	Yes	Default value, which is returned when the value of a data item is not found in the database. Set this parameter as needed.

Return value

Type	Description
string	Value of the data item.

Example

import featureAbility from '@ohos.ability.featureAbility';

// Obtain the value of SCREEN_BRIGHTNESS_STATUS (this data item already exists in the database).
let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let helper = featureAbility.acquireDataAbilityHelper(uri);
let value:string = settings.getValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '10');

settings.setValueSync^(deprecated)

setValueSync(dataAbilityHelper: DataAbilityHelper, name: string, value: string): boolean

Sets the value for a data item. Unlike setValue, this API returns the result synchronously.

• If the specified data item exists in the database, the setValueSync method updates the value of the data item.
• If the data item does not exist in the database, the setValueSync method inserts the data item into the database.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use setValueSync() instead.

Model restriction: This API can be used only in the FA model.

Required permissions: ohos.permission.MANAGE_SETTINGS (available only to system applications)

System capability: SystemCapability.Applications.Settings.Core

Parameters

Name	Type	Mandatory	Description
dataAbilityHelper	DataAbilityHelper	Yes	DataAbilityHelper class.
name	string	Yes	Name of the target data item. Data items can be classified as follows: - Existing data items in the database - Custom data items
value	string	Yes	Value of the data item. The value range varies by service.

Return value

Type	Description
boolean	Result indicating whether the value is set successfully. Returns true if the operation is successful; returns false otherwise.

Example

import featureAbility from '@ohos.ability.featureAbility';

// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValueSync API will update its value.)
let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS);
let helper = featureAbility.acquireDataAbilityHelper(uri);
let ret:string = settings.setValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '100');

settings.openInputMethodSettings²³⁺

openInputMethodSettings(context: Context): void

Open the input method settings page.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones and tablets. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Error codes

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

ID	Error Message
16900010	Parameter error.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Go to the input method settings page.
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
settings.openInputMethodSettings(context);

settings.openInputMethodDetail²³⁺

openInputMethodDetail(context: Context, bundleName: string, inputMethodId: string): void

Opens the input method details page.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones and tablets. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
bundleName	string	Yes	Bundle name of the input method to be started.
inputMethodId	string	Yes	Unique ID of the input method extension in the application.

Error codes

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

ID	Error Message
16900010	Parameter error.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Go to the input method details page.
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let bundleName: string = "target inputMethod bundle name";
let inputMethodId: string = "target inputMethod id";
settings.openInputMethodDetail(context, bundleName, inputMethodId);

settings.openBiometricsSettingsPage²⁴⁺

openBiometricsSettingsPage(context: Context): void

Opens the biometric recognition and password settings page.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones, tablets, and PCs/2-in-1 devices. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Error codes

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

ID	Error Message
16900010	Parameter error.
16900020	Failed to open the settings page via redirection.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  settings.openBiometricsSettingsPage(context);
} catch (err) {
  console.error(`Failed to open the biometrics and password settings page. code: ${err?.code}, message: ${err?.message}`);
}

settings.openNfcSettingsPage²⁴⁺

openNfcSettingsPage(context: Context): void

Opens the NFC settings page.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones and tablets. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Error codes

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

ID	Error Message
16900010	Parameter error.
16900020	Failed to open the settings page via redirection.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  settings.openNfcSettingsPage(context);
} catch (err) {
  console.error(`Failed to open the NFC settings page. code: ${err?.code}, message: ${err?.message}`);
}

settings.openMobileNetworkSettingsPage

openMobileNetworkSettingsPage(context: Context): void

Opens the mobile network settings page.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones and tablets. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Error codes

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

ID	Error Message
16900010	Parameter error.
16900020	Failed to open the settings page via redirection.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  settings.openMobileNetworkSettingsPage(context);
} catch (err) {
  console.error(`Failed to open the mobile network settings page. code: ${err?.code}, message: ${err?.message}`);
}

settings.openDisplaySettingsPage

openDisplaySettingsPage(context: Context): void

Opens the display and brightness setting page.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones, tablets, and PCs/2-in-1 devices. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Error codes

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

ID	Error Message
16900010	Parameter error.
16900020	Failed to open the settings page via redirection.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  settings.openDisplaySettingsPage(context);
} catch (err) {
  console.error(`Failed to open the display settings page. code: ${err?.code}, message: ${err?.message}`);
}

settings.openScreenRefreshRateSettingsPage

openScreenRefreshRateSettingsPage(context: Context): void

Opens the screen refresh rate setting page.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones, tablets, and PCs/2-in-1 devices. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Error codes

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

ID	Error Message
16900010	Parameter error.
16900020	Failed to open the settings page via redirection.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  settings.openScreenRefreshRateSettingsPage(context);
} catch (err) {
  console.error(`Failed to open the screen refresh rate settings page. code: ${err?.code}, message: ${err?.message}`);
}

settings.openSoundSettingsPage

openSoundSettingsPage(context: Context): void

Opens the sound and vibration setting page.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones, tablets, and PCs/2-in-1 devices. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Error codes

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

ID	Error Message
16900010	Parameter error.
16900020	Failed to open the settings page via redirection.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  settings.openSoundSettingsPage(context);
} catch (err) {
  console.error(`Failed to open the sound settings page. code: ${err?.code}, message: ${err?.message}`);
}

settings.openAboutDeviceSettingsPage

openAboutDeviceSettingsPage(context: Context): void

Opens the about device setting page.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones, tablets, and PCs/2-in-1 devices. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.

Error codes

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

ID	Error Message
16900010	Parameter error.
16900020	Failed to open the settings page via redirection.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  settings.openAboutDeviceSettingsPage(context);
} catch (err) {
  console.error(`Failed to open the about device settings page. code: ${err?.code}, message: ${err?.message}`);
}

settings.openAppDetailSettingsPage

openAppDetailSettingsPage(context: Context, bundleName: string, appIndex?: int): void

Opens the application details setting page.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Applications.Settings.Core

Device behavior differences: This API can be properly called on phones, tablets, and PCs/2-in-1 devices. If it is called on other device types, it has no effect.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. Only UIAbilityContext and ExtensionContext are supported. For details about the application context of the stage model, see Context.
bundleName	string	Yes	Bundle name.
appIndex	int	No	Index of an application clone.

Error codes

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

ID	Error Message
16900010	Parameter error.
16900020	Failed to open the settings page via redirection.

Example

import { settings } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  settings.openAppDetailSettingsPage(context, 'com.example');
} catch (err) {
  console.error(`Failed to open the app detail settings page. code: ${err?.code}, message: ${err?.message}`);
}