!6184 新增接口代码补充

Merge pull request !6184 from Wangkai/master

zh-cn/application-dev/reference/apis/js-apis-distributed-data.md

@@ -113,6 +113,7 @@ try {
 
 | 参数名 | 参数类型 | 必填 | 说明 |
 | ----- | ------ | ------ | ------ |
+| context | Context | 是 | 应用程序或功能的上下文。 <br>API version 9之前的Context定义见[Context](js-apis-Context.md)。<br>API version 9及之后的Context定义见[Context](js-apis-ability-context.md)。|
 | userInfo | [UserInfo](#userinfo) | 是  | 调用方的用户信息。 |
 | bundleName | string | 是  | 调用方的包名。 |
 
@@ -2227,6 +2228,87 @@ try {
     console.log("An unexpected error occurred. Error:" + e);
 }
 ```
+
+### delete<sup>9+</sup>
+
+delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback&lt;void&gt;): void
+
+从数据库中删除符合predicates条件的键值对，并通过callback方式返回，此方法为异步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| predicates    | Predicates  | 是    |指示筛选条件,当此参数为null时，应定义处理逻辑。|
+| callback  | AsyncCallback&lt;void&gt;  | 是    |回调函数。   |
+
+**示例：**
+
+```js
+import dataSharePredicates from './@ohos.data.dataSharePredicates';
+let kvStore;
+try {
+	let predicates = new dataSharePredicates.DataSharePredicates();
+	kvStore.delete(predicates, function (err, data) {
+		if (err == undefined) {
+			console.log('delete success');
+		} else {
+			console.log('delete fail' + err);
+		}
+    });  
+} catch (e) {
+	console.log('An unexpected error occurred. Error:' + e);
+}
+```
+
+### delete<sup>9+</sup>
+
+delete(predicates: dataSharePredicates.DataSharePredicates): Promise&lt;void&gt;
+
+从数据库中删除符合predicates条件的键值对，并通过Promise方式返回，此方法为异步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| predicates    | Predicates  | 是    |指示筛选条件,当此参数为null时，应定义处理逻辑。|
+
+
+**返回值：**
+
+| 类型    | 说明       |
+| ------  | -------   |
+| Promise&lt;void&gt; |Promise实例，用于异步处理。|
+
+**示例：**
+
+```js
+import dataSharePredicates from './@ohos.data.dataSharePredicates';
+let kvStore;
+try {
+	let predicates = new dataSharePredicates.DataSharePredicates();
+	let arr = ["name"];
+	predicates.inKeys(arr);
+	kvStore.put("name", "bob").then((data) => {
+		console.log('put success' + JSON.stringify(data));
+		kvStore.delete(predicates).then((data) => {
+			console.log('delete success');
+		}).catch((err) => {
+			console.log('delete fail' + JSON.stringify(err));
+		});
+	}) .catch((err) => {
+		console.log(' put fail' + err);
+	});
+}catch (e) {
+	console.log("An unexpected error occurred. Error:" + e);
+}
+
+```
+
 ### on('dataChange')
 
 on(event: 'dataChange', type: SubscribeType, observer: Callback&lt;ChangeNotification&gt;): void
@@ -2304,6 +2386,36 @@ kvStore.off('dataChange', function (data) {
 });
 ```
 
+### off('syncComplete')<sup>9+</sup>
+
+off(event: 'syncComplete', syncCallback?: Callback&lt;Array&lt;[string, number]&gt;&gt;): void
+
+取消订阅数据变更通知，此方法为同步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| event  |string  | 是    |取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。       |
+| syncCallback  |Callback&lt;Array&lt;[string, number]&gt;&gt;   | 否    |用于向调用方发送同步结果的回调。    |
+
+**示例：**
+
+```js
+let kvStore;
+try {
+    const func = function (data) {
+        console.log('syncComplete ' + data)
+    };
+    kvStore.on('syncComplete', func);
+    kvStore.off('syncComplete', func);
+}catch(e) {
+    console.log('syncComplete e ' + e);
+}
+```
+
 
 ### putBatch<sup>8+</sup>
 
@@ -2406,6 +2518,89 @@ try {
 }
 ```
 
+### putBatch<sup>9+</sup>
+
+putBatch(value: Array&lt;ValuesBucket&gt;, callback: AsyncCallback&lt;void&gt;): void
+  
+将值写入KvStore数据库，并通过callback方式返回，此方法为异步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| value   |Array[&lt;ValuesBucket&gt;]()[] | 是    |表示要插入的数据。  |
+| callback |Asyncallback&lt;void&gt; |是     |回调函数。 |
+
+**示例：**
+
+```js
+let kvStore;
+try {
+    let v8Arr = [];
+    let arr = new Uint8Array([4,5,6,7]);
+    let vb1 = {key : "name_1", value : 32}
+    let vb2 = {key : "name_2", value : arr};
+    let vb3 = {key : "name_3", value : "lisi"};
+
+    v8Arr.push(vb1);
+    v8Arr.push(vb2);
+    v8Arr.push(vb3);
+    kvStore.putBatch(v8Arr, async function (err,data) {
+                console.log('putBatch success');
+    }).catch((err) => {
+        console.log('putBatch fail ' + JSON.stringify(err));
+    });
+}catch(e) {
+    console.log('putBatch e ' + JSON.stringify(e));
+}
+```
+
+### putBatch<sup>9+</sup>
+
+putBatch(value: Array&lt;ValuesBucket&gt;): Promise&lt;void&gt;
+
+将valuesbucket类型的值写入KvStore数据库，并通过Promise方式返回，此方法为异步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| value  |Array&lt;[ValuesBucket&gt;](#)[] | 是    |表示要插入的数据。  |
+
+**返回值：**
+
+| 类型    | 说明       |
+| ------  | -------   |
+| Promise&lt;void&gt; |Promise实例，用于异步处理。|
+
+**示例：**
+
+```js
+let kvStore;
+try {
+    let v8Arr = [];
+    let arr = new Uint8Array([4,5,6,7]);
+    let vb1 = {key : "name_1", value : 32}
+    let vb2 = {key : "name_2", value : arr};
+    let vb3 = {key : "name_3", value : "lisi"};
+
+    v8Arr.push(vb1);
+    v8Arr.push(vb2);
+    v8Arr.push(vb3);
+    kvStore.putBatch(v8Arr).then(async (err) => {
+        console.log('putBatch success');
+    }).catch((err) => {
+        console.log('putBatch fail ' + JSON.stringify(err));
+    });
+}catch(e) {
+    console.log('PutBatch e ' + JSON.stringify(e));
+}
+
+```
 
 ### deleteBatch<sup>8+</sup>
 
@@ -3440,6 +3635,81 @@ try {
 }
 ```
 
+### getResultSet<sup>9+</sup> ###
+
+getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback&lt;KvStoreResultSet&gt;): void
+
+获取与指定Predicate对象匹配的KvStoreResultSet对象，并通过callback方式返回，此方法为异步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------   | ----  | ----------------------- |
+| predicates  | Predicates    | 是    |指示筛选条件,当此参数为null时，应定义处理逻辑。             |
+| callback  |AsyncCallback&lt;[KvStoreResultSet](#kvstoreresultsetsup8sup)&gt;   | 是    |回调函数，获取与指定Predicates对象匹配的KvStoreResultSet对象。 |
+
+**示例：**
+
+```js
+import dataSharePredicates from './@ohos.data.dataSharePredicates';
+let kvStore;
+try {
+    let resultSet;
+    let predicates = new dataSharePredicates.DataSharePredicates();
+    predicates.prefixKey("batch_test_string_key");
+    kvStore.getResultSet(predicates, async function (err, result) {
+    console.log(' GetResultSet success');
+    resultSet = result;
+    kvStore.closeResultSet(resultSet, function (err, data) {
+        console.log(' closeResultSet success');
+        })
+    });
+}catch(e) {
+    console.log('An unexpected error occurred. Error:' + e);
+}
+```
+### getResultSet<sup>9+</sup> ###
+
+getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise&lt;KvStoreResultSet&gt;
+
+获取与指定Predicate对象匹配的KvStoreResultSet对象，并通过Promise方式返回，此方法为异步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------   | ----  | ----------------------- |
+| predicates  |[Predicates](#)  | 是    |指示筛选条件,当此参数为null时，应定义处理逻辑。            |
+
+**返回值：**
+
+| 类型    | 说明       |
+| ------  | -------   |
+|Promise&lt;[KvStoreResultSet](#kvstoreresultset8)&gt; |Promise实例，用于获取异步返回结果。|
+
+**示例：**
+
+```js
+import dataSharePredicates from './@ohos.data.dataSharePredicates';
+let kvStore;
+try {
+	let resultSet;
+    let predicates =  new dataSharePredicates.DataSharePredicates();
+    predicates.prefixKey("batch_test_string_key");
+    kvStore.getResultSet(predicates) .then((result) => {
+        console.log(' GetResultSet success');
+        resultSet = result;
+        kvStore.closeResultSet(resultSet, fun ction (err, data) {
+            console.log(' closeResultSet success');
+        })
+    });
+}catch(e) {
+	console.log('An unexpected error occurred. Error:' + e);
+}
+```
 ### closeResultSet<sup>8+</sup> ###
 
 closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback&lt;void&gt;): void
@@ -3769,8 +4039,60 @@ try {
 }
 ```
 
+### on('dataChange')<sup>9+</sup> ###
+
+on(event: 'dataChange', type: SubscribeType, listener: Callback&lt;ChangeNotification&gt;): void
+
+订阅指定类型的数据变更通知，此方法为同步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| event  |string  | 是    |订阅的事件名，固定为'dataChange'，表示数据变更事件。       |
+| type  |[SubscribeType](#subscribetype) | 是    |表示订阅的类型。     |
+| listener |Callback&lt;[ChangeNotification](#changenotification)&gt; | 是    |回调函数。 |
+
+**示例：**
+
+```js
+let kvStore;
+kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) {
+    console.log("dataChange callback call data: " + JSON.stringify(data));
+});
+
+```
+
+### off('dataChange')<sup>9+</sup> ###
+
+off(event:'dataChange', listener?: Callback&lt;ChangeNotification&gt;): void
+
+取消订阅数据变更通知，此方法为同步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| event  |string  | 是    |取消订阅的事件名，固定为'dataChange'，表示数据变更事件。       |
+| listener |Callback&lt;[ChangeNotification](#changenotification)&gt; |否    |回调函数。 |
+
+**示例：**
+
+```js
+let kvStore;
+kvStore.on('dataChange', function (data) {
+    console.log("callback call data: " + data);
+});
+kvStore.off('dataChange', function (data) {
+    console.log("callback call data: " + data);
+});
+```
+### sync<sup>7+</sup>
 
-### sync
 
 sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void
 
@@ -3795,6 +4117,48 @@ let kvStore;
 kvStore.sync('deviceIds', distributedData.SyncMode.PULL_ONLY, 1000);
 ```
 
+### sync<sup>9+</sup>
+sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void
+
+在手动同步方式下，触发数据库同步，此方法为同步方法。关于分布式数据服务的同步方式说明，请见[分布式数据服务概述](../../database/database-mdds-overview.md)。
+
+**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------   | ----  | ----------------------- |
+| deviceIds  |string[]  | 是    |同一组网环境下，需要同步的设备的deviceId列表。    |
+| mode            |[SyncMode](#syncmode)  | 是    |同步模式。  |
+| query  |[Query](#querysup8sup)   | 是   |表示数据库的查询谓词条件  |
+| delayMs  |number   | 否   |可选参数，允许延时时间，单位：ms（毫秒）。   |
+
+**示例：**
+
+```js
+let kvstore;
+const KEY_TEST_SYNC_ELEMENT = 'key_test_sync';
+const VALUE_TEST_SYNC_ELEMENT = 'value-string-001';
+try {
+    kvStore.on('syncComplete', function (data) {
+        console.log('Sync dataChange');
+    });
+    kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err,data) {
+        console.log('Sync put success');
+        const devices = ['deviceList'];
+        const mode = distributedData.SyncMode.PULL_ONLY;
+        const query = new distributedData.Query();
+        query.prefixKey("batch_test");
+        query.deviceId('localDeviceId');
+        kvStore.sync(devices, query, PULL_ONLY , 1000);
+    });
+}catch(e) {
+    console.log('Sync e' + e);
+}
+```
+
 ### setSyncParam<sup>8+</sup> ###
 
 setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback&lt;void&gt;): void
@@ -5062,6 +5426,48 @@ try {
 }
 ```
 
+### sync<sup>9+</sup> ###
+
+sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void
+
+在手动同步方式下， 触发数据库同步，此方法为同步方法。关于分布式数据服务的同步方式说明，请见[分布式数据服务概述](../../database/database-mdds-overview.md)。
+
+**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------   | ----  | ----------------------- |
+| deviceIds    |string[]               | 是    |需要同步DeviceKvStore数据库的设备ID列表。 |
+| query            |[Query](#query8)  | 是    | 数据库的查询谓词条件。|
+| delayMs  |number                 | 否    |可选参数，允许延时时间，单位：ms（毫秒）。  |
+
+**示例：**
+
+```js
+let kvstore;
+const KEY_TEST_SYNC_ELEMENT = 'key_test_sync';
+const VALUE_TEST_SYNC_ELEMENT = 'value-string-001';
+try {
+    kvStore.on('syncComplete', function (data) {
+        console.log('Sync dataChange');
+    });
+    kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err,data) {
+        console.log('Sync put success');
+        const devices = ['deviceList'];
+        const mode = distributedData.SyncMode.PULL_ONLY;
+        const query = new distributedData.Query();
+        query.prefixKey("batch_test");
+        query.deviceId('localDeviceId');
+        kvStore.sync(devices, query, 1000);
+    });
+}catch(e) {
+    console.log('Sync e' + e);
+}
+```
+
 ### on('syncComplete')<sup>8+</sup> ###
 
 on(event: 'syncComplete', syncCallback: Callback&lt;Array&lt;[string, number]&gt;&gt;): void
@@ -5128,6 +5534,59 @@ try {
 }
 ```
 
+### on('dataChange')<sup>9+</sup> ###
+
+on(event: 'dataChange', type: SubscribeType, listener: Callback&lt;ChangeNotification&gt;): void
+
+订阅指定类型的数据变更通知，此方法为同步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| event  |string  | 是    |订阅的事件名，固定为'dataChange'，表示数据变更事件。       |
+| type  |[SubscribeType](#subscribetype) | 是    |表示订阅的类型。     |
+| listener |Callback&lt;[ChangeNotification](#changenotification)&gt; | 是    |回调函数。 |
+
+**示例：**
+
+```js
+let kvStore;
+kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) {
+    console.log("dataChange callback call data: " + JSON.stringify(data));
+});
+```
+
+
+### off('dataChange')<sup>9+</sup> ###
+
+off(event:'dataChange', listener?: Callback&lt;ChangeNotification&gt;): void
+
+取消订阅数据变更通知，此方法为同步方法。
+
+**系统能力：**  SystemCapability.DistributedDataManager.KVStore.Core
+
+**参数：**
+
+| 参数名  | 参数类型 | 必填  | 说明                    |
+| -----  | ------  | ----  | ----------------------- |
+| event  |string  | 是    |取消订阅的事件名，固定为'dataChange'，表示数据变更事件。       |
+| listener |Callback&lt;[ChangeNotification](#changenotification)&gt; |否    |回调函数。 |
+
+**示例：**
+
+```js
+let kvStore;
+kvStore.on('dataChange', function (data) {
+    console.log("callback call data: " + data);
+});
+kvStore.off('dataChange', function (data) {
+    console.log("callback call data: " + data);
+});
+```
+
 ## SyncMode
 
 同步模式枚举。