1# @ohos.settings (设置数据项名称) 2 3本模块提供访问设置数据项的能力。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - 如果访问的数据项没有获取到值，表示当前系统应用没有将该数据项的值添加到数据库。 10 11## 导入模块 12 13```js 14import settings from '@ohos.settings'; 15``` 16## domainName 17 18提供查询的域名。 19 20### 属性 21 22**系统能力：** SystemCapability.Applications.Settings.Core 23 24| 名称 | 类型 | 可读 | 可写 | 说明 | 25|-----------------------------| ------ | ---- | ---- | ------------------------------------------------------------ | 26| DEVICE_SHARED<sup>11+</sup> | string | 是 | 是 | 设备属性共享域。 | 27| USER_PROPERTY<sup>11+</sup> | string | 是 | 是 | 为用户属性域。 | 28 29## date 30 31提供设置时间和日期格式的数据项(暂不支持)。 32 33### 属性 34 35**系统能力：** SystemCapability.Applications.Settings.Core 36 37| 名称 | 类型 | 可读 | 可写 | 说明 | 38| ------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 39| DATE_FORMAT | string | 是 | 是 | 日期格式。<br/>日期格式包括mm/dd/yyyy、dd/mm/yyyy和yyyy/mm/dd ，其中mm、dd和yyyy分别代表月份、日期和年份。 | 40| TIME_FORMAT | string | 是 | 是 | 时间以12小时格式或24小时格式显示。<br>- 值为 "12"表示12小时格式。<br/>- 值为"24"表示24小时格式。 | 41| AUTO_GAIN_TIME | string | 是 | 是 | 是否自动从网络获取日期、时间和时区。 <br>- 值为true表示自动从网络获取信息。<br/>- 值为false表示不自动获取信息。 | 42| AUTO_GAIN_TIME_ZONE | string | 是 | 是 | 是否自动从NITZ获取时区。 <br>- 值为true表示自动获取。<br/>- 值为false表示不自动获取。 | 43 44## display 45 46提供设置显示效果的数据项(暂不支持)。 47 48### 属性 49 50**系统能力：** SystemCapability.Applications.Settings.Core 51 52| 名称 | 类型 | 可读 | 可写 | 说明 | 53| ----------------------------- | ------ | ---- | ---- |-------------------------------------------------------------------------------------------------------------| 54| FONT_SCALE | string | 是 | 是 | 字体的比例因子，值为浮点数。(当前版本参数仅支持固定值查询。) | 55| SCREEN_BRIGHTNESS_STATUS | string | 是 | 是 | 屏幕亮度。取值范围:0到255。 | 56| AUTO_SCREEN_BRIGHTNESS | string | 是 | 是 | 是否启用屏幕亮度自动调整。<br/>- 值为AUTO_SCREEN_BRIGHTNESS_MODE，表示启用自动调整。<br/>- 值为MANUAL_SCREEN_BRIGHTNESS_MODE，表示不启用自动调整。 | 57| AUTO_SCREEN_BRIGHTNESS_MODE | number | 是 | 是 | 使用屏幕亮度自动调整时AUTO_SCREEN_BRIGHTNESS的值。 | 58| MANUAL_SCREEN_BRIGHTNESS_MODE | number | 是 | 是 | 使用屏幕亮度手动调整时的AUTO_SCREEN_BRIGHTNESS值。 | 59| SCREEN_OFF_TIMEOUT | string | 是 | 是 | 设备在一段时间不活动后进入睡眠状态的等待时间(单位:ms)。 | 60| DEFAULT_SCREEN_ROTATION | string | 是 | 是 | 启用屏幕的自动旋转时，此属性无效。不启用自动旋转时，以下值可用。<br>- 值为0，表示屏幕旋转0度。<br>- 值为1，表示屏幕旋转90度。<br/>- 值为2，表示屏幕旋转180度。<br/>- 值为3，表示屏幕旋转270度。 | 61| ANIMATOR_DURATION_SCALE | string | 是 | 是 | 动画持续时间的比例因子。影响所有此类动画的开始延迟和持续时间。<br/>值为0，表示动画将立即结束。默认值为1。 | 62| TRANSITION_ANIMATION_SCALE | string | 是 | 是 | 过渡动画的比例因子。<br/>值为0，表示禁用过渡动画。 | 63| WINDOW_ANIMATION_SCALE | string | 是 | 是 | 普通窗口动画的比例因子。<br/>值为0，表示禁用窗口动画。 | 64| DISPLAY_INVERSION_STATUS | string | 是 | 是 | 是否启用显示颜色反转。<br/>- 值为1，表示启用显示颜色反转。<br/>- 值为0，表示不启用显示颜色反转。 | 65 66## general 67 68提供设置设备常规信息的数据项(暂不支持)。 69 70### 属性 71 72**系统能力：** SystemCapability.Applications.Settings.Core 73 74| 名称 | 类型 | 可读 | 可写 | 说明 | 75| -------------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 76| SETUP_WIZARD_FINISHED | string | 是 | 是 | 是否已运行启动向导。<br>- 值为0，表示启动向导尚未运行。<br/>- 值不为0，表示启动向导已运行。 | 77| END_BUTTON_ACTION | string | 是 | 是 | 用户不在呼叫中时，由用户按下呼叫结束按钮会发生的情况。<br/>- 值为0，表示没有任何反应。<br/>- 值为1，表示显示主屏幕。<br/>- 值为2，表示设备进入睡眠状态，屏幕锁定。<br/>- 值为3，表示显示主屏幕。如果用户已在主屏幕上，设备将进入睡眠状态。 | 78| ACCELEROMETER_ROTATION_STATUS | string | 是 | 是 | 是否使用加速计更改屏幕方向，即是否启用自动旋转。<br>- 值为1，表示启用加速计。<br/>- 值为0，表示不启用加速计。 | 79| DEVICE_PROVISION_STATUS | string | 是 | 是 | 是否预配设备。<br>在具有单个系统用户的多用户设备上，当值为true时，屏幕可能会被锁定。此外，其他功能无法在系统用户上启动，除非被标记在屏幕锁定上显示。 | 80| HDC_STATUS | string | 是 | 是 | 是否启用USB设备上的硬盘控制器(HDC)。<br>- 值为true，表示启用HDC。<br/>- 值为false，表示不启用HDC。 | 81| BOOT_COUNTING | string | 是 | 是 | 设备开机后的启动操作数。 | 82| CONTACT_METADATA_SYNC_STATUS | string | 是 | 是 | 是否启用联系人元数据同步。<br>- 值为true，表示启用同步。<br/>- 值为false，表示不启用同步。 | 83| DEVICE_NAME | string | 是 | 是 | 设备名称。 | 84| USB_STORAGE_STATUS | string | 是 | 是 | 是否启用USB大容量存储。<br>- 值为true，表示启用USB大容量存储。<br/>- 值为false，表示不启用USB大容量存储。 | 85| DEBUGGER_WAITING | string | 是 | 是 | 设备在启动应用程序进行调试时是否等待调试器进行调试。<br>- 值为1，表示设备等待调试器。<br/>- 值为0，表示系统不会等待调试器，因此应用程序会正常运行。 | 86| DEBUG_APP_PACKAGE | string | 是 | 是 | 要调试的应用程序的bundle name。 | 87| ACCESSIBILITY_STATUS | string | 是 | 是 | 是否启用辅助功能。<br>- 值为1，表示启用辅助功能。<br/>- 值为0，表示不启用辅助功能。 | 88| ACTIVATED_ACCESSIBILITY_SERVICES | string | 是 | 是 | 已激活的辅助功能的列表。 | 89| GEOLOCATION_ORIGINS_ALLOWED | string | 是 | 是 | 浏览器可以使用的默认地理位置。多个地理位置由空格分隔。 | 90| SKIP_USE_HINTS | string | 是 | 是 | 应用程序是否应在首次启动时尝试跳过所有介绍性提示。适用于临时用户或熟悉环境的用户。<br>- 值为1，表示应用程序将尝试在第一次启动时跳过所有介绍性提示。<br/>- 值为0，表示应用程序不会在首次启动时跳过介绍性提示。 | 91| TOUCH_EXPLORATION_STATUS | string | 是 | 是 | 是否启用触摸浏览。<br>- 值为1，表示启用触摸浏览。<br/>- 值为0，表示不启用触摸浏览。 | 92 93## input 94 95提供设置有关输入法信息的数据项。(暂不支持) 96 97### 属性 98 99**系统能力：** SystemCapability.Applications.Settings.Core 100 101| 名称 | 类型 | 可读 | 可写 | 说明 | 102| ------------------------------------ | ------ | ---- | ---- | ------------------------------------------------------------ | 103| DEFAULT_INPUT_METHOD | string | 是 | 是 | 默认输入法及其ID。 | 104| ACTIVATED_INPUT_METHOD_SUB_MODE | string | 是 | 是 | 默认输入法键盘类型及其ID。 | 105| ACTIVATED_INPUT_METHODS | string | 是 | 是 | 已激活的输入法的列表。<br>该列表是一个字符串，由已激活的输入法ID和输入法键盘类型组成。<br>输入法ID后添加冒号':'连接，输入法的键盘类型后添加分号';'连接。<br>用ima代表输入法ID，keyboardType代表键盘类型，示例格式是ima0:keyboardType0;keyboardType1;ima1:ima2:keyboardTypes0。 | 106| SELECTOR_VISIBILITY_FOR_INPUT_METHOD | string | 是 | 是 | 输入法选择器是否可见。<br>值为1，表示输入法选择器可见。<br/>值为0，表示输入法选择器不可见。 | 107| AUTO_CAPS_TEXT_INPUT | string | 是 | 是 | 是否为文本编辑器启用自动大写。<br>值为0，表示不启用自动大写。<br/>值为1，表示启用自动大写。 | 108| AUTO_PUNCTUATE_TEXT_INPUT | string | 是 | 是 | 是否为文本编辑器启用自动标点符号。自动标点符号使文本编辑器能够将两个空格转换为句点'.'和空格。<br>值为0，表示不启用自动标点符号。<br/>值为1，表示启用自动标点符号。 | 109| AUTO_REPLACE_TEXT_INPUT | string | 是 | 是 | 是否为文本编辑器启用自动更正。自动更正使文本编辑器能够更正拼写错误。<br>值为0，表示不启用自动更正。<br/>值为1，表示启用自动更正。 | 110| SHOW_PASSWORD_TEXT_INPUT | string | 是 | 是 | 是否在文本编辑器中启用密码显示。密码显示使文本编辑器能够在用户键入密码字符时显示密码字符。<br>值为0，表示不启用密码显示。<br/>值为1，表示启用密码显示。 | 111 112## network 113 114提供设置网络信息的数据项。(暂不支持) 115 116### 属性 117 118**系统能力：** SystemCapability.Applications.Settings.Core 119 120| 名称 | 类型 | 可读 | 可写 | 说明 | 121| ------------------------ | ------ | ---- | ---- | ------------------------------------------------------------ | 122| DATA_ROAMING_STATUS | string | 是 | 是 | 是否启用数据漫游。<br>值为true，表示启用数据漫游。<br/>值为false，表示不启用数据漫游。 | 123| HTTP_PROXY_CFG | string | 是 | 是 | 全局HTTP代理的主机名和端口号。主机名和端口号由冒号':'分隔。 | 124| NETWORK_PREFERENCE_USAGE | string | 是 | 是 | 要使用网络的用户首选项。 | 125 126## phone 127 128提供设置来电和去电接听方式的数据项。(暂不支持) 129 130### 属性 131 132**系统能力：** SystemCapability.Applications.Settings.Core 133 134| 名称 | 类型 | 可读 | 可写 | 说明 | 135| ------------------ | ------ | ---- | ---- | ------------------------------------------------------------ | 136| RTT_CALLING_STATUS | string | 是 | 是 | 是否启用实时文本(RTT)呼叫。启用，来电和去电在设备和运营商支持时作为RTT呼叫应答。 <br> 值为1，表示启用RTT呼叫。 <br/> 值为0，表示不启用RTT呼叫。 | 137 138## sound 139 140提供设置声音效果的数据项。(暂不支持) 141 142### 属性 143 144**系统能力：** SystemCapability.Applications.Settings.Core 145 146| 名称 | 类型 | 可读 | 可写 | 说明 | 147| ---------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 148| VIBRATE_WHILE_RINGING | string | 是 | 是 | 设备在来电响铃时是否振动。此属性由电话和设置应用程序使用。<br/>该值是布尔类型，仅影响设备因来电而响铃的情况，不影响任何其他应用程序或场景。 | 149| DEFAULT_ALARM_ALERT | string | 是 | 是 | 系统默认告警的存储区域。 | 150| DTMF_TONE_TYPE_WHILE_DIALING | string | 是 | 是 | 拨号时播放的双音多频(DTMF)音的类型。 <br>值为0表示常规的短音效。<br/>值为1表示长音效。 | 151| DTMF_TONE_WHILE_DIALING | string | 是 | 是 | 拨号时是否播放DTMF音。<br>值为1，表示播放DTMF音。<br/>值为0，表示不播放。 | 152| AFFECTED_MODE_RINGER_STREAMS | string | 是 | 是 | 音频流受振铃模式和请勿打扰(DND)模式更改的影响。要求特定的音频流受到振铃模式和DDN模式变化的影响，将对应比特位设置为1。 | 153| AFFECTED_MUTE_STREAMS | string | 是 | 是 | 受静音模式影响的音频流。要求特定音频流在静音模式下保持静音，将相应位设置为1。 | 154| DEFAULT_NOTIFICATION_SOUND | string | 是 | 是 | 系统默认通知音的存储区域。 | 155| DEFAULT_RINGTONE | string | 是 | 是 | 系统默认铃声的存储区域。 | 156| SOUND_EFFECTS_STATUS | string | 是 | 是 | 声音功能是否可用。<br>值为0表示不可用。 <br/>值为1表示可用。 | 157| VIBRATE_STATUS | string | 是 | 是 | 设备是否为事件振动。该参数在系统内部使用。 <br>值为1，表示设备会因事件而振动。 <br/>值为0，表示设备不因事件振动。 | 158| HAPTIC_FEEDBACK_STATUS | string | 是 | 是 | 设备是否启用触觉反馈。<br/>值为true，表示启用触觉反馈。<br/>值为false，表示不启用触觉反馈。 | 159 160## TTS 161 162提供设置文本到语音(TTS)转换信息的数据项。(暂不支持) 163 164### 属性 165 166**系统能力：** SystemCapability.Applications.Settings.Core 167 168| 名称 | 类型 | 可读 | 可写 | 说明 | 169| ------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 170| DEFAULT_TTS_PITCH | string | 是 | 是 | 文本转语音(TTS)引擎的默认音高。<br>其中100=1x，该值设置为200，表示频率是正常声音频率的两倍。 | 171| DEFAULT_TTS_RATE | string | 是 | 是 | TTS引擎的默认语速。<br>其中100=1x。 | 172| DEFAULT_TTS_SYNTH | string | 是 | 是 | 默认TTS引擎。 | 173| ENABLED_TTS_PLUGINS | string | 是 | 是 | 用于TTS的已激活插件包列表，多个插件包用空格分隔。 | 174 175 176## wireless 177 178提供设置无线网络信息的数据项。(暂不支持) 179 180### 属性 181 182**系统能力：** SystemCapability.Applications.Settings.Core 183 184| 名称 | 类型 | 可读 | 可写 | 说明 | 185| --------------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | 186| BLUETOOTH_DISCOVER_ABILITY_STATUS | string | 是 | 是 | 设备是否可以被其他设备通过蓝牙发现或连接。<br>值为0表示设备不可以被连接或发现。<br/>值为1表示设备可以被连接但不可以被发现。<br/>值为2表示设备可以被连接和发现。 | 187| BLUETOOTH_DISCOVER_TIMEOUT | string | 是 | 是 | 通过蓝牙发现设备的持续时间(以秒为单位)。<br>这段时间后，设备不可以被蓝牙搜寻到。 | 188| AIRPLANE_MODE_RADIOS | string | 是 | 是 | 启用飞行模式时要禁用的无线电信号列表。 <br>多个无线电信号用逗号(,)分隔。<br>取值包括以下常量：BLUETOOTH_RADIO、 CELL_RADIO、 NFC_RADIO、 WIFI_RADIO。 | 189| BLUETOOTH_RADIO | string | 是 | 否 | 常量，作为AIRPLANE_MODE_RADIOS的取值时表示蓝牙在飞行模式下禁用。 | 190| CELL_RADIO | string | 是 | 否 | 常量，作为AIRPLANE_MODE_RADIOS的取值时表示蜂窝无线电在飞行模式下禁用。 | 191| NFC_RADIO | string | 是 | 否 | 常量，作为AIRPLANE_MODE_RADIOS的取值时表示NFC在飞行模式下禁用。 | 192| WIFI_RADIO | string | 是 | 否 | 常量，作为AIRPLANE_MODE_RADIOS的取值时表示Wi-Fi在飞行模式下禁用。 | 193| BLUETOOTH_STATUS | string | 是 | 是 | 蓝牙是否可用。 <br>- 值为true表示蓝牙可用。<br/>- 值为false表示蓝牙不可用。 | 194| OWNER_LOCKDOWN_WIFI_CFG | string | 是 | 是 | 是否应锁定由设备所有者的应用程序创建的Wi-Fi配置。<br>- 值为true表示Wi-Fi配置应该被锁定。<br/>- 值为false表示不应该被锁定。 | 195| WIFI_DHCP_MAX_RETRY_COUNT | string | 是 | 是 | 尝试从DHCP服务器获取IP地址的最大次数。 | 196| WIFI_TO_MOBILE_DATA_AWAKE_TIMEOUT | string | 是 | 是 | Wi-Fi连接断开后等待移动数据连接时保持唤醒锁的最长时间。 | 197| WIFI_STATUS | string | 是 | 是 | Wi-Fi是否可用。<br>- 值为true表示Wi-Fi可用。<br/>- 值为false表示Wi-Fi不可用。 | 198| WIFI_WATCHDOG_STATUS | string | 是 | 是 | Wi-Fi的WatchDog是否可用。 <br>- 值为true表示可用。<br/>- 值为false表示不可用。 | 199 200 201## settings.setValue<sup>10+</sup> 202 203setValue(context: Context, name: string, value: string, callback: AsyncCallback\<boolean>): void 204 205将数据项名称及数据项的值保存到数据库中，使用callback异步回调。 206 207**模型约束**：此接口仅可在Stage模型下使用。 208 209**系统能力**：SystemCapability.Applications.Settings.Core 210 211**需要权限**： ohos.permission.MANAGE_SETTINGS，仅系统应用可用。 212 213**参数**： 214 215| 参数名 | 类型 | 必填 | 说明 | 216| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 217| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 218| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 219| value | string | 是 | 数据项值。取值范围随业务变动。 | 220| callback | AsyncCallback\<boolean> | 是 | 回调函数。返回true表示操作成功，否则操作失败。 | 221 222**示例**： 223 224```js 225import settings from '@ohos.settings'; 226import { common } from '@kit.AbilityKit'; 227 228// 更新数据项亮度的值(该数据项在数据库中已存在，故setValue方法将更新该数据项的值)。 229const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 230settings.setValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', (status) => { 231 console.log('Callback return whether value is set.'); 232}); 233``` 234 235## settings.setValue<sup>10+</sup> 236 237setValue(context: Context, name: string, value: string): Promise\<boolean> 238 239将数据项名称及数据项的值保存到数据库中。使用Promise异步回调。 240 241**模型约束**：此接口仅可在Stage模型下使用。 242 243**系统能力**：SystemCapability.Applications.Settings.Core 244 245**需要权限**： ohos.permission.MANAGE_SETTINGS，该权限仅系统应用可用。 246 247**参数**： 248 249| 参数名 | 类型 | 必填 | 说明 | 250| ------- | ------- | ---- | ------------------------------------------------------------ | 251| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 252| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 253| value | string | 是 | 数据项值。取值范围随业务变动。 | 254 255**返回值**： 256 257| 类型 | 说明 | 258| ----------------- | -------------------------------------------------- | 259| Promise\<boolean> | Promise对象。返回true表示操作成功，否则返回false。 | 260 261**示例**： 262 263```js 264import settings from '@ohos.settings'; 265import { common } from '@kit.AbilityKit'; 266 267// 更新数据项亮度的值(该数据项在数据库中已存在，故setValue方法将更新该数据项的值)。 268const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 269settings.setValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100').then((status) => { 270 console.log('Callback return whether value is set.'); 271}); 272``` 273 274## settings.setValue<sup>11+</sup> 275 276setValue(context: Context, name: string, value: string, domainName: string): Promise\<boolean> 277 278将数据项名称及数据项的值保存到数据库中。使用 Promise异步回调。 279 280**模型约束**：此接口仅可在Stage模型下使用。 281 282**系统能力**：SystemCapability.Applications.Settings.Core 283 284**需要权限**： 285- 写入DEVICE_SHARED、USER_PROPERTY域需要权限ohos.permission.MANAGE_SETTINGS，该权限仅系统应用可用。 286- 写入USER_SECURITY域需要权限ohos.permission.MANAGE_SECURE_SETTINGS，该权限仅系统应用可用。 287 288**参数**： 289 290| 参数名 | 类型 | 必填 | 说明 | 291| -------- | ---------------------- | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 292| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 293| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 294| value | string | 是 | 数据项值。取值范围随业务变动。 | 295|domainName| string | 是 | 指定要设置的域名。 <br>- domainName为domainName.DEVICE_SHARED,<br> 表示设备属性共享域。<br>- domainName为domainName.USER_PROPERTY,<br> 表示用户属性域。 <br>- domainName为domainName.USER_SECURITY,<br> 表示用户安全属性域(仅对系统应用开放)。 | 296 297**返回值**： 298 299| 类型 | 说明 | 300| ---------------- | ----------------------------------- | 301| Promise\<string> | Promise对象。返回true表示操作成功，否则返回false。 | 302 303**错误码**： 304 305以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 306 307| 错误码ID | 错误信息 | 308| ------- | -------- | 309| 201 | Permission denied. | 310 311**示例**： 312 313```js 314import settings from '@ohos.settings'; 315import { common } from '@kit.AbilityKit'; 316 317// 更新数据项亮度的值(该数据项在数据库中已存在，故setValue方法将更新该数据项的值)。 318const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 319settings.setValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', settings.domainName.DEVICE_SHARED).then((status) => { 320 console.log(`callback:return whether value is set.`) 321}); 322``` 323 324## settings.getValue<sup>10+</sup> 325 326getValue(context: Context, name: string, callback: AsyncCallback\<string>): void 327 328获取数据库中指定数据项的值。使用callback异步回调。 329 330**模型约束**：此接口仅可在Stage模型下使用。 331 332**系统能力**：SystemCapability.Applications.Settings.Core 333 334**参数**： 335 336| 参数名 | 类型 | 必填 | 说明 | 337| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 338| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 339| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 340| callback | AsyncCallback\<string> | 是 | 使用callback方式获取数据项的值。 | 341 342**示例**： 343 344```js 345import settings from '@ohos.settings'; 346import { common } from '@kit.AbilityKit'; 347 348const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 349settings.getValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, (err, value) => { 350 if (err) { 351 console.error(`Failed to get the setting. ${err.message} `); 352 return; 353 } 354 console.log(`callback:value -> ${value}`) 355}); 356``` 357 358## settings.getValue<sup>10+</sup> 359 360getValue(context: Context, name: string): Promise\<string> 361 362获取数据库中指定数据项的值。使用Promise异步回调。 363 364**模型约束**：此接口仅可在Stage模型下使用。 365 366**系统能力**：SystemCapability.Applications.Settings.Core 367 368**参数**： 369 370| 参数名 | 类型 | 必填 | 说明 | 371| ------- | ------- | ---- | ------------------------------------------------------------ | 372| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 373| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 374 375**返回值**： 376 377| 类型 | 说明 | 378| ---------------- | ----------------------------------- | 379| Promise\<string> | Promise对象。返回获得的数据项的值。 | 380 381**示例**： 382 383```js 384import settings from '@ohos.settings'; 385import { common } from '@kit.AbilityKit'; 386 387const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 388settings.getValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value) => { 389 console.log(`promise:value -> ${value}`) 390}); 391``` 392 393## settings.getValue<sup>11+</sup> 394 395getValue(context: Context, name: string, domainName: string): Promise\<string>; 396 397获取数据库中指定数据项的值。使用 Promise异步回调。 398 399**模型约束**：此接口仅可在Stage模型下使用。 400 401**系统能力**：SystemCapability.Applications.Settings.Core 402 403**需要权限**： 404- 读取USER_SECURITY域需要权限ohos.permission.MANAGE_SECURE_SETTINGS，该权限仅系统应用可用。 405 406**参数**： 407 408| 参数名 | 类型 | 必填 | 说明 | 409| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 410| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 411| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 412|domainName| string | 是 | 指定要设置的域名。 <br>- domainName为domainName.DEVICE_SHARED,<br> 设备属性共享域。<br>- domainName为domainName.USER_PROPERTY,<br> 表示为用户属性域。 <br>- domainName为domainName.USER_SECURITY,<br> 表示为用户安全属性域(仅对系统应用开放)。| 413 414**返回值**： 415 416| 类型 | 说明 | 417| ---------------- | ----------------------------------- | 418| Promise\<string> | Promise对象。返回获得的数据项的值。 | 419 420**示例**： 421 422```js 423import settings from '@ohos.settings'; 424import { common } from '@kit.AbilityKit'; 425 426// 更新数据项亮度的值(该数据项在数据库中已存在，故getValue方法将更新该数据项的值)。 427const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 428settings.getValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, settings.domainName.DEVICE_SHARED).then((value) => { 429 console.log(`Promise:value -> ${value}`); 430}); 431``` 432 433## settings.getValueSync<sup>10+</sup> 434 435getValueSync(context: Context, name: string, defValue: string): string; 436 437获取数据项的值。此方法相较getValue为同步方法。 438 439**模型约束**：此接口仅可在Stage模型下使用。 440 441**系统能力**：SystemCapability.Applications.Settings.Core 442 443**参数**： 444 445| 参数名 | 类型 | 必填 | 说明 | 446| -------- | ------- | ---- | ------------------------------------------------------------ | 447| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 448| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 449| defValue | string | 是 | 默认值。由开发者设置，未从数据库中查询到该数据时，表示返回该默认值。 | 450 451**返回值**： 452 453| 类型 | 说明 | 454| ------ | ---------------- | 455| string | 返回数据项的值。 | 456 457**示例**： 458 459```js 460import settings from '@ohos.settings'; 461import { common } from '@kit.AbilityKit'; 462 463// 获取数据项亮度的值(该数据项在数据库中已存在)。 464const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 465let value = settings.getValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '10'); 466``` 467 468## settings.getValueSync<sup>11+</sup> 469 470getValueSync(context: Context, name: string, defValue: string, domainName: string): string; 471 472获取数据项的值。此方法相较getValue为同步方法。 473 474**模型约束**：此接口仅可在Stage模型下使用。 475 476**系统能力**：SystemCapability.Applications.Settings.Core 477 478**需要权限**： 479- 读取USER_SECURITY域需要权限ohos.permission.MANAGE_SECURE_SETTINGS，该权限仅系统应用可用。 480 481**参数**： 482 483| 参数名 | 类型 | 必填 | 说明 | 484|------------| ---------------------- | ---- | ------------------------------------------------------------ | 485| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 486| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 487| defValue | string | 是 | 数据项值。取值范围随业务变动。 | 488| domainName | string | 是 | 指定要设置的域名。 <br>- domainName为domainName.DEVICE_SHARED,<br> 设备属性共享域。<br>- domainName为domainName.USER_PROPERTY,<br> 表示为用户属性域。 <br>- domainName为domainName.USER_SECURITY,<br> 表示为用户安全属性域(仅对系统应用开放)。| 489 490 491**返回值**： 492 493| 类型 | 说明 | 494| ---------------- | ----------------------------------- | 495| string | 返回数据项的值。 | 496 497**示例**： 498 499```js 500import settings from '@ohos.settings'; 501import { common } from '@kit.AbilityKit'; 502 503// 更新数据项亮度的值(该数据项在数据库中已存在)。 504const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 505let value = settings.getValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', settings.domainName.DEVICE_SHARED); 506``` 507 508## settings.setValueSync<sup>10+</sup> 509 510setValueSync(context: Context, name: string, value: string): boolean 511 512设置数据项的值。此方法相较setValue为同步方法。 513 514- 如果数据库中已经存在该数据项，则setValueSync方法将更新该数据项的值。 515- 如果数据库中尚未存在该数据项，则setValueSync方法将向数据库中插入该数据项。 516 517**模型约束**：此接口仅可在Stage模型下使用。 518 519**系统能力**：SystemCapability.Applications.Settings.Core 520 521**需要权限**： ohos.permission.MANAGE_SETTINGS，该权限仅系统应用可用。 522 523**参数**： 524 525| 参数名 | 类型 | 必填 | 说明 | 526| ------- | ------- | ---- | ------------------------------------------------------------ | 527| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 528| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 529| value | string | 是 | 数据项的具体数值。取值范围随业务变动。 | 530 531**返回值**： 532 533| 类型 | 说明 | 534| ------- | ------------------------------------------------------------ | 535| boolean | 返回设置数据项的值是否成功的结果。true表示设置成功，false表示设置失败。 | 536 537**示例**： 538 539```js 540import settings from '@ohos.settings'; 541import { common } from '@kit.AbilityKit'; 542 543// 更新数据项亮度的值(该数据项在数据库中已存在，故setValueSync方法将更新该数据项的值)。 544const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 545let ret = settings.setValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100'); 546``` 547 548## settings.setValueSync<sup>11+</sup> 549 550setValueSync(context: Context, name: string, value: string, domainName: string): boolean 551 552设置数据项的值。此方法相较setValue为同步方法。 553 554- 如果数据库中已经存在该数据项，则setValueSync方法将更新该数据项的值。 555- 如果数据库中尚未存在该数据项，则setValueSync方法将向数据库中插入该数据项。 556 557**模型约束**：此接口仅可在Stage模型下使用。 558 559**系统能力**：SystemCapability.Applications.Settings.Core 560 561**需要权限**： 562- 写入DEVICE_SHARED、USER_PROPERTY域需要权限ohos.permission.MANAGE_SETTINGS，该权限仅系统应用可用。 563- 写入USER_SECURITY域需要权限ohos.permission.MANAGE_SECURE_SETTINGS，该权限仅系统应用可用。 564 565**参数**： 566 567| 参数名 | 类型 | 必填 | 说明 | 568|---------| ---------------------- | ---- | ------------------------------------------------------------ | 569| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 570| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 571| value | string | 是 | 数据项值。取值范围随业务变动。 | 572| domainName | string | 是 | 指定要设置的域名。 <br>- domainName为domainName.DEVICE_SHARED,<br> 设备属性共享域。<br>- domainName为domainName.USER_PROPERTY,<br> 表示为用户属性域。 <br>- domainName为domainName.USER_SECURITY,<br> 表示为用户安全属性域(仅对系统应用开放)。| 573 574**返回值**： 575 576| 类型 | 说明 | 577| ---------------- | ----------------------------------- | 578| boolean | 返回设置数据项的值是否成功的结果。true表示设置成功，false表示设置失败。 | 579 580**错误码**： 581 582以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 583 584| 错误码ID | 错误信息 | 585| ------- | -------- | 586| 201 | Permission denied. | 587 588**示例**： 589 590```js 591import settings from '@ohos.settings'; 592import { common } from '@kit.AbilityKit'; 593 594// 更新数据项亮度的值(该数据项在数据库中已存在，故setValueSync方法将更新该数据项的值)。 595const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 596let ret = settings.setValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '100', settings.domainName.DEVICE_SHARED); 597``` 598 599## settings.registerKeyObserver<sup>11+</sup> 600 601registerKeyObserver(context: Context, name: string, domainName: string, observer:AsyncCallback\<void>): boolean 602 603用于在指定上下文中注册一个观察者，以便在指定域名中观察指定的域名。当该键值发生变化时，将调用注册的回调函数。成功注册返回true，否则返回false。 604 605**模型约束**：此接口仅可在Stage模型下使用。 606 607**系统能力**：SystemCapability.Applications.Settings.Core 608 609**参数**： 610 611| 参数名 | 类型 | 必填 | 说明 | 612| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 613| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 614| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 615|domainName| string | 是 | 指定要设置的域名。 <br>- domainName为domainName.DEVICE_SHARED,<br> 设备属性共享域。<br>- domainName为domainName.USER_PROPERTY,<br> 表示为用户属性域。 <br>- domainName为domainName.USER_SECURITY,<br> 表示为用户安全属性域(仅对系统应用开放)。| 616|observer | AsyncCallback\<void> | 是 | 使用callback方式获取数据项的值。 | 617 618**返回值**： 619 620| 类型 | 说明 | 621| ---------------- | ----------------------------------- | 622| boolean | 返回设置数据项的值是否成功的结果。true表示设置成功，false表示设置失败。 | 623 624**示例**： 625 626```js 627import settings from '@ohos.settings'; 628import { common } from '@kit.AbilityKit'; 629 630const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 631settings.registerKeyObserver(context, settings.display.SCREEN_BRIGHTNESS_STATUS, settings.domainName.DEVICE_SHARED, (err, val) => { 632 if (err) { 633 console.error(`Failed to get the setting. ${err.message} `); 634 return; 635 } 636 console.log(`callback:value -> ${JSON.stringify(val)}`) 637 let value:string = settings.getValueSync(context, settings.display.SCREEN_BRIGHTNESS_STATUS, '10'); 638 console.log(`Promise:value -> ${value}`); 639}); 640``` 641 642## settings.unregisterKeyObserver<sup>11+</sup> 643 644unregisterKeyObserver(context: Context, name: string, domainName: string): boolean 645 646同步方法，进行注销指定域名下对指定键的监视器。 647 648**模型约束**：此接口仅可在Stage模型下使用。 649 650**系统能力**：SystemCapability.Applications.Settings.Core 651 652| 参数名 | 类型 | 必填 | 说明 | 653| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 654| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 655| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 656|domainName| string | 是 | 指定要设置的域名。 <br>- domainName为domainName.DEVICE_SHARED,<br> 设备属性共享域。<br>- domainName为domainName.USER_PROPERTY,<br> 表示为用户属性域。 <br>- domainName为domainName.USER_SECURITY,<br> 表示为用户安全属性域(仅对系统应用开放)| 657 658**返回值**： 659 660| 类型 | 说明 | 661| ---------------- | ----------------------------------- | 662| boolean | 返回注销指定域名下对指定键的监视器是否成功的结果。true表示注销成功，false表示注销失败。 | 663 664**示例**： 665 666```js 667import settings from '@ohos.settings'; 668import { common } from '@kit.AbilityKit'; 669 670const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 671let ret = settings.unregisterKeyObserver(context, settings.display.SCREEN_BRIGHTNESS_STATUS, settings.domainName.DEVICE_SHARED); 672``` 673 674## settings.openNetworkManagerSettings<sup>18+</sup> 675 676openNetworkManagerSettings(context: Context): Promise\<boolean> 677 678打开网络管理器设置页面。使用Promise异步回调。 679 680**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 681 682**系统能力**：SystemCapability.Applications.Settings.Core 683 684**参数**： 685 686| 参数名 | 类型 | 必填 | 说明 | 687| -------- | ---------------------- | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 688| context | Context | 是 | 应用上下文(仅支持UIAbilityContext和ExtensionContext)。<br />Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-context.md)。 | 689 690**返回值**： 691 692| 类型 | 说明 | 693| ---------------- | ----------------------------------- | 694| Promise\<string> | Promise对象。返回true表示操作成功，否则返回false。 | 695 696**错误码**： 697 698以下错误码详细介绍请参考[设置数据项错误码](./errorcode-settings.md)。 699 700| 错误码ID | 错误信息 | 701|----------|-------------------------| 702| 14800000 | Parameter error. | 703| 14800010 | Original service error. | 704 705**示例**： 706 707```js 708import settings from '@ohos.settings'; 709import { common } from '@kit.AbilityKit'; 710 711// 跳转网络管理器设置页面。 712const context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 713settings.openNetworkManagerSettings(context).then((status) => { 714 console.log(`callback:return whether setings is open.`) 715}); 716``` 717 718## settings.enableAirplaneMode 719 720enableAirplaneMode(enable: boolean, callback: AsyncCallback\<void>): void 721 722启用或禁用飞行模式。使用callback异步回调。(暂不支持) 723 724**系统能力**：SystemCapability.Applications.Settings.Core 725 726**参数**： 727 728| 参数名 | 类型 | 必填 | 说明 | 729| -------- | -------------------- | ---- | ----------------------------------------------- | 730| enable | boolean | 是 | 是否开启飞行模式。true表示开启，false表示禁用。 | 731| callback | AsyncCallback\<void> | 是 | 回调函数。 | 732 733**示例**： 734 735```js 736let isEnabled :boolean = true; 737settings.enableAirplaneMode(isEnabled, (err:Error) => { 738 if (err) { 739 console.log('Failed to enable AirplaneMode.'); 740 return; 741 } 742 console.log('Return true if enable.'); 743}) 744``` 745 746## settings.enableAirplaneMode 747 748enableAirplaneMode(enable: boolean): Promise\<void> 749 750启用或禁用飞行模式。使用Promise异步回调。(暂不支持) 751 752**系统能力**：SystemCapability.Applications.Settings.Core 753 754**参数**： 755 756| 参数名 | 类型 | 必填 | 说明 | 757| ------ | ------- | ---- | ----------------------------------------------- | 758| enable | boolean | 是 | 是否开启飞行模式。true表示开启，false表示禁用。 | 759 760**返回值**： 761 762| 类型 | 说明 | 763| -------------- | ------------------------- | 764| Promise\<void> | 无返回结果的Promise对象。 | 765 766**示例**： 767 768```js 769let isEnabled :boolean = true; 770settings.enableAirplaneMode(isEnabled).then(() => { 771 console.log('Succeeded in enabling AirplaneMode.'); 772}).catch((err:Error) => { 773 console.log(`Failed to enable AirplaneMode. Cause: ${err}`); 774}) 775``` 776 777## settings.canShowFloating 778 779canShowFloating(callback: AsyncCallback\<boolean>): void 780 781检查应用是否能够以悬浮窗形式显示。使用callback异步回调。(暂不支持) 782 783**系统能力**：SystemCapability.Applications.Settings.Core 784 785**参数**： 786 787| 参数名 | 类型 | 必填 | 说明 | 788| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 789| callback | AsyncCallback\<boolean> | 是 | 回调函数。<br/>返回true，表示应用能够以悬浮窗形式显示。返回false，表示不能。 | 790 791**示例**： 792 793```js 794settings.canShowFloating((err:Error, status: boolean) => { 795 if (err) { 796 console.error(`Failed to Checks whether a specified application can show as float window ${err.message} `); 797 return; 798 } 799 console.log('Checks whether a specified application can show as float window.'); 800}); 801``` 802 803## settings.canShowFloating 804 805canShowFloating(): Promise\<boolean> 806 807检查应用是否能够以悬浮窗形式显示。使用Promise异步回调。(暂不支持) 808 809**系统能力**：SystemCapability.Applications.Settings.Core 810 811**返回值**： 812 813| 类型 | 说明 | 814| ----------------- | ------------------------------------------------------------ | 815| Promise\<boolean> | Promise对象。<br/>返回true，表示应用能够以悬浮窗形式显示。返回false，表示不能。 | 816 817**示例**： 818 819```js 820settings.canShowFloating().then((status:boolean) => { 821 console.log('Checks whether a specified application can show as float window.'); 822}); 823``` 824 825## settings.getUriSync<sup>8+</sup> 826 827getUriSync(name: string): string 828 829获取数据项的URI。(暂不支持) 830 831**系统能力**：SystemCapability.Applications.Settings.Core 832 833**参数**： 834 835| 参数名 | 类型 | 必填 | 说明 | 836| ------ | ------ | ---- | ------------------------------------------------------------ | 837| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 838 839**返回值**： 840 841| 类型 | 说明 | 842| ------ | ------------- | 843| string | 数据项的URI。 | 844 845**示例**： 846 847```js 848// 获取数据项的URI。 849let uriVar:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 850``` 851 852## settings.getURI<sup>(deprecated)</sup> 853 854getURI(name: string, callback: AsyncCallback\<object>): void 855 856获取数据项的URI。使用callback异步回调。(暂不支持) 857 858> **说明：** 859> 860> 从 API version 7开始支持，从API version 9开始废弃，此接口不再提供代替接口。 861 862**系统能力**：SystemCapability.Applications.Settings.Core 863 864**参数**： 865 866| 参数名 | 类型 | 必填 | 说明 | 867| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 868| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 869| callback | AsyncCallback\<object> | 是 | 回调函数。获取数据项的URI。 | 870 871**示例**： 872 873```js 874settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS, (uri:string) => { 875 console.log(`callback:uri -> ${JSON.stringify(uri)}`) 876}) 877``` 878 879## settings.getURI<sup>(deprecated)</sup> 880 881getURI(name: string): Promise\<object> 882 883获取数据项的URI。使用Promise异步回调。(暂不支持) 884 885> **说明：** 886> 887> 从 API version 7开始支持，从API version 9开始废弃，此接口不再提供代替接口。 888 889**系统能力**：SystemCapability.Applications.Settings.Core 890 891**参数**： 892 893| 参数名 | 类型 | 必填 | 说明 | 894| ------ | ------ | ---- | ------------------------------------------------------------ | 895| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 896 897**返回值**： 898 899| 类型 | 说明 | 900| ---------------- | ------------------------------------ | 901| Promise\<object> | Promise对象。返回获取的数据项的URI。 | 902 903**示例**： 904 905```js 906settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS).then((uri:string) => { 907 console.log(`promise:uri -> ${JSON.stringify(uri)}`) 908}) 909``` 910 911 912 913## settings.getValue<sup>(deprecated)</sup> 914 915getValue(dataAbilityHelper: DataAbilityHelper, name: string, callback: AsyncCallback\<object>): void 916 917获取数据库中指定数据项的值。使用callback异步回调。 918 919> **说明：** 920> 921> 从 API version 7开始支持，从API version 9开始废弃，建议使用[getValue()](#settingsgetvalue10)替代。 922 923**模型约束**：此接口仅可在FA模型下使用。 924 925**系统能力**：SystemCapability.Applications.Settings.Core 926 927**参数**： 928 929| 参数名 | 类型 | 必填 | 说明 | 930| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 931| dataAbilityHelper | [DataAbilityHelper](../apis-ability-kit/js-apis-inner-ability-dataAbilityHelper.md) | 是 | 数据管理辅助类。 | 932| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 933| callback | AsyncCallback\<object> | 是 | 使用callback方式获取数据项的值。 | 934 935**示例**： 936 937```js 938import featureAbility from '@ohos.ability.featureAbility'; 939 940let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 941let helper = featureAbility.acquireDataAbilityHelper(uri); 942settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, (err:Error, value:string) => { 943 if (err) { 944 console.error(`Failed to get the setting. ${err.message} `); 945 return; 946 } 947 console.log(`callback:value -> ${JSON.stringify(value)}`) 948}); 949``` 950 951## settings.getValue<sup>(deprecated)</sup> 952 953getValue(dataAbilityHelper: DataAbilityHelper, name: string): Promise\<object> 954 955获取数据库中指定数据项的值。使用Promise异步回调。 956 957> **说明：** 958> 959> 从 API version 7开始支持，从API version 9开始废弃，建议使用[getValue()](#settingsgetvalue10-1)替代。 960 961**模型约束**：此接口仅可在FA模型下使用。 962 963**系统能力**：SystemCapability.Applications.Settings.Core 964 965**参数**： 966 967| 参数名 | 类型 | 必填 | 说明 | 968| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 969| dataAbilityHelper | [DataAbilityHelper](../apis-ability-kit/js-apis-inner-ability-dataAbilityHelper.md) | 是 | 数据管理辅助类。 | 970| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 971 972**返回值**： 973 974| 类型 | 说明 | 975| ---------------- | ----------------------------------- | 976| Promise\<object> | Promise对象。返回获得的数据项的值。 | 977 978**示例**： 979 980```js 981import featureAbility from '@ohos.ability.featureAbility'; 982 983let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 984let helper = featureAbility.acquireDataAbilityHelper(uri); 985settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value:string) => { 986 console.log(`promise:value -> ${JSON.stringify(value)}`) 987}); 988``` 989 990## settings.getValueSync<sup>(deprecated)</sup> 991 992getValueSync(dataAbilityHelper: DataAbilityHelper, name: string, defValue: string): string 993 994获取数据项的值。此方法相较getValue为同步方法。 995 996> **说明：** 997> 998> 从 API version 8开始支持，从API version 9开始废弃，建议使用[getValueSync()](#settingsgetvaluesync10)替代。 999 1000**模型约束**：此接口仅可在FA模型下使用。 1001 1002**系统能力**：SystemCapability.Applications.Settings.Core 1003 1004**参数**： 1005 1006| 参数名 | 类型 | 必填 | 说明 | 1007| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1008| dataAbilityHelper | [DataAbilityHelper](../apis-ability-kit/js-apis-inner-ability-dataAbilityHelper.md) | 是 | 数据管理辅助类。 | 1009| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 1010| defValue | string | 是 | 默认值。由开发者设置，当未从数据库中查询到该数据时，表示返回该默认值。 | 1011 1012**返回值**： 1013 1014| 类型 | 说明 | 1015| ------ | ---------------- | 1016| string | 返回数据项的值。 | 1017 1018**示例**： 1019 1020```js 1021import featureAbility from '@ohos.ability.featureAbility'; 1022 1023// 获取数据项亮度的值(该数据项在数据库中已存在)。 1024let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 1025let helper = featureAbility.acquireDataAbilityHelper(uri); 1026let value:string = settings.getValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '10'); 1027``` 1028 1029## settings.setValueSync<sup>(deprecated)</sup> 1030 1031setValueSync(dataAbilityHelper: DataAbilityHelper, name: string, value: string): boolean 1032 1033设置数据项的值。此方法相较setValue为同步方法。 1034 1035- 如果数据库中已经存在该数据项，则setValueSync方法将更新该数据项的值。 1036- 如果数据库中尚未存在该数据项，则setValueSync方法将向数据库中插入该数据项。 1037 1038> **说明：** 1039> 1040> 从 API version 8开始支持，从API version 9开始废弃，建议使用[setValueSync()](#settingssetvaluesync10)替代。 1041 1042**模型约束**：此接口仅可在FA模型下使用。 1043 1044**需要权限**：ohos.permission.MANAGE_SETTINGS，该权限仅系统应用可用。 1045 1046**系统能力**：SystemCapability.Applications.Settings.Core 1047 1048**参数**： 1049 1050| 参数名 | 类型 | 必填 | 说明 | 1051| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1052| dataAbilityHelper | [DataAbilityHelper](../apis-ability-kit/js-apis-inner-ability-dataAbilityHelper.md) | 是 | 数据管理辅助类。 | 1053| name | string | 是 | 数据项的名称。数据项名称分为以下两种。<br>- 上述任意一个数据库中已存在的数据项。<br>- 开发者自行添加的数据项。 | 1054| value | string | 是 | 数据项的具体数值。取值范围随业务变动。 | 1055 1056**返回值**： 1057 1058| 类型 | 说明 | 1059| ------- | ------------------------------------------------------------ | 1060| boolean | 返回设置数据项的值是否成功的结果。true表示设置成功，false表示设置失败。 | 1061 1062**示例**： 1063 1064```js 1065import featureAbility from '@ohos.ability.featureAbility'; 1066 1067// 更新数据项亮度的值(该数据项在数据库中已存在，故setValueSync方法将更新该数据项的值)。 1068let uri:string = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); 1069let helper = featureAbility.acquireDataAbilityHelper(uri); 1070let ret:string = settings.setValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '100'); 1071```