Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
You need to sign in or sign up before continuing.
未验证 提交 ebe29125 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!7874 master - 首选项API及指南优化：需同步翻译 

Merge pull request !7874 from 葛亚芳/master
上级 8b42c44a 90eade70
隐藏空白更改
内联 并排
Showing with 336 addition and 311 deletion
zh-cn/application-dev/database/database-preference-guidelines.md
浏览文件 @ ebe29125
...@@ -6,11 +6,17 @@ ...@@ -6,11 +6,17 @@
## 场景介绍 ## 场景介绍
首选项功能通常用于保存应用的一些常用配置信息，并不适合需要存储大量数据和频繁改变数据的场景。应用的数据保存在文件中，这些文件可以持久化地存储在设备上。需要注意的是，应用访问的实例包含文件所有数据，这些数据会一直加载在设备的内存中，直到应用主动从内存中将其移除前，应用都可以通过Preferences API进行相关数据操作。 首选项功能通常用于保存应用的一些常用配置信息，并不适合需要存储大量数据和频繁改变数据的场景。应用的数据保存在文件中，这些文件可以持久化地存储在设备上。
需要注意的是，应用访问的实例包含文件所有数据，这些数据会一直加载在设备的内存中，直到应用主动从内存中将其移除前，应用都可以通过Preferences API进行相关数据操作。
## 接口说明 ## 接口说明
首选项为应用提供key-value键值型的文件数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型。更多首选项相关接口，请见[首选项API](../reference/apis/js-apis-data-preferences.md)。 首选项为应用提供Key-Value键值型的文件数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。
数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。
更多首选项相关接口，请见[首选项API](../reference/apis/js-apis-data-preferences.md)。
### 创建存储实例 ### 创建存储实例
...@@ -18,29 +24,26 @@ ...@@ -18,29 +24,26 @@
**表1** 首选项实例创建接口 **表1** 首选项实例创建接口
| 包名 | 接口名 | 描述 | | 包名 | 接口名 | 描述 |
| ----------------- | ------------------------------------------- | ------------------------------------------- | | --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| ohos.data.preferences | getPreferences(context: Context, name: string): Promise\<Preferences> | 读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作。 | | ohos.data.preferences | getPreferences(context: Context, name: string): Promise\<Preferences> | 读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作。 |
### 存入数据 ### 存取数据
通过put系列方法，可以增加或修改Preferences实例中的数据。 通过put系列方法，可以增加或修改Preferences实例中的数据。
**表2** 首选项存入接口
| 类名 | 接口名 | 描述 |
| ------- | -------------------------------------------------- | ----------------------------------------------- |
| Preferences | put(key: string, value: ValueType): Promise\<void> | 支持值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据存入。 |
### 读取数据
通过调用get系列方法，可以读取Preferences中的数据。 通过调用get系列方法，可以读取Preferences中的数据。
**表3** 首选项读取接口 通过调用getAll系列方法，可以获取Preferences中包含所有键值的Object对象。
**表2** 首选项存取接口
| 类名 | 接口名 | 描述 | | 类名 | 接口名 | 描述 |
| ------- | ---------------------------------------------------------- | ----------------------------------------------- | | ----------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
| Preferences | put(key: string, value: ValueType): Promise\<void> | 支持存入值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据。 |
| Preferences | get(key: string, defValue: ValueType): Promise\<ValueType> | 支持获取值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据。 | | Preferences | get(key: string, defValue: ValueType): Promise\<ValueType> | 支持获取值为number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型的数据。 |
| Preferences | getAll(): Promise<Object> | 支持获取含有所有键值的Object对象。 |
### 数据持久化 ### 数据持久化
...@@ -48,18 +51,18 @@ ...@@ -48,18 +51,18 @@
**表4** 首选项持久化接口 **表4** 首选项持久化接口
| 类名 | 接口名 | 描述 | | 类名 | 接口名 | 描述 |
| ------- | ----------------------- | --------------------------------------- | | ----------- | ----------------------- | ------------------------------------------- |
| Preferences | flush(): Promise\<void> | 将Preferences实例通过异步线程回写入文件中。 | | Preferences | flush(): Promise\<void> | 将Preferences实例通过异步线程回写入文件中。 |
### 订阅数据变化 ### 订阅数据变化
订阅数据变更者类，订阅的key的值发生变更后，在执行flush方法后，会执行callback回调。 订阅数据变更者类，订阅的Key的值发生变更后，在执行flush方法后，会触发callback回调。
**表5** 首选项变化订阅接口 **表5** 首选项变化订阅接口
| 类名 | 接口名 | 描述 | | 类名 | 接口名 | 描述 |
| ------- | ------------------------------------------------------------ | -------------- | | ----------- | ------------------------------------------------------------ | -------------- |
| Preferences | on(type: 'change', callback: Callback<{ key : string }>): void | 订阅数据变化。 | | Preferences | on(type: 'change', callback: Callback<{ key : string }>): void | 订阅数据变化。 |
| Preferences | off(type: 'change', callback: Callback<{ key : string }>): void | 注销订阅。 | | Preferences | off(type: 'change', callback: Callback<{ key : string }>): void | 注销订阅。 |
...@@ -69,57 +72,57 @@ ...@@ -69,57 +72,57 @@
**表6** 首选项删除接口 **表6** 首选项删除接口
| 包名 | 接口名 | 描述 | | 包名 | 接口名 | 描述 |
| ----------------- | ---------------------------------------------------- | ------------------------------------------------------------ | | --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| ohos.data.preferences | deletePreferences(context: Context, name: string): Promise\<void>; | 从缓存中移除已加载的Preferences对象，同时从设备上删除对应的文件。 | | ohos.data.preferences | deletePreferences(context: Context, name: string): Promise\<void> | 从缓存中移除已加载的Preferences对象，同时从设备上删除对应的文件。 |
| ohos.data.preferences | removePreferencesFromCache(context: Context, name: string): Promise\<void>; | 仅从缓存中移除已加载的Preferences对象，主要用于释放内存。 | ohos.data.preferences | removePreferencesFromCache(context: Context, name: string): Promise\<void> | 仅从缓存中移除已加载的Preferences对象，主要用于释放内存。 |
## 开发步骤 ## 开发步骤
1. 准备工作，导入@ohos.data.preferences以及相关的模块到开发环境。 1. 准备工作，导入@ohos.data.preferences以及相关的模块到开发环境。
```js ```js
import data_preferences from '@ohos.data.preferences' import data_preferences from '@ohos.data.preferences';
``` ```
2. 获取Preferences实例。 2. 获取Preferences实例。
读取指定文件，将数据加载到Preferences实例，用于数据操作。 读取指定文件，将数据加载到Preferences实例，用于数据操作。
```js ```js
let promise = data_preferences.getPreferences(this.context, 'mystore') let promise = data_preferences.getPreferences(this.context, 'mystore');
``` ```
3. 存入数据。 3. 存入数据。
使用Preferences put方法保存数据到缓存的实例中。 使用put方法保存数据到缓存的实例中。
```js ```js
promise.then((preferences) => { promise.then((preferences) => {
let putPromise = preferences.put('startup', 'auto') let putPromise = preferences.put('startup', 'auto');
putPromise.then(() => { putPromise.then(() => {
console.info("Put the value of startup successfully.") console.info("Succeeded in putting the value of 'startup'.");
}).catch((err) => { }).catch((err) => {
console.info("Put the value of startup failed with err: " + err) console.info("Failed to put the value of 'startup'. Cause: " + err);
}) })
}).catch((err) => { }).catch((err) => {
console.info("Get the storage failed") console.info("Failed to get preferences.");
}) })
``` ```
4. 读取数据。 4. 读取数据。
使用Preferences get方法读取数据。 使用get方法读取数据。
```js ```js
promise.then((preferences) => { promise.then((preferences) => {
let getPromise = preferences.get('startup', 'default') let getPromise = preferences.get('startup', 'default');
getPromise.then((value) => { getPromise.then((value) => {
console.info("The value of startup is " + value) console.info("The value of 'startup' is " + value);
}).catch((err) => { }).catch((err) => {
console.info("Get the value of startup failed with err: " + err) console.info("Failed to get the value of 'startup'. Cause: " + err);
}) })
}).catch((err) => { }).catch((err) => {
console.info("Get the storage failed")}) console.info("Failed to get preferences.")});
``` ```
5. 数据持久化。 5. 数据持久化。
...@@ -132,25 +135,25 @@ ...@@ -132,25 +135,25 @@
6. 订阅数据变化。 6. 订阅数据变化。
应用订阅数据变化需要指定observer作为回调方法。订阅的key的值发生变更后，当执行flush方法时，observer被触发回调。 应用订阅数据变化需要指定observer作为回调方法。订阅的Key的值发生变更后，当执行flush方法时，observer被触发回调。
```js ```js
var observer = function (key) { var observer = function (key) {
console.info("The key of " + key + " changed.") console.info("The key" + key + " changed.");
} }
preferences.on('change', observer) preferences.on('change', observer);
preferences.put('startup', 'auto', function (err) { preferences.put('startup', 'auto', function (err) {
if (err) { if (err) {
console.info("Put the value of startup failed with err: " + err) console.info("Failed to put the value of 'startup'. Cause: " + err);
return return;
} }
console.info("Put the value of startup successfully.") console.info("Succeeded in putting the value of 'startup'.");
preferences.flush(function (err) { preferences.flush(function (err) {
if (err) { if (err) {
console.info("Flush to file failed with err: " + err) console.info("Failed to flush. Cause: " + err);
return return;
} }
console.info("Flushed to file successfully.") // observer will be called. console.info("Succeeded in flushing."); // observer will be called.
}) })
}) })
``` ```
...@@ -160,13 +163,14 @@ ...@@ -160,13 +163,14 @@
使用deletePreferences方法从内存中移除指定文件对应的Preferences单实例，并删除指定文件及其备份文件、损坏文件。删除指定文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。删除后，数据及文件将不可恢复。 使用deletePreferences方法从内存中移除指定文件对应的Preferences单实例，并删除指定文件及其备份文件、损坏文件。删除指定文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。删除后，数据及文件将不可恢复。
```js ```js
let proDelete = data_preferences.deletePreferences(context, 'mystore') let proDelete = data_preferences.deletePreferences(context, 'mystore');
proDelete.then(() => { proDelete.then(() => {
console.info("Deleted successfully.") console.info("Succeeded in deleting.");
}).catch((err) => { }).catch((err) => {
console.info("Deleted failed with err: " + err) console.info("Failed to delete. Cause: " + err);
}) })
``` ```
## 相关实例 ## 相关实例
针对首选项开发，有以下相关实例可供参考： 针对首选项开发，有以下相关实例可供参考：
- [`Preferences`：首选项（eTS）（API9）](https://gitee.com/openharmony/app_samples/tree/master/data/Preferences)
- [`Preferences`：首选项（eTS）（API9）](https://gitee.com/openharmony/app_samples/tree/master/data/Preferences)
\ No newline at end of file
zh-cn/application-dev/database/database-preference-overview.md
浏览文件 @ ebe29125
# 首选项概述 # 首选项概述
首选项适用于对Key-Value结构的数据进行存取和持久化操作。应用获取某个Preferences对象后，该存储对象中的数据将会被缓存在内存中，以便应用获得更快的数据存取速度。应用也可以将缓存的数据再次写回文本文件中进行持久化存储，由于文件读写将产生不可避免的系统资源开销，建议应用减少对持久化文件的读写频率。 首选项Preferences，适用于对`Key-Value`结构的数据进行存取和持久化操作。
应用获取某个`Preferences`对象后，该存储对象中的数据将会被缓存在内存中，以便应用获得更快的数据存取速度。
应用也可以将缓存的数据再次写回文本文件中进行持久化存储，由于文件读写将产生不可避免的系统资源开销，建议应用降低对持久化文件的读写频率。
## 基本概念 ## 基本概念
- **Key-Value数据结构** - **Key-Value数据结构**
一种键值结构数据类型。Key是不重复的关键字，Value是数据值。 一种键值型的数据结构。`Key`是不重复的关键字，`Value`是数据值。
- **非关系型数据库** - **非关系型数据库**
区别于关系数据库，不保证遵循ACID（Atomicity, Consistency, Isolation and Durability）特性，不采用关系模型来组织数据，数据之间无关系。 区别于关系数据库，不保证遵循ACID（Atomic、Consistency、Isolation及Durability）特性，不采用关系模型来组织数据，数据之间无关系。比如，以`Key-Value`数据结构组成的数据库。
## 运作机制 ## 运作机制
1. 应用通过指定首选项持久化文件将其中的数据加载到Preferences实例，系统会通过静态容器将该实例存储在内存中，同一应用或进程中每个文件仅存在一个Preferences实例，直到应用主动从内存中移除该实例或者删除该首选项持久化文件。 1. 应用通过指定首选项持久化文件将其中的数据加载到`Preferences`实例，系统会通过静态容器将该实例存储在内存中，同一应用或进程中每个文件仅存在一个`Preferences`实例，直到应用主动从内存中移除该实例或者删除该首选项持久化文件。
2. 应用获取到首选项持久化文件对应的实例后，可以从Preferences实例中读取数据，或者将数据存入Preferences实例中。通过调用flush方法可以将Preferences实例中的数据回写到文件里。 2. 应用获取到首选项持久化文件对应的实例后，可以从`Preferences`实例中读取数据，或者将数据存入`Preferences`实例中。通过调用flush方法可以将`Preferences`实例中的数据回写到文件里。
**图1** 首选项运作机制 **图1** 首选项运作机制
...@@ -23,6 +27,6 @@ ...@@ -23,6 +27,6 @@
## 约束与限制 ## 约束与限制
- 因Preferences实例会加载到内存中，建议存储的数据不超过一万条，并及时清理不再使用的实例，以便减少非内存开销。 - 因`Preferences`实例会加载到内存中，建议存储的数据不超过一万条，并注意及时清理不再使用的实例，以便减少非内存开销。
- 数据中的key为string类型，要求非空且字符长度不超过80字节。 - 数据中的`Key`为`string`类型，要求非空且字符长度不超过80个字节。
- 当数据中的value为string类型时，允许为空，字符长度不超过8192字节。 - 当数据中的`Value`为`string`类型时，允许为空，字符长度不超过8192个字节。
\ No newline at end of file
zh-cn/application-dev/reference/apis/js-apis-data-preferences.md
浏览文件 @ ebe29125
# 首选项 # 首选项
首选项为应用提供key-value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。 首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。
数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。
> **说明：** > **说明：**
>
> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块 ## 导入模块
```ts ```js
import data_preferences from '@ohos.data.preferences'; import data_preferences from '@ohos.data.preferences';
``` ```
## 常量 ## 常量
**系统能力：** 以下各项对应的系统能力均为SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
| 名称 | 参数类型 | 可读 | 可写 | 说明 | | 名称 | 参数类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- | | ---------------- | -------- | ---- | ---- | --------------------------------------- |
| MAX_KEY_LENGTH | string | 是 | 否 | key的最大长度限制，需小于80字节。 | | MAX_KEY_LENGTH | string | 是 | 否 | Key的最大长度限制，需小于80个字节。 |
| MAX_VALUE_LENGTH | string | 是 | 否 | value的最大长度限制，需小于8192字节。 | | MAX_VALUE_LENGTH | string | 是 | 否 | Value的最大长度限制，需小于8192个字节。 |
## data_preferences.getPreferences ## data_preferences.getPreferences
getPreferences(context: Context, name: string, callback: AsyncCallback&lt;Preferences&gt;): void getPreferences(context: Context, name: string, callback: AsyncCallback&lt;Preferences&gt;): void
读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作，该方法使用callback方式作为异步方法。 读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | 参数名 | 类型 | 必填 | 说明 |
| context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 | | -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ |
| name | string | 是 | 应用程序内部数据存储名称。 | | context | [Context](js-apis-ability-context.md) | 是 | 应用上下文。 |
| callback | AsyncCallback&lt;[Preferences](#preferences)&gt; | 是 | 回调函数。 | | name | string | 是 | 应用程序内部数据存储名称。 |
| callback | AsyncCallback&lt;[Preferences](#preferences)&gt; | 是 | 回调函数。当获取Preferences实例成功，err为undefined，object为获取的Preferences实例；否则err为错误码。 |
**示例：** **示例：**
```ts
data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { ```js
var preferences = null;
data_preferences.getPreferences(this.context, 'mystore', function (err, object) {
if (err) { if (err) {
console.info("Get preferences failed.") console.info("Failed to get preferences. Cause: " + err);
return; return;
} }
console.info("Get preferences successfully.") preferences = object;
console.info("Succeeded in getting preferences.");
}) })
``` ```
...@@ -55,28 +61,31 @@ data_preferences.getPreferences(this.context, 'mystore', function (err, preferen ...@@ -55,28 +61,31 @@ data_preferences.getPreferences(this.context, 'mystore', function (err, preferen
getPreferences(context: Context, name: string): Promise&lt;Preferences&gt; getPreferences(context: Context, name: string): Promise&lt;Preferences&gt;
读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作，该方法使用Promise方式作为异步方法。 读取指定首选项持久化文件，将数据加载到Preferences实例，用于数据操作，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | ------- | ------------------------------------- | ---- | -------------------------- |
| context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 | | context | [Context](js-apis-ability-context.md) | 是 | 应用上下文。 |
| name | string | 是 | 应用程序内部数据存储名称。 | | name | string | 是 | 应用程序内部数据存储名称。 |
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | ------------------------------------------ | ---------------------------------- |
| Promise&lt;[Preferences](#preferences)&gt; | Promise实例，用于异步获取结果。 | | Promise&lt;[Preferences](#preferences)&gt; | Promise对象，返回Preferences实例。 |
**示例：** **示例：**
```ts
```js
var preferences = null;
let promise = data_preferences.getPreferences(this.context, 'mystore') let promise = data_preferences.getPreferences(this.context, 'mystore')
promise.then((preferences) => { promise.then((object) => {
console.info("Get preferences successfully.") preferences = object;
console.info("Succeeded in getting preferences.");
}).catch((err) => { }).catch((err) => {
console.info("Get preferences failed.") console.info("Failed to get preferences. Cause: " + err);
}) })
``` ```
...@@ -85,26 +94,27 @@ promise.then((preferences) => { ...@@ -85,26 +94,27 @@ promise.then((preferences) => {
deletePreferences(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void deletePreferences(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void
从内存中移除指定首选项持久化文件对应的Preferences单实例，并删除指定文件及其备份文件和损坏文件。 从内存中移除指定首选项持久化文件对应的Preferences单实例，并删除指定文件及其备份文件和损坏文件，使用callback异步回调。
删除指定首选项持久化文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题，该方法使用callback方式作为异步方法。
删除指定首选项持久化文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | ------------------------------------- | ---- | ---------------------------------------------------- |
| context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 | | context | [Context](js-apis-ability-context.md) | 是 | 应用上下文。 |
| name | string | 是 | 应用程序内部数据存储名称。 | | name | string | 是 | 应用程序内部数据存储名称。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 | | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当移除成功，err为undefined，否则为错误码。 |
**示例：** **示例：**
```ts ```js
data_preferences.deletePreferences(this.context, 'mystore', function (err) { data_preferences.deletePreferences(this.context, 'mystore', function (err) {
if (err) { if (err) {
console.info("Deleted preferences failed, err: " + err) console.info("Failed to delete preferences. Cause: " + err);
return return
} }
console.info("Deleted preferences successfully.") console.info("Succeeded in deleting preferences." );
}) })
``` ```
...@@ -113,29 +123,30 @@ data_preferences.deletePreferences(this.context, 'mystore', function (err) { ...@@ -113,29 +123,30 @@ data_preferences.deletePreferences(this.context, 'mystore', function (err) {
deletePreferences(context: Context, name: string): Promise&lt;void&gt; deletePreferences(context: Context, name: string): Promise&lt;void&gt;
从内存中移除指定首选项持久化文件对应的Preferences单实例，并删除指定文件及其备份文件和损坏文件。 从内存中移除指定首选项持久化文件对应的Preferences单实例，并删除指定文件及其备份文件和损坏文件，使用Promise异步回调。
删除指定首选项持久化文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题，该方法使用Promise方式作为异步方法。
删除指定首选项持久化文件时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | ------- | ------------------------------------- | ---- | -------------------------- |
| context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 | | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
| name | string | 是 | 应用程序内部数据存储名称。 | | name | string | 是 | 应用程序内部数据存储名称。 |
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise实例，用于异步获取结果。 | | Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例：** **示例：**
```ts ```js
let promise = data_preferences.deletePreferences(this.context, 'mystore') let promise = data_preferences.deletePreferences(this.context, 'mystore')
promise.then(() => { promise.then(() => {
console.info("Deleted preferences successfully.") console.info("Succeeded in deleting preferences.");
}).catch((err) => { }).catch((err) => {
console.info("Deleted preferences failed, err: " + err) console.info("Failed to delete preferences. Cause: " + err);
}) })
``` ```
...@@ -144,27 +155,27 @@ promise.then(() => { ...@@ -144,27 +155,27 @@ promise.then(() => {
removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void
从内存中移除指定首选项持久化文件对应的Preferences单实例。 从内存中移除指定首选项持久化文件对应的Preferences单实例，使用callback异步回调。
移除Preferences单实例时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题，该方法使用callback方式作为异步方法。 移除Preferences单实例时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | ------------------------------------- | ---- | ---------------------------------------------------- |
| context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 | | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
| name | string | 是 | 应用程序内部数据存储名称。 | | name | string | 是 | 应用程序内部数据存储名称。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 | | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当移除成功，err为undefined，否则为错误码。 |
**示例：** **示例：**
```ts ```js
data_preferences.removePreferencesFromCache(this.context, 'mystore', function (err) { data_preferences.removePreferencesFromCache(this.context, 'mystore', function (err) {
if (err) { if (err) {
console.info("Removed preferences from cache failed, err: " + err) console.info("Failed to remove preferences. Cause: " + err);
return return;
} }
console.info("Removed preferences from cache successfully.") console.info("Succeeded in removing preferences.");
}) })
``` ```
...@@ -173,62 +184,65 @@ data_preferences.removePreferencesFromCache(this.context, 'mystore', function (e ...@@ -173,62 +184,65 @@ data_preferences.removePreferencesFromCache(this.context, 'mystore', function (e
removePreferencesFromCache(context: Context, name: string): Promise&lt;void&gt; removePreferencesFromCache(context: Context, name: string): Promise&lt;void&gt;
从内存中移除指定首选项持久化文件对应的Preferences单实例。 从内存中移除指定首选项持久化文件对应的Preferences单实例，使用Promise异步回调。
移除Preferences单实例时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题，该方法使用Promise方式作为异步方法。 移除Preferences单实例时，应用不允许再使用该实例进行数据操作，否则会出现数据一致性问题。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | ------- | ------------------------------------- | ---- | -------------------------- |
| context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 | | context | [Context](js-apis-ability-context.md) | 是 | 应用程序或功能的上下文。 |
| name | string | 是 | 应用程序内部数据存储名称。 | | name | string | 是 | 应用程序内部数据存储名称。 |
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise实例，用于异步获取结果。 | | Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例：** **示例：**
```ts ```js
let promise = data_preferences.removePreferencesFromCache(this.context, 'mystore') let promise = data_preferences.removePreferencesFromCache(this.context, 'mystore')
promise.then(() => { promise.then(() => {
console.info("Removed preferences from cache successfully.") console.info("Succeeded in removing preferences.");
}).catch((err) => { }).catch((err) => {
console.info("Removed preferences from cache failed, err: " + err) console.info("Failed to remove preferences. Cause: " + err);
}) })
``` ```
## Preferences ## Preferences
提供获取和修改存储数据的接口。 存储实例，提供获取和修改存储数据的接口。
下列接口都需先使用[data_preferences.getPreferences](#data_preferencesgetpreferences)获取到Preferences实例，再通过此实例调用对应接口。
### get ### get
get(key: string, defValue: ValueType, callback: AsyncCallback&lt;ValueType&gt;): void get(key: string, defValue: ValueType, callback: AsyncCallback&lt;ValueType&gt;): void
获取键对应的值，如果值为null或者非默认值类型，返回默认数据，该方法使用callback方式作为异步方法。 获取键对应的值，如果值为null或者非默认值类型，返回默认数据，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| key | string | 是 | 要获取的存储key名称，不能为空。 | | key | string | 是 | 要获取的存储Key名称，不能为空。 |
| defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>。 | | defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型。 |
| callback | AsyncCallback&lt;ValueType&gt; | 是 | 回调函数。 | | callback | AsyncCallback&lt;[ValueType](#valuetype)&gt; | 是 | 回调函数。当获取成功时，err为undefined，data为键对应的值；否则err为错误码。 |
**示例：** **示例：**
```ts
preferences.get('startup', 'default', function(err, value) { ```js
preferences.get('startup', 'default', function(err, data) {
if (err) { if (err) {
console.info("Get value of startup failed, err: " + err) console.info("Failed to get value of 'startup'. Cause: " + err);
return return;
} }
console.info("Get value of startup is " + value) console.info("Succeeded in getting value of 'startup'. Data： " + data);
}) })
``` ```
...@@ -237,28 +251,29 @@ preferences.get('startup', 'default', function(err, value) { ...@@ -237,28 +251,29 @@ preferences.get('startup', 'default', function(err, value) {
get(key: string, defValue: ValueType): Promise&lt;ValueType&gt; get(key: string, defValue: ValueType): Promise&lt;ValueType&gt;
获取键对应的值，如果值为null或者非默认值类型，返回默认数据，该方法使用Promise方式作为异步方法。 获取键对应的值，如果值为null或者非默认值类型，返回默认数据，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
- **参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| key | string | 是 | 要获取的存储key名称，不能为空。 | | key | string | 是 | 要获取的存储Key名称，不能为空。 |
| defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>。 | | defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型。 |
**返回值：** **返回值：**
| 类型 | 说明 |
| -------- | -------- | | 类型 | 说明 |
| Promise&lt;ValueType&gt; | Promise实例，用于异步获取结果。 | | ----------------------------------- | ----------------------------- |
| Promise<[ValueType](#valuetype)&gt; | Promise对象，返回键对应的值。 |
**示例：** **示例：**
```ts ```js
let promise = preferences.get('startup', 'default') let promise = preferences.get('startup', 'default');
promise.then((value) => { promise.then((data) => {
console.info("Get value of startup is " + value) console.info("Succeeded in getting value of 'startup'. Data: " + data);
}).catch((err) => { }).catch((err) => {
console.info("Get value of startup failed, err: " + err) console.info("Failed to get value of 'startup'. Cause: " + err);
}) })
``` ```
...@@ -266,25 +281,26 @@ promise.then((value) => { ...@@ -266,25 +281,26 @@ promise.then((value) => {
getAll(callback: AsyncCallback&lt;Object&gt;): void; getAll(callback: AsyncCallback&lt;Object&gt;): void;
返回含有所有键值的Object对象。 获取含有所有键值的Object对象。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;Object&gt; | 是 | 回调函数。返回含有所有键值的Object对象。 | | callback | AsyncCallback&lt;Object&gt; | 是 | 回调函数。当获取成功，err为undefined，value为含有所有键值的Object对象；否则err为错误码。 |
**示例：** **示例：**
```ts
```js
preferences.getAll(function (err, value) { preferences.getAll(function (err, value) {
if (err) { if (err) {
console.info("getAll failed, err: " + err) console.info("Failed to get all key-values. Cause: " + err);
return return;
} }
let keys = Object.keys(value) let allKeys = Object.keys(value);
console.info('getAll keys = ' + keys) console.info("getAll keys = " + allKeys);
console.info("getAll object = " + JSON.stringify(value)) console.info("getAll object = " + JSON.stringify(value));
}); });
``` ```
...@@ -293,24 +309,24 @@ preferences.getAll(function (err, value) { ...@@ -293,24 +309,24 @@ preferences.getAll(function (err, value) {
getAll(): Promise&lt;Object&gt; getAll(): Promise&lt;Object&gt;
返回含有所有键值的Object对象。 获取含有所有键值的Object对象。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | --------------------- | ------------------------------------------- |
| Promise&lt;Object&gt; | Promise对象。返回含有所有键值的Object对象。 | | Promise&lt;Object&gt; | Promise对象，返回含有所有键值的Object对象。 |
**示例：** **示例：**
```ts ```js
let promise = preferences.getAll() let promise = preferences.getAll();
promise.then((value) => { promise.then((value) => {
let keys = Object.keys(value) let allKeys = Object.keys(value);
console.info('getAll keys = ' + keys) console.info('getAll keys = ' + allKeys);
console.info("getAll object = " + JSON.stringify(value)) console.info("getAll object = " + JSON.stringify(value));
}).catch((err) => { }).catch((err) => {
console.info("getAll failed, err: " + err) console.info("Failed to get all key-values. Cause: " + err);
}) })
``` ```
...@@ -318,25 +334,25 @@ promise.then((value) => { ...@@ -318,25 +334,25 @@ promise.then((value) => {
put(key: string, value: ValueType, callback: AsyncCallback&lt;void&gt;): void put(key: string, value: ValueType, callback: AsyncCallback&lt;void&gt;): void
首先获取指定首选项持久化文件对应的Preferences实例，然后借助Preferences API将数据写入Preferences实例，通过flush或者flushSync将Preferences实例持久化，该方法使用callback方式作为异步方法。 将数据写入Preferences实例，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | ------------------------- | ---- | ------------------------------------------------------------ |
| key | string | 是 | 要修改的存储的key，不能为空。 | | key | string | 是 | 要修改的存储的Key，不能为空。 |
| value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>。 | | value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 | | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当数据写入成功，err为undefined；否则为错误码。 |
**示例：** **示例：**
```ts ```js
preferences.put('startup', 'auto', function (err) { preferences.put('startup', 'auto', function (err) {
if (err) { if (err) {
console.info("Put value of startup failed, err: " + err) console.info("Failed to put value of 'startup'. Cause: " + err);
return return;
} }
console.info("Put value of startup successfully.") console.info("Succeeded in putting value of 'startup'.");
}) })
``` ```
...@@ -345,28 +361,28 @@ preferences.put('startup', 'auto', function (err) { ...@@ -345,28 +361,28 @@ preferences.put('startup', 'auto', function (err) {
put(key: string, value: ValueType): Promise&lt;void&gt; put(key: string, value: ValueType): Promise&lt;void&gt;
首先获取指定首选项持久化文件对应的Preferences实例，然后借助Preferences API将数据写入Preferences实例，通过flush或者flushSync将Preferences实例持久化，该方法使用Promise方式作为异步方法。 将数据写入Preferences实例，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | ------ | ----------------------- | ---- | ------------------------------------------------------------ |
| key | string | 是 | 要修改的存储的key，不能为空。 | | key | string | 是 | 要修改的存储的Key，不能为空。 |
| value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>。 | | value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型。 |
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise实例，用于异步处理。 | | Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例：** **示例：**
```ts ```js
let promise = preferences.put('startup', 'auto') let promise = preferences.put('startup', 'auto');
promise.then(() => { promise.then(() => {
console.info("Put value of startup successfully.") console.info("Succeeded in putting value of 'startup'.");
}).catch((err) => { }).catch((err) => {
console.info("Put value of startup failed, err: " + err) console.info("Failed to put value of 'startup'. Cause: " + err));
}) })
``` ```
...@@ -375,27 +391,27 @@ promise.then(() => { ...@@ -375,27 +391,27 @@ promise.then(() => {
has(key: string, callback: AsyncCallback&lt;boolean&gt;): void has(key: string, callback: AsyncCallback&lt;boolean&gt;): void
检查存储对象是否包含名为给定key的存储键值对，该方法使用callback方式作为异步方法。 检查存储对象是否包含名为给定Key的存储键值对，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| key | string | 是 | 要检查的存储key名称，不能为空。 | | key | string | 是 | 要检查的存储key名称，不能为空。 |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数。返回存储对象是否包含给定key的存储键值对，true表示存在，false表示不存在。 | | callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数。返回存储对象是否包含给定key的存储键值对，true表示存在，false表示不存在。 |
**示例：** **示例：**
```ts ```js
preferences.has('startup', function (err, isExist) { preferences.has('startup', function (err, isExist) {
if (err) { if (err) {
console.info("Check the key of startup failed, err: " + err) console.info("Failed to check the key 'startup'. Cause: " + err);
return return;
} }
if (isExist) { if (isExist) {
console.info("The key of startup is contained.") console.info("The key 'startup' is contained.");
} else { } else {
console.info("The key of startup dose not contain.") console.info("The key 'startup' dose not contain.");
} }
}) })
``` ```
...@@ -405,31 +421,32 @@ preferences.has('startup', function (err, isExist) { ...@@ -405,31 +421,32 @@ preferences.has('startup', function (err, isExist) {
has(key: string): Promise&lt;boolean&gt; has(key: string): Promise&lt;boolean&gt;
检查存储对象是否包含名为给定key的存储键值对，该方法使用Promise方式作为异步方法。 检查存储对象是否包含名为给定Key的存储键值对，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | ------ | ------ | ---- | ------------------------------- |
| key | string | 是 | 要检查的存储key名称，不能为空。 | | key | string | 是 | 要检查的存储key名称，不能为空。 |
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | ---------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Promise对象。返回存储对象是否包含给定key的存储键值对，true表示存在，false表示不存在。 | | Promise&lt;boolean&gt; | Promise对象。返回存储对象是否包含给定key的存储键值对，true表示存在，false表示不存在。 |
**示例：** **示例：**
```ts
let promise = preferences.has('startup') ```js
let promise = preferences.has('startup');
promise.then((isExist) => { promise.then((isExist) => {
if (isExist) { if (isExist) {
console.info("The key of startup is contained.") console.info("The key 'startup' is contained.");
} else { } else {
console.info("The key of startup dose not contain.") console.info("The key 'startup' dose not contain.");
} }
}).catch((err) => { }).catch((err) => {
console.info("Check the key of startup failed, err: " + err) console.info("Failed to check the key 'startup'. Cause: " + err);
}) })
``` ```
...@@ -438,24 +455,24 @@ promise.then((isExist) => { ...@@ -438,24 +455,24 @@ promise.then((isExist) => {
delete(key: string, callback: AsyncCallback&lt;void&gt;): void delete(key: string, callback: AsyncCallback&lt;void&gt;): void
从存储对象中删除名为给定key的存储键值对，该方法使用callback方式作为异步方法。 从存储对象中删除名为给定Key的存储键值对，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | ------------------------- | ---- | ---------------------------------------------------- |
| key | string | 是 | 要删除的存储key名称，不能为空。 | | key | string | 是 | 要删除的存储Key名称，不能为空。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 | | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当删除成功，err为undefined；否则为错误码。 |
**示例：** **示例：**
```ts ```js
preferences.delete('startup', function (err) { preferences.delete('startup', function (err) {
if (err) { if (err) {
console.info("Delete startup key failed, err: " + err) console.info("Failed to delete the key 'startup'. Cause: " + err);
return return;
} }
console.info("Deleted startup key successfully.") console.info("Succeeded in deleting the key 'startup'.");
}) })
``` ```
...@@ -464,27 +481,27 @@ preferences.delete('startup', function (err) { ...@@ -464,27 +481,27 @@ preferences.delete('startup', function (err) {
delete(key: string): Promise&lt;void&gt; delete(key: string): Promise&lt;void&gt;
从存储对象删除名为给定key的存储键值对，该方法使用Promise方式作为异步方法。 从存储对象删除名为给定Key的存储键值对，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | ------ | ------ | ---- | ------------------------------- |
| key | string | 是 | 要删除的存储key名称，不能为空。 | | key | string | 是 | 要删除的存储key名称，不能为空。 |
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise实例，用于异步处理。 | | Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例：** **示例：**
```ts ```js
let promise = preferences.delete('startup') let promise = preferences.delete('startup');
promise.then(() => { promise.then(() => {
console.info("Deleted startup key successfully.") console.info("Succeeded in deleting the key 'startup'.");
}).catch((err) => { }).catch((err) => {
console.info("Delete startup key failed, err: " + err) console.info("Failed to delete the key 'startup'. Cause: " + err);
}) })
``` ```
...@@ -493,23 +510,23 @@ promise.then(() => { ...@@ -493,23 +510,23 @@ promise.then(() => {
flush(callback: AsyncCallback&lt;void&gt;): void flush(callback: AsyncCallback&lt;void&gt;): void
将当前preferences对象中的修改保存到当前的preferences，并异步存储到首选项持久化文件中，该方法使用callback方式作为异步方法。 将当前preferences对象中的修改保存到当前的preferences，并异步存储到首选项持久化文件中，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | ------------------------- | ---- | ---------------------------------------------------- |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 | | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当保存成功，err为undefined；否则为错误码。 |
**示例：** **示例：**
```ts ```js
preferences.flush(function (err) { preferences.flush(function (err) {
if (err) { if (err) {
console.info("Flush to file failed, err: " + err) console.info("Failed to flush. Cause: " + err);
return return;
} }
console.info("Flushed to file successfully.") console.info("Succeeded in flushing.");
}) })
``` ```
...@@ -518,22 +535,22 @@ preferences.flush(function (err) { ...@@ -518,22 +535,22 @@ preferences.flush(function (err) {
flush(): Promise&lt;void&gt; flush(): Promise&lt;void&gt;
将当前preferences对象中的修改保存到当前的preferences，并异步存储到首选项持久化文件中，该方法使用Promise方式作为异步方法。 将当前preferences对象中的修改保存到当前的preferences，并异步存储到首选项持久化文件中，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise实例，用于异步处理。 | | Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例：** **示例：**
```ts ```js
let promise = preferences.flush() let promise = preferences.flush();
promise.then(() => { promise.then(() => {
console.info("Flushed to file successfully.") console.info("Succeeded in flushing.");
}).catch((err) => { }).catch((err) => {
console.info("Flush to file failed, err: " + err) console.info("Failed to flush. Cause: " + err);
}) })
``` ```
...@@ -542,23 +559,23 @@ promise.then(() => { ...@@ -542,23 +559,23 @@ promise.then(() => {
clear(callback: AsyncCallback&lt;void&gt;): void clear(callback: AsyncCallback&lt;void&gt;): void
清除此存储对象中的所有存储，该方法使用callback方式作为异步方法。 清除此存储对象中的所有存储，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | ------------------------- | ---- | ---------------------------------------------------- |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。 | | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当清除成功，err为undefined；否则为错误码。 |
**示例：** **示例：**
```ts ```js
preferences.clear(function (err) { preferences.clear(function (err) {
if (err) { if (err) {
console.info("Clear to file failed, err: " + err) console.info("Failed to clear. Cause: " + err);
return return;
} }
console.info("Cleared to file successfully.") console.info("Succeeded in clearing.");
}) })
``` ```
...@@ -567,22 +584,22 @@ preferences.clear(function (err) { ...@@ -567,22 +584,22 @@ preferences.clear(function (err) {
clear(): Promise&lt;void&gt; clear(): Promise&lt;void&gt;
清除此存储对象中的所有存储，该方法使用Promise方式作为异步方法。 清除此存储对象中的所有存储，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**返回值：** **返回值：**
| 类型 | 说明 | | 类型 | 说明 |
| -------- | -------- | | ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise实例，用于异步处理。 | | Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例：** **示例：**
```ts ```js
let promise = preferences.clear() let promise = preferences.clear()
promise.then(() => { promise.then(() => {
console.info("Cleared to file successfully.") console.info("Succeeded in clearing.");
}).catch((err) => { }).catch((err) => {
console.info("Clear to file failed, err: " + err) console.info("Failed to clear. Cause: " + err);
}) })
``` ```
...@@ -591,40 +608,40 @@ promise.then(() => { ...@@ -591,40 +608,40 @@ promise.then(() => {
on(type: 'change', callback: Callback&lt;{ key : string }&gt;): void on(type: 'change', callback: Callback&lt;{ key : string }&gt;): void
订阅数据变更者类，订阅的key的值发生变更后，在执行flush方法后，callback方法会被回调。 订阅数据变更，订阅的Key的值发生变更后，在执行[flush](#flush)方法后，触发callback回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------------------------------- | ---- | ---------------------------------------- |
| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | | type | string | 是 | 事件类型，固定值'change'，表示数据变更。 |
| callback | Callback&lt;{ key : string }&gt; | 是| 回调对象实例。 | | callback | Callback&lt;{ key : string }&gt; | 是 | 回调对象实例。 |
**示例：** **示例：**
```ts ```js
data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) {
if (err) { if (err) {
console.info("Get preferences failed.") console.info("Failed to Gget preferences.");
return; return;
} }
var observer = function (key) { var observer = function (key) {
console.info("The key of " + key + " changed.") console.info("The key " + key + " changed.");
} }
preferences.on('change', observer) preferences.on('change', observer);
preferences.put('startup', 'auto', function (err) { preferences.put('startup', 'auto', function (err) {
if (err) { if (err) {
console.info("Put the value of startup failed, err: " + err) console.info("Failed to put the value of 'startup'. Cause: " + err);
return return;
} }
console.info("Put the value of startup successfully.") console.info("Succeeded in putting the value of 'startup'.");
preferences.flush(function (err) { preferences.flush(function (err) {
if (err) { if (err) {
console.info("Flush to file failed, err: " + err) console.info("Failed to flush. Cause: " + err);
return return;
} }
console.info("Flushed to file successfully.") // observer will be called. console.info("Succeeded in flushing."); // observer will be called.
}) })
}) })
}) })
...@@ -635,42 +652,42 @@ data_preferences.getPreferences(this.context, 'mystore', function (err, preferen ...@@ -635,42 +652,42 @@ data_preferences.getPreferences(this.context, 'mystore', function (err, preferen
off(type: 'change', callback?: Callback&lt;{ key : string }&gt;): void off(type: 'change', callback?: Callback&lt;{ key : string }&gt;): void
当不再进行订阅数据变更时，使用此接口取消订阅。 取消订阅数据变更，订阅的Key的值发生变更后，在执行[flush](#flush)方法后，触发callback回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- | | -------- | -------------------------------- | ---- | ------------------------------------------ |
| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | | type | string | 是 | 事件类型，固定值'change'，表示数据变更。 |
| callback | Callback&lt;{ key : string }&gt; | 否| 需要取消的回调对象实例，不填则全部取消。 | | callback | Callback&lt;{ key : string }&gt; | 否 | 需要取消的回调对象实例，不填写则全部取消。 |
**示例：** **示例：**
```ts ```js
data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) {
if (err) { if (err) {
console.info("Get preferences failed.") console.info("Failed to Gget preferences.");
return; return;
} }
var observer = function (key) { var observer = function (key) {
console.info("The key of " + key + " changed.") console.info("The key " + key + " changed.");
} }
preferences.on('change', observer) preferences.on('change', observer);
preferences.put('startup', 'auto', function (err) { preferences.put('startup', 'auto', function (err) {
if (err) { if (err) {
console.info("Put the value of startup failed, err: " + err) console.info("Failed to put the value of 'startup'. Cause: " + err);
return return;
} }
console.info("Put the value of startup successfully.") console.info("Succeeded in putting the value of 'startup'.");
preferences.flush(function (err) { preferences.flush(function (err) {
if (err) { if (err) {
console.info("Flush to file failed, err: " + err) console.info("Failed to flush. Cause: " + err);
return return;
} }
console.info("Flushed to file successfully.") // observer will be called. console.info("Succeeded in flushing."); // observer will be called.
}) })
preferences.off('change', observer) preferences.off('change', observer);
}) })
}) })
``` ```
...@@ -681,11 +698,11 @@ data_preferences.getPreferences(this.context, 'mystore', function (err, preferen ...@@ -681,11 +698,11 @@ data_preferences.getPreferences(this.context, 'mystore', function (err, preferen
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core **系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
| 类型 | 说明 | | 类型 | 说明 |
| -------------- | ------------------------------ | | --------------- | ------------------------------ |
| number | 表示值类型为数字。 | | number | 表示值类型为数字。 |
| string | 表示值类型为字符串。 | | string | 表示值类型为字符串。 |
| boolean | 表示值类型为布尔值。 | | boolean | 表示值类型为布尔值。 |
| Array\<number> | 表示值类型为数字类型的数组。 | | Array\<number> | 表示值类型为数字类型的数组。 |
| Array\<boolean> | 表示值类型为布尔类型的数组。 | | Array\<boolean> | 表示值类型为布尔类型的数组。 |
| Array\<string> | 表示值类型为字符串类型的数组。 | | Array\<string> | 表示值类型为字符串类型的数组。 |
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或