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

Merge pull request !20371 from blue sky/add_sync_interfaces

zh-cn/application-dev/database/data-persistence-by-preferences.md

@@ -10,7 +10,7 @@
 
 如图所示，用户程序通过JS接口调用用户首选项读写对应的数据文件。开发者可以将用户首选项持久化文件的内容加载到Preferences实例，每个文件唯一对应到一个Preferences实例，系统会通过静态容器将该实例存储在内存中，直到主动从内存中移除该实例或者删除该文件。
 
-应用首选项的持久化文件保存在应用沙箱内部，可以通过context获取其路径。具体可见[获取应用开发路径](../application-models/application-context-stage.md#获取应用开发路径)。
+应用首选项的持久化文件保存在应用沙箱内部，可以通过context获取其路径。具体可见[获取应用文件路径](../application-models/application-context-stage.md#获取应用文件路径)。
 
 **图1** 用户首选项运作机制  
 
@@ -28,15 +28,15 @@
 
 ## 接口说明
 
-以下是用户首选项持久化功能的相关接口，大部分为异步接口。异步接口均有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的存储键值对。 | 
+| 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                           | 取消订阅数据变更。                                                  | 
@@ -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) {
+     if (preferences.hasSync('startup')) {
        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}`);
-         }
+       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;
-       }
+     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

@@ -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