add sync interfaces

Signed-off-by: N MangTsang <mang.tsang@huawei.com>

add sync interfaces
Signed-off-by: N MangTsang <mang.tsang@huawei.com>
8f3aac8a · MangTsang · c1becef4 · 8f3aac8a · 8f3aac8a
2 changed file
--- 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&lt;Preferences&gt;): void | 获取Preferences实例。 | 
+| getPreferences(context: Context, name: string, callback: AsyncCallback&lt;Preferences&gt;): void | 获取Preferences实例。                                           | 
-| put(key: string, value: ValueType, callback: AsyncCallback&lt;void&gt;): void | 将数据写入Preferences实例，可通过flush将Preferences实例持久化。 | 
+| putSync(key: string, value: ValueType): void                | 将数据写入Preferences实例，可通过flush将Preferences实例持久化。该接口存在异步接口。    | 
-| has(key: string, callback: AsyncCallback&lt;boolean&gt;): void | 检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。 | 
+| hasSync(key: string): void                                   | 检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。该接口存在异步接口。    | 
-| get(key: string, defValue: ValueType, callback: AsyncCallback&lt;ValueType&gt;): void | 获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。 | 
+| getSync(key: string, defValue: ValueType): void            | 获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。该接口存在异步接口。         | 
-| delete(key: string, callback: AsyncCallback&lt;void&gt;): void | 从Preferences实例中删除名为给定Key的存储键值对。 | 
+| deleteSync(key: string): void                                   | 从Preferences实例中删除名为给定Key的存储键值对。该接口存在异步接口。                  | 
-| flush(callback: AsyncCallback&lt;void&gt;): void | 将当前Preferences实例的数据异步存储到用户首选项持久化文件中。 | 
+| flush(callback: AsyncCallback&lt;void&gt;): void                                                 | 将当前Preferences实例的数据异步存储到用户首选项持久化文件中。                       | 
-| on(type: 'change', callback: Callback&lt;{ key : string }&gt;): void | 订阅数据变更，订阅的Key的值发生变更后，在执行flush方法后，触发callback回调。 | 
+| on(type: 'change', callback: Callback&lt;{ key : string }&gt;): void                             | 订阅数据变更，订阅的Key的值发生变更后，在执行flush方法后，触发callback回调。             | 
-| off(type: 'change', callback?: Callback&lt;{ key : string }&gt;): void | 取消订阅数据变更。 | 
+| off(type: 'change', callback?: Callback&lt;{ key : string }&gt;): void                           | 取消订阅数据变更。                                                  | 
-| deletePreferences(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void | 从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件，则同时删除其持久化文件。 | 
+| deletePreferences(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): 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 (preferences.hasSync('startup')) {
-       if (err) {
+       console.info("The key 'startup' is contained.");
-         console.error(`Failed to check the key 'startup'. Code:${err.code}, message:${err.message}`);
+     } else {
-         return;
+       console.info("The key 'startup' does not contain.");
-       }
+       // 此处以此键值对不存在时写入数据为例
-       if (val) {
+       preferences.putSync('startup', 'auto');
-         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}`);
-         }
-       }
-     })
   } 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) => {
+     let val = preferences.getSync('startup', 'default');
-       if (err) {
+     console.info(`Succeeded in getting value of 'startup'. val: ${val}.`);
-         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}.`);
-     })
   } 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) => {
+     preferences.deleteSync('startup');
-       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'.");
-     })
   } catch (err) {
     console.error(`Failed to delete the key 'startup'. Code:${err.code}, message:${err.message}`);
   }

--- 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.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
 存储实例，提供获取和修改存储数据的接口。
@@ -510,6 +559,38 @@ try {
 }
 ```
+### getSync<sup>10+</sup>
+getSync(key: string, defValue: ValueType): ValueType;
+获取键对应的值，如果值为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;
@@ -574,6 +655,33 @@ try {
 }
 ```
+### getAllSync<sup>10+</sup>
+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&lt;void&gt;): void
@@ -644,6 +752,32 @@ 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
@@ -720,6 +854,42 @@ 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
@@ -788,6 +958,31 @@ try {
 ```
+### deleteSync<sup>10+</sup>
+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&lt;void&gt;): void
@@ -910,6 +1105,25 @@ try {
 ```
+### clearSync<sup>10+</sup>
+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&lt;{ key : string }&gt;): void