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