Skip to content

D
Docs

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

通知 159
Star 292
Fork 28
D
Docs
未验证 提交 50e250d2 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!20371 增加首选项同步接口描述 

Merge pull request !20371 from blue sky/add_sync_interfaces
上级 5c604952 256661fc
隐藏空白更改
内联 并排
Showing with 260 addition and 73 deletion
zh-cn/application-dev/database/data-persistence-by-preferences.md
浏览文件 @ 50e250d2
......@@ -10,7 +10,7 @@
如图所示，用户程序通过JS接口调用用户首选项读写对应的数据文件。开发者可以将用户首选项持久化文件的内容加载到Preferences实例，每个文件唯一对应到一个Preferences实例，系统会通过静态容器将该实例存储在内存中，直到主动从内存中移除该实例或者删除该文件。
应用首选项的持久化文件保存在应用沙箱内部，可以通过context获取其路径。具体可见[获取应用开发路径](../application-models/application-context-stage.md#获取应用开发路径)。
应用首选项的持久化文件保存在应用沙箱内部，可以通过context获取其路径。具体可见[获取应用文件路径](../application-models/application-context-stage.md#获取应用文件路径)。
**图1** 用户首选项运作机制  
......@@ -28,19 +28,19 @@
## 接口说明
以下是用户首选项持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见[用户首选项](../reference/apis/js-apis-data-preferences.md)。
以下是用户首选项持久化功能的相关接口，更多接口及使用方式请见[用户首选项](../reference/apis/js-apis-data-preferences.md)。
| 接口名称 | 描述 |
| -------- | -------- |
| getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void | 获取Preferences实例。 |
| put(key: string, value: ValueType, callback: AsyncCallback<void>): void | 将数据写入Preferences实例，可通过flush将Preferences实例持久化。 |
| has(key: string, callback: AsyncCallback<boolean>): void | 检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。 |
| get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void | 获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。 |
| delete(key: string, callback: AsyncCallback<void>): void | 从Preferences实例中删除名为给定Key的存储键值对。 |
| flush(callback: AsyncCallback<void>): void | 将当前Preferences实例的数据异步存储到用户首选项持久化文件中。 |
| on(type: 'change', callback: Callback<{ key : string }>): void | 订阅数据变更，订阅的Key的值发生变更后，在执行flush方法后，触发callback回调。 |
| off(type: 'change', callback?: Callback<{ key : string }>): void | 取消订阅数据变更。 |
| deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void | 从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件，则同时删除其持久化文件。 |
| 接口名称 | 描述 |
|--------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void | 获取Preferences实例。 |
| putSync(key: string, value: ValueType): void | 将数据写入Preferences实例，可通过flush将Preferences实例持久化。该接口存在异步接口。 |
| hasSync(key: string): void | 检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。该接口存在异步接口。 |
| getSync(key: string, defValue: ValueType): void | 获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。该接口存在异步接口。 |
| deleteSync(key: string): void | 从Preferences实例中删除名为给定Key的存储键值对。该接口存在异步接口。 |
| flush(callback: AsyncCallback<void>): void | 将当前Preferences实例的数据异步存储到用户首选项持久化文件中。 |
| on(type: 'change', callback: Callback<{ key : string }>): void | 订阅数据变更，订阅的Key的值发生变更后，在执行flush方法后，触发callback回调。 |
| off(type: 'change', callback?: Callback<{ key : string }>): void | 取消订阅数据变更。 |
| deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void | 从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件，则同时删除其持久化文件。 |
## 开发步骤
......@@ -102,40 +102,24 @@
3. 写入数据。
使用put()方法保存数据到缓存的Preferences实例中。在写入数据后，如有需要，可使用flush()方法将Preferences实例的数据存储到持久化文件。
使用putSync()方法保存数据到缓存的Preferences实例中。在写入数据后，如有需要，可使用flush()方法将Preferences实例的数据存储到持久化文件。
> **说明：**
>
> 当对应的键已经存在时，put()方法会修改其值。如果仅需要在键值对不存在时新增键值对，而不修改已有键值对，需使用has()方法检查是否存在对应键值对；如果不关心是否会修改已有键值对，则直接使用put()方法即可。
> 当对应的键已经存在时，putSync()方法会修改其值。可以使用hasSync()方法检查是否存在对应键值对。
示例代码如下所示：
```js
try {
preferences.has('startup', function (err, val) {
if (err) {
console.error(`Failed to check the key 'startup'. Code:${err.code}, message:${err.message}`);
return;
}
if (val) {
console.info("The key 'startup' is contained.");
} else {
console.info("The key 'startup' does not contain.");
// 此处以此键值对不存在时写入数据为例
try {
preferences.put('startup', 'auto', (err) => {
if (err) {
console.error(`Failed to put data. Code:${err.code}, message:${err.message}`);
return;
}
console.info('Succeeded in putting data.');
})
} catch (err) {
console.error(`Failed to put data. Code: ${err.code},message:${err.message}`);
}
}
})
if (preferences.hasSync('startup')) {
console.info("The key 'startup' is contained.");
} else {
console.info("The key 'startup' does not contain.");
// 此处以此键值对不存在时写入数据为例
preferences.putSync('startup', 'auto');
}
} catch (err) {
console.error(`Failed to check the key 'startup'. Code:${err.code}, message:${err.message}`);
}
......@@ -143,17 +127,12 @@
4. 读取数据。
使用get()方法获取数据，即指定键对应的值。如果值为null或者非默认值类型，则返回默认数据。示例代码如下所示：
使用getSync()方法获取数据，即指定键对应的值。如果值为null或者非默认值类型，则返回默认数据。示例代码如下所示：
```js
try {
preferences.get('startup', 'default', (err, val) => {
if (err) {
console.error(`Failed to get value of 'startup'. Code:${err.code}, message:${err.message}`);
return;
}
console.info(`Succeeded in getting value of 'startup'. val: ${val}.`);
})
let val = preferences.getSync('startup', 'default');
console.info(`Succeeded in getting value of 'startup'. val: ${val}.`);
} catch (err) {
console.error(`Failed to get value of 'startup'. Code:${err.code}, message:${err.message}`);
}
......@@ -161,18 +140,12 @@
5. 删除数据。
使用delete()方法删除指定键值对，示例代码如下所示：
使用deleteSync()方法删除指定键值对，示例代码如下所示：
```js
try {
preferences.delete('startup', (err) => {
if (err) {
console.error(`Failed to delete the key 'startup'. Code:${err.code}, message:${err.message}`);
return;
}
console.info("Succeeded in deleting the key 'startup'.");
})
preferences.deleteSync('startup');
} catch (err) {
console.error(`Failed to delete the key 'startup'. Code:${err.code}, message:${err.message}`);
}
......
zh-cn/application-dev/reference/apis/js-apis-data-preferences.md
浏览文件 @ 50e250d2
......@@ -310,7 +310,7 @@ class EntryAbility extends UIAbility {
removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void
从内存中移除指定的Preferences实例，使用callback异步回调。
从缓存中移除指定的Preferences实例，使用callback异步回调。
调用该接口后，应用不允许再使用该Preferences实例进行数据操作，否则会出现数据一致性问题。
......@@ -373,7 +373,7 @@ class EntryAbility extends UIAbility {
removePreferencesFromCache(context: Context, name: string): Promise<void>
从内存中移除指定的Preferences实例，使用Promise异步回调。
从缓存中移除指定的Preferences实例，使用Promise异步回调。
调用该接口后，应用不允许再使用该Preferences实例进行数据操作，否则会出现数据一致性问题。
......@@ -434,9 +434,58 @@ class EntryAbility extends UIAbility {
}
```
## data_preferences.removePreferencesFromCacheSync<sup>10+</sup>
removePreferencesFromCacheSync(context: Context, name: string): void
从缓存中移除指定的Preferences实例，此为同步接口。
调用该接口后，应用不允许再使用该Preferences实例进行数据操作，否则会出现数据一致性问题。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-uiAbilityContext.md)。 |
| name | string | 是 | Preferences实例的名称。 |
**示例：**
FA模型示例：
```js
// 获取context
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
data_preferences.removePreferencesFromCacheSync(context, 'mystore');
} catch(err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage模型示例：
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
data_preferences.removePreferencesFromCacheSync(this.context, 'mystore');
} catch(err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## Preferences
存储实例，提供获取和修改存储数据的接口。
首选项实例，提供获取和修改存储数据的接口。
下列接口都需先使用[data_preferences.getPreferences](#data_preferencesgetpreferences)获取到Preferences实例，再通过此实例调用对应接口。
......@@ -445,7 +494,7 @@ class EntryAbility extends UIAbility {
get(key: string, defValue: ValueType, callback: AsyncCallback&lt;ValueType&gt;): void
获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用callback异步回调。
从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -478,7 +527,7 @@ try {
get(key: string, defValue: ValueType): Promise&lt;ValueType&gt;
获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用Promise异步回调。
从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -510,11 +559,43 @@ try {
}
```
### getSync<sup>10+</sup>
getSync(key: string, defValue: ValueType): ValueType
从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，此为同步接口。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| key | string | 是 | 要获取的存储Key名称，不能为空。 |
| defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型。 |
**返回值：**
| 类型 | 说明 |
| ----------------------------------- | ----------------------------- |
| [ValueType](#valuetype) | 返回键对应的值。 |
**示例：**
```js
try {
let value = preferences.getSync('startup', 'default');
console.info("Succeeded in getting value of 'startup'. Data: " + value);
} catch(err) {
console.info("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message);
}
```
### getAll
getAll(callback: AsyncCallback&lt;Object&gt;): void;
获取含有所有键值的Object对象。
从缓存的Preferences实例中获取所有键值数据。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -522,7 +603,7 @@ getAll(callback: AsyncCallback&lt;Object&gt;): void;
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;Object&gt; | 是 | 回调函数。当获取成功，err为undefined，value为含有所有键值的Object对象；否则err为错误码。 |
| callback | AsyncCallback&lt;Object&gt; | 是 | 回调函数。当获取成功，err为undefined，value为所有键值数据；否则err为错误码。 |
**示例：**
......@@ -547,7 +628,7 @@ try {
getAll(): Promise&lt;Object&gt;
获取含有所有键值的Object对象。
从缓存的Preferences实例中获取所有键值数据。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -555,7 +636,7 @@ getAll(): Promise&lt;Object&gt;
| 类型 | 说明 |
| --------------------- | ------------------------------------------- |
| Promise&lt;Object&gt; | Promise对象，返回含有所有键值的Object对象。 |
| Promise&lt;Object&gt; | Promise对象，返回含有所有键值数据。 |
**示例：**
......@@ -574,11 +655,38 @@ try {
}
```
### getAllSync<sup>10+</sup>
getAllSync(): Object
从缓存的Preferences实例中获取所有键值数据。，此为同步接口。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**返回值：**
| 类型 | 说明 |
| --------------------- | ------------------------------------------- |
| Object | 返回含有所有键值数据。 |
**示例：**
```js
try {
let value = preferences.getAllSync();
let allKeys = Object.keys(value);
console.info('getAll keys = ' + allKeys);
console.info("getAll object = " + JSON.stringify(value));
} catch (err) {
console.info("Failed to get all key-values. code =" + err.code + ", message =" + err.message);
}
```
### put
put(key: string, value: ValueType, callback: AsyncCallback&lt;void&gt;): void
将数据写入Preferences实例，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。
将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -611,7 +719,7 @@ try {
put(key: string, value: ValueType): Promise&lt;void&gt;
将数据写入Preferences实例，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。
将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -644,11 +752,37 @@ try {
```
### putSync<sup>10+</sup>
putSync(key: string, value: ValueType): void
将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ----------------------- | ---- | ------------------------------------------------------------ |
| key | string | 是 | 要修改的存储的Key，不能为空。 |
| value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>类型。 |
**示例：**
```js
try {
preferences.putSync('startup', 'auto');
} catch(err) {
console.info("Failed to put value of 'startup'. code =" + err.code +", message =" + err.message);
}
```
### has
has(key: string, callback: AsyncCallback&lt;boolean&gt;): void
检查Preferences实例是否包含名为给定Key的存储键值对，使用callback异步回调。
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -684,7 +818,7 @@ try {
has(key: string): Promise&lt;boolean&gt;
检查Preferences实例是否包含名为给定Key的存储键值对，使用Promise异步回调。
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -720,11 +854,47 @@ try {
```
### hasSync<sup>10+</sup>
hasSync(key: string): boolean
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，此为同步接口。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------- |
| key | string | 是 | 要检查的存储key名称，不能为空。 |
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 |
**示例：**
```js
try {
let isExist = preferences.hasSync('startup');
if (isExist) {
console.info("The key 'startup' is contained.");
} else {
console.info("The key 'startup' dose not contain.");
}
} catch(err) {
console.info("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
}
```
### delete
delete(key: string, callback: AsyncCallback&lt;void&gt;): void
从Preferences实例中删除名为给定Key的存储键值对，使用callback异步回调。
从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -756,7 +926,7 @@ try {
delete(key: string): Promise&lt;void&gt;
从Preferences实例中删除名为给定Key的存储键值对，使用Promise异步回调。
从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -788,11 +958,36 @@ try {
```
### deleteSync<sup>10+</sup>
deleteSync(key: string): void
从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------- |
| key | string | 是 | 要删除的存储key名称，不能为空。 |
**示例：**
```js
try {
preferences.deleteSync('startup');
} catch(err) {
console.info("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message);
}
```
### flush
flush(callback: AsyncCallback&lt;void&gt;): void
将当前Preferences实例的数据异步存储到用户首选项的持久化文件中，使用callback异步回调。
将缓存的Preferences实例中的数据异步存储到用户首选项的持久化文件中，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -823,7 +1018,7 @@ try {
flush(): Promise&lt;void&gt;
将当前Preferences实例的数据异步存储到用户首选项的持久化文件中，使用Promise异步回调。
将缓存的Preferences实例中的数据异步存储到用户首选项的持久化文件中，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -853,7 +1048,7 @@ try {
clear(callback: AsyncCallback&lt;void&gt;): void
清除此Preferences实例中的所有存储，使用callback异步回调。
清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -884,7 +1079,7 @@ try {
clear(): Promise&lt;void&gt;
清除此Preferences实例中的所有存储，使用Promise异步回调。
清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
......@@ -910,6 +1105,25 @@ try {
```
### clearSync<sup>10+</sup>
clearSync(): void
清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。
**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core
**示例：**
```js
try {
preferences.clearSync();
} catch(err) {
console.info("Failed to clear. code =" + err.code + ", message =" + err.message);
}
```
### on('change')
on(type: 'change', callback: Callback&lt;{ key : string }&gt;): void
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或