1# @ohos.settings (Data Item Settings) 2 3The **settings** module provides APIs for setting data items. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```js 12import settings from '@ohos.settings'; 13``` 14 15## date 16 17Provides data items for setting the time and date formats. 18 19### Attributes 20 21**System capability**: SystemCapability.Applications.settings.Core 22 23| Name | Type | Readable| Writable| Description | 24| ------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 25| DATE_FORMAT | string | Yes | Yes | Date format.<br>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.| 26| TIME_FORMAT | string | Yes | Yes | Time format.<br>**12**: 12-hour format.<br>**24**: 24-hour format.| 27| AUTO_GAIN_TIME | string | Yes | Yes | Whether the date, time, and time zone are automatically obtained from the Network Identity and Time Zone (NITZ).<br>The value **true** means that the date, time, and time zone are automatically obtained from NITZ;<br>and **false** means the opposite.| 28| AUTO_GAIN_TIME_ZONE | string | Yes | Yes | Whether the time zone is automatically obtained from NITZ.<br>The value **true** means that the time zone is automatically obtained from NITZ;<br>and **false** means the opposite.| 29 30## display 31 32Provides data items for setting the display effects. 33 34### Attributes 35 36**System capability**: SystemCapability.Applications.settings.Core 37 38| Name | Type | Readable| Writable| Description | 39| ----------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 40| FONT_SCALE | string | Yes | Yes | Scale factor of the font. The value is a floating point number. | 41| SCREEN_BRIGHTNESS_STATUS | string | Yes | Yes | Screen brightness. The value ranges from 0 to 255. | 42| AUTO_SCREEN_BRIGHTNESS | string | Yes | Yes | Whether automatic screen brightness adjustment is enabled.<br>**AUTO_SCREEN_BRIGHTNESS_MODE**: Automatic screen brightness adjustment is enabled.<br><br>**MANUAL_SCREEN_BRIGHTNESS_MODE**: Automatic screen brightness adjustment is disabled.| 43| AUTO_SCREEN_BRIGHTNESS_MODE | number | Yes | Yes | Value of **AUTO_SCREEN_BRIGHTNESS** when automatic screen brightness adjustment is enabled. | 44| MANUAL_SCREEN_BRIGHTNESS_MODE | number | Yes | Yes | Value of **AUTO_SCREEN_BRIGHTNESS** when automatic screen brightness adjustment is disabled. | 45| SCREEN_OFF_TIMEOUT | string | Yes | Yes | Waiting time for the device to enter the sleep state when not in use (unit: ms). | 46| DEFAULT_SCREEN_ROTATION | string | Yes | Yes | Rotation angle. This attribute is valid only when screen auto-rotation is disabled.<br>**0**: The screen rotates by 0 degrees.<br>**1**: The screen rotates by 90 degrees.<br>**2**: The screen rotates by 180 degrees.<br>**3**: The screen rotates by 270 degrees.| 47| ANIMATOR_DURATION_SCALE | string | Yes | Yes | Scale factor for the animation duration. This affects the start delay and duration of all such animations.<br>If the value is **0**, the animation ends immediately. The default value is **1**.| 48| TRANSITION_ANIMATION_SCALE | string | Yes | Yes | Scale factor for transition animations.<br>The value **0** indicates that the transition animations are disabled. | 49| WINDOW_ANIMATION_SCALE | string | Yes | Yes | Scale factor for normal window animations.<br>The value **0** indicates that window animations are disabled. | 50| DISPLAY_INVERSION_STATUS | string | Yes | Yes | Whether display color inversion is enabled.<br>**1**: Display color inversion is enabled.<br><br>**0**: Display color inversion is disabled.| 51 52## general 53 54Provides data items for setting the general information about the device. 55 56### Attributes 57 58**System capability**: SystemCapability.Applications.settings.Core 59 60| Name | Type | Readable| Writable| Description | 61| -------------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 62| SETUP_WIZARD_FINISHED | string | Yes | Yes | Whether the startup wizard is running.<br>If the value is **0**, the startup wizard is not running.<br>If the value is not **0**, the startup wizard is running.| 63| END_BUTTON_ACTION | string | Yes | Yes | Action after the call end button is pressed if the user is not in a call.<br>**0**: Nothing happens.<br>**1**: The home screen is displayed.<br>**2**: The device enters sleep mode and the screen is locked.<br>**3**: The home screen is displayed. If the focus is already on the home screen, the device will enter sleep mode.| 64| ACCELEROMETER_ROTATION_STATUS | string | Yes | Yes | Whether the accelerometer is used to change screen orientation, that is, whether to enable auto-rotation.<br>**1**: The accelerometer is used.<br>**0**: The accelerometer is not used.| 65| AIRPLANE_MODE_STATUS | string | Yes | Yes | Whether airplane mode is enabled.<br>**1**: Airplane mode is enabled.<br>**0**: Airplane mode is disabled.| 66| DEVICE_PROVISION_STATUS | string | Yes | Yes | Whether the device is preconfigured.<br>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.| 67| HDC_STATUS | string | Yes | Yes | Whether the hard disk controller (HDC) on the USB device is enabled.<br>**true**: HDC is enabled.<br>**false**: HDC is disabled.| 68| BOOT_COUNTING | string | Yes | Yes | Number of boot operations after the device is powered on. | 69| CONTACT_METADATA_SYNC_STATUS | string | Yes | Yes | Whether contacts metadata synchronization is enabled.<br>**true**: Contacts metadata synchronization is enabled.<br>**false**: Contacts metadata synchronization is disabled.| 70| DEVELOPMENT_SETTINGS_STATUS | string | Yes | Yes | Whether developer options are enabled.<br>**true**: Developer options are enabled.<br>**false**: Developer options are disabled.| 71| DEVICE_NAME | string | Yes | Yes | Device name. | 72| USB_STORAGE_STATUS | string | Yes | Yes | Whether USB mass storage is enabled.<br>**true**: USB mass storage is enabled.<br>**false**: USB mass storage is disabled.| 73| DEBUGGER_WAITING | string | Yes | Yes | Whether the device waits for the debugger when starting an application to debug.<br>**1**: The device waits for the debugger.<br>**0**: The device does not wait for the debugger. In this case, the application runs normally.| 74| DEBUG_APP_PACKAGE | string | Yes | Yes | Bundle name of the application to be debugged. | 75| ACCESSIBILITY_STATUS | string | Yes | Yes | Whether accessibility is enabled.<br>**1**: Accessibility is enabled.<br>**0**: Accessibility is disabled.| 76| ACTIVATED_ACCESSIBILITY_SERVICES | string | Yes | Yes | List of activated accessibility features. | 77| GEOLOCATION_ORIGINS_ALLOWED | string | Yes | Yes | Default geographic location that can be used by the browser. Multiple geographic locations are separated by spaces. | 78| SKIP_USE_HINTS | string | Yes | Yes | Whether the application should attempt to skip all introductory hints at the first startup. This feature is intended for temporary or experienced users.<br>**1**: The application attempts to skip all introductory hints at the first startup.<br>**0**: The application does not skip all introductory hints at the first startup.| 79| TOUCH_EXPLORATION_STATUS | string | Yes | Yes | Whether touch exploration is enabled.<br>**1**: Touch exploration is enabled.<br>**0**: Touch exploration is disabled.| 80 81## input 82 83Provides data items for setting input methods. 84 85### Attributes 86 87**System capability**: SystemCapability.Applications.settings.Core 88 89| Name | Type | Readable| Writable| Description | 90| ------------------------------------ | ------ | ---- | ---- | ------------------------------------------------------------ | 91| DEFAULT_INPUT_METHOD | string | Yes | Yes | Default input method and its ID. | 92| ACTIVATED_INPUT_METHOD_SUB_MODE | string | Yes | Yes | Type and ID of the default input method keyboard. | 93| ACTIVATED_INPUT_METHODS | string | Yes | Yes | List of activated input methods.<br>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.| 94| SELECTOR_VISIBILITY_FOR_INPUT_METHOD | string | Yes | Yes | Whether the input method selector is visible.<br>**1**: The input method selector is visible.<br>**0**: The input method selector is invisible.| 95| AUTO_CAPS_TEXT_INPUT | string | Yes | Yes | Whether automatic capitalization is enabled for the text editor.<br>**0**: Automatic capitalization is disabled.<br>**1**: Automatic capitalization is enabled.| 96| AUTO_PUNCTUATE_TEXT_INPUT | string | Yes | 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.<br>**0**: Automatic punctuation is disabled.<br>**1**: Automatic punctuation is enabled.| 97| AUTO_REPLACE_TEXT_INPUT | string | Yes | Yes | Whether autocorrect is enabled for the text editor. Autocorrect enables the text editor to correct typos.<br>**0**: Autocorrect is disabled.<br>**1**: Autocorrect is enabled | 98| SHOW_PASSWORD_TEXT_INPUT | string | Yes | 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.<br>**0**: Password presentation is disabled.<br>**1**: Password presentation is enabled.| 99 100## network 101 102Provides data items for setting network information. 103 104### Attributes 105 106**System capability**: SystemCapability.Applications.settings.Core 107 108| Name | Type | Readable| Writable| Description | 109| ------------------------ | ------ | ---- | ---- | ------------------------------------------------------------ | 110| DATA_ROAMING_STATUS | string | Yes | Yes | Whether data roaming is enabled.<br>**true**: Data roaming is enabled.<br>**false**: Data roaming is disabled.| 111| HTTP_PROXY_CFG | string | Yes | Yes | Host name and port number of the global HTTP proxy. The host name and port number are separated by a colon (:).| 112| NETWORK_PREFERENCE_USAGE | string | Yes | Yes | User preferences for the network to use. | 113 114## phone 115 116Provides data items for setting the modes of answering incoming and outgoing calls. 117 118### Attributes 119 120**System capability**: SystemCapability.Applications.settings.Core 121 122| Name | Type | Readable| Writable| Description | 123| ------------------ | ------ | ---- | ---- | ------------------------------------------------------------ | 124| RTT_CALLING_STATUS | string | Yes | Yes | Whether the real-time text (RTT) feature is enabled. If this feature is enabled, incoming and outgoing calls are answered as RTT calls when supported by the device and carrier.<br> **1**: RTT is enabled.<br> **0**: RTT is disabled.| 125 126## sound 127 128Provides data items for setting the sound effects. 129 130### Attributes 131 132**System capability**: SystemCapability.Applications.settings.Core 133 134| Name | Type | Readable| Writable| Description | 135| ---------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 136| VIBRATE_WHILE_RINGING | string | Yes | Yes | Whether the device vibrates when it is ringing for an incoming call. This attribute 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.| 137| DEFAULT_ALARM_ALERT | string | Yes | Yes | Storage area of the system default alarms and alerts. | 138| DTMF_TONE_TYPE_WHILE_DIALING | string | Yes | Yes | Type of the dual tone multi-frequency (DTMF) tone played while dialing.<br>**0**: normal short tone.<br>**1**: long tone.| 139| DTMF_TONE_WHILE_DIALING | string | Yes | Yes | Whether the DTMF tone is played when dialing.<br>**1**: DTMF tone is played when dialing.<br>**0**: DTMF tone is not played when dialing.| 140| AFFECTED_MODE_RINGER_STREAMS | string | Yes | Yes | Which audio streams are affected by changes on 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 DDN mode, set the corresponding bit to **1**.| 141| AFFECTED_MUTE_STREAMS | string | Yes | 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**.| 142| DEFAULT_NOTIFICATION_SOUND | string | Yes | Yes | Storage area of the system default notification tone. | 143| DEFAULT_RINGTONE | string | Yes | Yes | Storage area of the system default ringtone. | 144| SOUND_EFFECTS_STATUS | string | Yes | Yes | Whether the sound feature is available.<br>**0**: The feature is not available.<br>**1**: The feature is available. | 145| VIBRATE_STATUS | string | Yes | Yes | Whether the device vibrates for an event. This attribute is used inside the system.<br>**1**: The device vibrates for an event.<br>**0**: The device does not vibrate for an event.| 146| HAPTIC_FEEDBACK_STATUS | string | Yes | Yes | Whether haptic feedback is enabled.<br>**true**: Haptic feedback is enabled.<br>**false**: Haptic feedback is disabled.| 147 148## TTS 149 150Provides data items for setting text-to-speech (TTS) information. 151 152### Attributes 153 154**System capability**: SystemCapability.Applications.settings.Core 155 156| Name | Type | Readable| Writable| Description | 157| ------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 158| DEFAULT_TTS_PITCH | string | Yes | Yes | Default pitch of the TTS engine.<br>100 = 1x. If the value is set to **200**, the frequency is twice the normal sound frequency.| 159| DEFAULT_TTS_RATE | string | Yes | Yes | Default voice rate of the TTS engine.<br>100 = 1x. | 160| DEFAULT_TTS_SYNTH | string | Yes | Yes | Default TTS engine. | 161| ENABLED_TTS_PLUGINS | string | Yes | Yes | List of activated plug-in packages used for TTS. Multiple plug-in packages are separated by spaces. | 162 163 164## wireless 165 166Provides data items for setting wireless network information. 167 168### Attributes 169 170**System capability**: SystemCapability.Applications.settings.Core 171 172| Name | Type | Readable| Writable| Description | 173| --------------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 174| BLUETOOTH_DISCOVER_ABILITY_STATUS | string | Yes | Yes | Whether the device can be discovered or connected by other devices through Bluetooth.<br>**0**: The device cannot be discovered or connected.<br>**1**: The device can be connected but cannot be discovered.<br>**2**: The device can be discovered and connected.| 175| BLUETOOTH_DISCOVER_TIMEOUT | string | Yes | Yes | Duration for discovering a device through Bluetooth, in seconds.<br>After the duration expires, the device cannot be discovered through Bluetooth.| 176| AIRPLANE_MODE_RADIOS | string | Yes | Yes | List of radio signals to be disabled when airplane mode is enabled.<br>Multiple radio signals are separated by commas (,). The list can include the following: **BLUETOOTH_RADIO**, **CELL_RADIO**, **NFC_RADIO**, and **WIFI_RADIO**.| 177| BLUETOOTH_RADIO | string | Yes | No | A value of **AIRPLANE_MODE_RADIOS** to indicate that Bluetooth is disabled in airplane mode.| 178| CELL_RADIO | string | Yes | No | A value of **AIRPLANE_MODE_RADIOS** to indicate that cellular radio is disabled in airplane mode.| 179| NFC_RADIO | string | Yes | No | A value of **AIRPLANE_MODE_RADIOS** to indicate that NFC is disabled in airplane mode.| 180| WIFI_RADIO | string | Yes | No | A value of **AIRPLANE_MODE_RADIOS** to indicate that Wi-Fi is disabled in airplane mode.| 181| BLUETOOTH_STATUS | string | Yes | Yes | Whether Bluetooth is available.<br>**true**: Bluetooth is available.<br>**false**: Bluetooth is unavailable.| 182| OWNER_LOCKDOWN_WIFI_CFG | string | Yes | Yes | Whether the Wi-Fi configuration created by the application of the device owner should be locked down.<br>**true**: The Wi-Fi configuration should be locked down.<br>**false**: The Wi-Fi configuration should not be locked down.| 183| WIFI_DHCP_MAX_RETRY_COUNT | string | Yes | Yes | Maximum number of attempts to obtain an IP address from the DHCP server. | 184| WIFI_TO_MOBILE_DATA_AWAKE_TIMEOUT | string | Yes | Yes | Maximum duration to hold a wake lock when waiting for the mobile data connection to establish after the Wi-Fi connection is disconnected. | 185| WIFI_STATUS | string | Yes | Yes | Whether Wi-Fi is available.<br>**true**: Wi-Fi is available.<br>**false**: Wi-Fi is unavailable.| 186| WIFI_WATCHDOG_STATUS | string | Yes | Yes | Whether Wi-Fi watchdog is available.<br>**true**: Wi-Fi watchdog is available.<br>**false**: Wi-Fi watchdog is unavailable.| 187 188 189## settings.setValue<sup>10+</sup> 190 191setValue(context: Context, name: string, value: string, callback: AsyncCallback\<boolean>): void 192 193Sets the value for a data item. This API uses an asynchronous callback to return the result. 194 195**Model restriction**: This API can be used only in the stage model. 196 197**System capability**: SystemCapability.Applications.settings.Core 198 199**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS 200 201**Parameters** 202 203| Name | Type | Mandatory| Description | 204| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 205| context | Context | Yes | Application context.<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).| 206| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 207| value | string | Yes | Value of the data item. The value range varies by service. | 208| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. Returns **true** if the operation is successful; returns **false** otherwise. | 209 210**Example** 211 212```js 213import settings from '@ohos.settings'; 214 215// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValue API will update its value.) 216settings.setValue(this.context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', (status) => { 217 console.log('Callback return whether value is set.'); 218}); 219``` 220 221## settings.setValue<sup>10+</sup> 222 223setValue(context: Context, name: string, value: string): Promise\<boolean> 224 225Sets the value for a data item. This API uses a promise to return the result. 226 227**Model restriction**: This API can be used only in the stage model. 228 229**System capability**: SystemCapability.Applications.settings.Core 230 231**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS 232 233**Parameters** 234 235| Name | Type | Mandatory| Description | 236| ------- | ------- | ---- | ------------------------------------------------------------ | 237| context | Context | Yes | Application context.<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).| 238| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 239| value | string | Yes | Value of the data item. The value range varies by service. | 240 241**Return value** 242 243| Type | Description | 244| ----------------- | -------------------------------------------------- | 245| Promise\<boolean> | Promise used to return the result. Returns **true** if the operation is successful; returns **false** otherwise.| 246 247**Example** 248 249```js 250import settings from '@ohos.settings'; 251 252// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValue API will update its value.) 253settings.setValue(this.context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100').then((status) => { 254 console.log('Callback return whether value is set.'); 255}); 256``` 257 258## setting.getValue<sup>10+</sup> 259 260getValue(context: Context, name: string, callback: AsyncCallback\<string>): void 261 262Obtains the value of a data item in the database. This API uses an asynchronous callback to return the result. 263 264**Model restriction**: This API can be used only in the stage model. 265 266**System capability**: SystemCapability.Applications.settings.Core 267 268**Parameters** 269 270| Name | Type | Mandatory| Description | 271| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 272| context | Context | Yes | Application context.<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).| 273| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br> - Existing data items in the database<br>- Custom data items| 274| callback | AsyncCallback\<string> | Yes | Callback used to return the value of the data item. | 275 276**Example** 277 278```js 279import settings from '@ohos.settings'; 280 281settings.getValue(this.context, settings.display.SCREEN_BRIGHTNESS_STATUS, (err, value) => { 282 if (err) { 283 console.error(`Failed to get the setting. ${err.message} `); 284 return; 285 } 286 console.log(`callback:value -> ${JSON.stringify(value)}`) 287}); 288``` 289 290## setting.getValue<sup>10+</sup> 291 292getValue(context: Context, name: string): Promise\<string> 293 294Obtains the value of a data item in the database. This API uses a promise to return the result. 295 296**Model restriction**: This API can be used only in the stage model. 297 298**System capability**: SystemCapability.Applications.settings.Core 299 300**Parameters** 301 302| Name | Type | Mandatory| Description | 303| ------- | ------- | ---- | ------------------------------------------------------------ | 304| context | Context | Yes | Application context.<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).| 305| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br> - Existing data items in the database<br>- Custom data items| 306 307**Return value** 308 309| Type | Description | 310| ---------------- | ----------------------------------- | 311| Promise\<string> | Promise used to return the value of the data item.| 312 313**Example** 314 315```js 316import settings from '@ohos.settings'; 317 318settings.getValue(this.context, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value) => { 319 console.log(`promise:value -> ${JSON.stringify(value)}`) 320}); 321``` 322 323## settings.getValueSync<sup>10+</sup> 324 325getValueSync(context: Context, name: string, defValue: string): string; 326 327Obtains the value of a data item. Unlike **getValue**, this API returns the result synchronously. 328 329**Model restriction**: This API can be used only in the stage model. 330 331**System capability**: SystemCapability.Applications.settings.Core 332 333**Parameters** 334 335| Name | Type | Mandatory| Description | 336| -------- | ------- | ---- | ------------------------------------------------------------ | 337| context | Context | Yes | Application context.<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).| 338| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 339| 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.| 340 341**Return value** 342 343| Type | Description | 344| ------ | ---------------- | 345| string | Value of the data item.| 346 347**Example** 348 349```js 350import settings from '@ohos.settings'; 351 352// Obtain the value of SCREEN_BRIGHTNESS_STATUS (this data item already exists in the database). 353let value = settings.getValueSync(this.context, settings.display.SCREEN_BRIGHTNESS_STATUS, '10'); 354``` 355 356## settings.setValueSync<sup>10+</sup> 357 358setValueSync(context: Context, name: string, value: string): boolean 359 360Sets the value for a data item. Unlike **setValue**, this API returns the result synchronously. 361 362If 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. 363 364**Model restriction**: This API can be used only in the stage model. 365 366**System capability**: SystemCapability.Applications.settings.Core 367 368**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS 369 370**Parameters** 371 372| Name | Type | Mandatory| Description | 373| ------- | ------- | ---- | ------------------------------------------------------------ | 374| context | Context | Yes | Application context.<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-context.md).| 375| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 376| value | string | Yes | Value of the data item. The value range varies by service. | 377 378**Return value** 379 380| Type | Description | 381| ------- | ------------------------------------------------------------ | 382| boolean | Result indicating whether the value is set successfully. Returns **true** if the value is set successfully; returns **false** otherwise.| 383 384**Example** 385 386```js 387import settings from '@ohos.settings'; 388 389// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValueSync API will update the value of the data item.) 390let ret = settings.setValueSync(this.context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100'); 391``` 392 393## settings.enableAirplaneMode 394 395enableAirplaneMode(enable: boolean, callback: AsyncCallback\<void>): void 396 397Enables or disables airplane mode. This API uses an asynchronous callback to return the result. 398 399This API is not supported currently. 400 401**System capability**: SystemCapability.Applications.settings.Core 402 403**Parameters** 404 405| Name | Type | Mandatory| Description | 406| -------- | -------------------- | ---- | ----------------------------------------------- | 407| enable | boolean | Yes | Whether airplane mode is enabled. **true** means that airplane mode is enabled, and **false** means the opposite.| 408| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 409 410**Example** 411 412```js 413let isEnabled :boolean = true; 414settings.enableAirplaneMode(isEnabled, (err:Error) => { 415 if (err) { 416 console.log('Failed to enable AirplaneMode.'); 417 return; 418 } 419 console.log('Return true if enable.'); 420}) 421``` 422 423## settings.enableAirplaneMode 424 425enableAirplaneMode(enable: boolean): Promise\<void> 426 427Enables or disables airplane mode. This API uses a promise to return the result. 428 429This API is not supported currently. 430 431**System capability**: SystemCapability.Applications.settings.Core 432 433**Parameters** 434 435| Name| Type | Mandatory| Description | 436| ------ | ------- | ---- | ----------------------------------------------- | 437| enable | boolean | Yes | Whether airplane mode is enabled. **true** means that airplane mode is enabled, and **false** means the opposite.| 438 439**Return value** 440 441| Type | Description | 442| -------------- | ------------------------- | 443| Promise\<void> | Promise that returns no value.| 444 445**Example** 446 447```js 448let isEnabled :boolean = true; 449settings.enableAirplaneMode(isEnabled).then(() => { 450 console.log('Succeeded in enabling AirplaneMode.'); 451}).catch((err:Error) => { 452 console.log(`Failed to enable AirplaneMode. Cause: ${err}`); 453}) 454``` 455 456## settings.canShowFloating 457 458canShowFloating(callback: AsyncCallback\<boolean>): void 459 460Checks whether the application can be displayed in a floating window. This API uses an asynchronous callback to return the result. 461 462**System capability**: SystemCapability.Applications.settings.Core 463 464**Parameters** 465 466| Name | Type | Mandatory| Description | 467| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 468| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>Returns **true** if the application can be displayed in a floating window; returns **false** otherwise.| 469 470**Example** 471 472```js 473settings.canShowFloating((status:boolean) => { 474 console.log('Checks whether a specified application can show as float window.'); 475}); 476``` 477 478## settings.canShowFloating 479 480canShowFloating(): Promise\<boolean> 481 482Checks whether the application can be displayed in a floating window. This API uses a promise to return the result. 483 484**System capability**: SystemCapability.Applications.settings.Core 485 486**Return value** 487 488| Type | Description | 489| ----------------- | ------------------------------------------------------------ | 490| Promise\<boolean> | Promise used to return the result.<br>Returns **true** if the application can be displayed in a floating window; returns **false** otherwise.| 491 492**Example** 493 494```js 495settings.canShowFloating().then((status:boolean) => { 496 console.log('Checks whether a specified application can show as float window.'); 497}); 498``` 499 500## settings.getUriSync<sup>8+</sup> 501 502getUriSync(name: string): string 503 504Obtains the URI of a data item. 505 506**System capability**: SystemCapability.Applications.settings.Core 507 508**Parameters** 509 510| Name| Type | Mandatory| Description | 511| ------ | ------ | ---- | ------------------------------------------------------------ | 512| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 513 514**Return value** 515 516| Type | Description | 517| ------ | ------------- | 518| string | URI of the data item.| 519 520**Example** 521 522```js 523// Obtain the URI of a data item. 524let uriVar:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 525``` 526 527## setting.getURI<sup>(deprecated)</sup> 528 529getURI(name: string, callback: AsyncCallback\<object>): void 530 531Obtains the URI of a data item. This API uses an asynchronous callback to return the result. 532 533> **NOTE** 534> 535> This API is supported since API version 7 and deprecated since API version 9. No substitute API is provided. 536 537**System capability**: SystemCapability.Applications.settings.Core 538 539**Parameters** 540 541| Name | Type | Mandatory| Description | 542| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 543| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 544| callback | AsyncCallback\<object> | Yes | Callback used to obtain the URI of the data item. | 545 546**Example** 547 548```js 549settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS, (uri:string) => { 550 console.log(`callback:uri -> ${JSON.stringify(uri)}`) 551}) 552``` 553 554## setting.getURI<sup>(deprecated)</sup> 555 556getURI(name: string): Promise\<object> 557 558Obtains the URI of a data item. This API uses a promise to return the result. 559 560> **NOTE** 561> 562> This API is supported since API version 7 and deprecated since API version 9. No substitute API is provided. 563 564**System capability**: SystemCapability.Applications.settings.Core 565 566**Parameters** 567 568| Name| Type | Mandatory| Description | 569| ------ | ------ | ---- | ------------------------------------------------------------ | 570| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 571 572**Return value** 573 574| Type | Description | 575| ---------------- | ------------------------------------ | 576| Promise\<object> | Promise used to return the URI of the data item.| 577 578**Example** 579 580```js 581settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS).then((uri:string) => { 582 console.log(`promise:uri -> ${JSON.stringify(uri)}`) 583}) 584``` 585 586## settings.setValue<sup>(deprecated)</sup> 587 588setValue(dataAbilityHelper: DataAbilityHelper, name: string, value: object, callback: AsyncCallback\<boolean>): void 589 590Sets the value for a data item. This API uses an asynchronous callback to return the result. 591 592> **NOTE** 593> 594> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setValue()](#settingssetvalue10) instead. 595 596**System API**: This is a system API. 597 598**Model restriction**: This API can be used only in the FA model. 599 600**System capability**: SystemCapability.Applications.settings.Core 601 602**Parameters** 603 604| Name | Type | Mandatory| Description | 605| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 606| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. | 607| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 608| value | object | Yes | Value of the data item. The value range varies by service. | 609| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. Returns **true** if the operation is successful; returns **false** otherwise. | 610 611 612## settings.setValue<sup>(deprecated)</sup> 613 614setValue(dataAbilityHelper: DataAbilityHelper, name: string, value: object): Promise\<boolean> 615 616Sets the value for a data item. This API uses a promise to return the result. 617 618> **NOTE** 619> 620> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setValue()](#settingssetvalue10-1) instead. 621 622**System API**: This is a system API. 623 624**Model restriction**: This API can be used only in the FA model. 625 626**System capability**: SystemCapability.Applications.settings.Core 627 628**Parameters** 629 630| Name | Type | Mandatory| Description | 631| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 632| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. | 633| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 634| value | object | Yes | Value of the data item. The value range varies by service. | 635 636**Return value** 637 638| Type | Description | 639| ----------------- | -------------------------------------------------- | 640| Promise\<boolean> | Promise used to return the result. Returns **true** if the operation is successful; returns **false** otherwise.| 641 642## setting.getValue<sup>(deprecated)</sup> 643 644getValue(dataAbilityHelper: DataAbilityHelper, name: string, callback: AsyncCallback\<object>): void 645 646Obtains the value of a data item in the database. This API uses an asynchronous callback to return the result. 647 648> **NOTE** 649> 650> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getValue()](#settinggetvalue10) instead. 651 652**Model restriction**: This API can be used only in the FA model. 653 654**System capability**: SystemCapability.Applications.settings.Core 655 656**Parameters** 657 658| Name | Type | Mandatory| Description | 659| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 660| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. | 661| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br> - Existing data items in the database<br>- Custom data items| 662| callback | AsyncCallback\<object> | Yes | Callback used to return the value of the data item. | 663 664**Example** 665 666```js 667import featureAbility from '@ohos.ability.featureAbility'; 668 669let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 670let helper = featureAbility.acquireDataAbilityHelper(uri); 671settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, (err:Error, value:string) => { 672 if (err) { 673 console.error(`Failed to get the setting. ${err.message} `); 674 return; 675 } 676 console.log(`callback:value -> ${JSON.stringify(value)}`) 677}); 678``` 679 680## setting.getValue<sup>(deprecated)</sup> 681 682getValue(dataAbilityHelper: DataAbilityHelper, name: string): Promise\<object> 683 684Obtains the value of a data item in the database. This API uses a promise to return the result. 685 686> **NOTE** 687> 688> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getValue()](#settinggetvalue10-1) instead. 689 690**Model restriction**: This API can be used only in the FA model. 691 692**System capability**: SystemCapability.Applications.settings.Core 693 694**Parameters** 695 696| Name | Type | Mandatory| Description | 697| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 698| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. | 699| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br> - Existing data items in the database<br>- Custom data items| 700 701**Return value** 702 703| Type | Description | 704| ---------------- | ----------------------------------- | 705| Promise\<object> | Promise used to return the value of the data item.| 706 707**Example** 708 709```js 710import featureAbility from '@ohos.ability.featureAbility'; 711 712let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 713let helper = featureAbility.acquireDataAbilityHelper(uri); 714settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value:string) => { 715 console.log(`promise:value -> ${JSON.stringify(value)}`) 716}); 717``` 718 719## settings.getValueSync<sup>(deprecated)</sup> 720 721getValueSync(dataAbilityHelper: DataAbilityHelper, name: string, defValue: string): string 722 723Obtains the value of a data item. Unlike **getValue**, this API returns the result synchronously. 724 725> **NOTE** 726> 727> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getValueSync()](#settingsgetvaluesync10) instead. 728 729**Model restriction**: This API can be used only in the FA model. 730 731**System capability**: SystemCapability.Applications.settings.Core 732 733**Parameters** 734 735| Name | Type | Mandatory| Description | 736| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 737| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. | 738| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 739| 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.| 740 741**Return value** 742 743| Type | Description | 744| ------ | ---------------- | 745| string | Value of the data item.| 746 747**Example** 748 749```js 750import featureAbility from '@ohos.ability.featureAbility'; 751 752// Obtain the value of SCREEN_BRIGHTNESS_STATUS (this data item already exists in the database). 753let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 754let helper = featureAbility.acquireDataAbilityHelper(uri); 755let value:string = settings.getValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '10'); 756``` 757 758## settings.setValueSync<sup>(deprecated)</sup> 759 760setValueSync(dataAbilityHelper: DataAbilityHelper, name: string, value: string): boolean 761 762Sets the value for a data item. Unlike **setValue**, this API returns the result synchronously. 763 764If 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. 765 766> **NOTE** 767> 768> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setValueSync()](#settingssetvaluesync10) instead. 769 770**Model restriction**: This API can be used only in the FA model. 771 772**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS (available only to system applications) 773 774**System capability**: SystemCapability.Applications.settings.Core 775 776**Parameters** 777 778| Name | Type | Mandatory| Description | 779| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 780| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | Yes | **DataAbilityHelper** class. | 781| name | string | Yes | Name of the target data item. Data items can be classified as follows:<br>- Existing data items in the database<br>- Custom data items| 782| value | string | Yes | Value of the data item. The value range varies by service. | 783 784**Return value** 785 786| Type | Description | 787| ------- | ------------------------------------------------------------ | 788| boolean | Result indicating whether the value is set successfully. Returns **true** if the value is set successfully; returns **false** otherwise.| 789 790**Example** 791 792```js 793import featureAbility from '@ohos.ability.featureAbility'; 794 795// Update the value of SCREEN_BRIGHTNESS_STATUS. (As this data item exists in the database, the setValueSync API will update the value of the data item.) 796let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 797let helper = featureAbility.acquireDataAbilityHelper(uri); 798let ret:string = settings.setValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '100'); 799``` 800