From 8f3aac8a39c9d41d34b29e615fc68d75acc437e1 Mon Sep 17 00:00:00 2001 From: MangTsang Date: Mon, 3 Jul 2023 11:30:14 +0800 Subject: [PATCH] add sync interfaces Signed-off-by: MangTsang --- .../data-persistence-by-preferences.md | 79 +++---- .../apis/js-apis-data-preferences.md | 214 ++++++++++++++++++ 2 files changed, 240 insertions(+), 53 deletions(-) diff --git a/zh-cn/application-dev/database/data-persistence-by-preferences.md b/zh-cn/application-dev/database/data-persistence-by-preferences.md index 6fb88b6cc5..09b6ee39c3 100644 --- a/zh-cn/application-dev/database/data-persistence-by-preferences.md +++ b/zh-cn/application-dev/database/data-persistence-by-preferences.md @@ -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}`); } diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-preferences.md b/zh-cn/application-dev/reference/apis/js-apis-data-preferences.md index 60a367834e..d6716a377e 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-preferences.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-preferences.md @@ -434,6 +434,55 @@ class EntryAbility extends UIAbility { } ``` +## data_preferences.removePreferencesFromCacheSync10+ + +removePreferencesFromCacheSync(context: Context, name: string): void; + +从内存中移除指定的Preferences实例，此为同步接口。 + +调用该接口后，应用不允许再使用该Preferences实例进行数据操作，否则会出现数据一致性问题。 + +**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------- | ---- | ----------------------- | +| context | Context | 是 | 应用上下文。
FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。
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 存储实例，提供获取和修改存储数据的接口。 @@ -510,6 +559,38 @@ try { } ``` +### getSync10+ + +getSync(key: string, defValue: ValueType): ValueType; + +获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，此为同步接口。 + +**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------------------------------------ | +| key | string | 是 | 要获取的存储Key名称，不能为空。 | +| defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean、Array\、Array\、Array\类型。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------- | ----------------------------- | +| [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<Object>): void; @@ -574,6 +655,33 @@ try { } ``` +### getAllSync10+ + +getAllSync(): Object; + +获取含有所有键值的Object对象，此为同步接口。 + +**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ------------------------------------------- | +| Object | 返回含有所有键值的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<void>): void @@ -644,6 +752,32 @@ try { ``` +### putSync10+ + +putSync(key: string, value: ValueType): void; + +将数据写入Preferences实例，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 + +**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------- | ---- | ------------------------------------------------------------ | +| key | string | 是 | 要修改的存储的Key，不能为空。 | +| value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean、Array\、Array\、Array\类型。 | + +**示例：** + +```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<boolean>): void @@ -720,6 +854,42 @@ try { ``` +### hasSync10+ + +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<void>): void @@ -788,6 +958,31 @@ try { ``` +### deleteSync10+ + +deleteSync(key: string): void; + +从Preferences实例中删除名为给定Key的存储键值对，此为同步接口。 + +**系统能力：** 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<void>): void @@ -910,6 +1105,25 @@ try { ``` +### clearSync10+ + +clearSync(): void; + +清除此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<{ key : string }>): void -- GitLab