diff --git a/zh-cn/application-dev/reference/apis/js-apis-distributed-data.md b/zh-cn/application-dev/reference/apis/js-apis-distributed-data.md index 89d0b8b9668f93108ed87946d88d19a82f28e53c..e885608121b9b3632ff68cc42106f940b6dbb410 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-distributed-data.md +++ b/zh-cn/application-dev/reference/apis/js-apis-distributed-data.md @@ -113,6 +113,7 @@ try { | 参数名 | 参数类型 | 必填 | 说明 | | ----- | ------ | ------ | ------ | +| context | Context | 是 | 应用程序或功能的上下文。
API version 9之前的Context定义见[Context](js-apis-Context.md)。
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); } ``` + +### delete9+ + +delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<void>): void + +从数据库中删除符合predicates条件的键值对，并通过callback方式返回，此方法为异步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| predicates | Predicates | 是 |指示筛选条件,当此参数为null时，应定义处理逻辑。| +| callback | AsyncCallback<void> | 是 |回调函数。 | + +**示例：** + +```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); +} +``` + +### delete9+ + +delete(predicates: dataSharePredicates.DataSharePredicates): Promise<void> + +从数据库中删除符合predicates条件的键值对，并通过Promise方式返回，此方法为异步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| predicates | Predicates | 是 |指示筛选条件,当此参数为null时，应定义处理逻辑。| + + +**返回值：** + +| 类型 | 说明 | +| ------ | ------- | +| Promise<void> |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<ChangeNotification>): void @@ -2304,6 +2386,36 @@ kvStore.off('dataChange', function (data) { }); ``` +### off('syncComplete')9+ + +off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void + +取消订阅数据变更通知，此方法为同步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| event |string | 是 |取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | +| syncCallback |Callback<Array<[string, number]>> | 否 |用于向调用方发送同步结果的回调。 | + +**示例：** + +```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); +} +``` + ### putBatch8+ @@ -2406,6 +2518,89 @@ try { } ``` +### putBatch9+ + +putBatch(value: Array<ValuesBucket>, callback: AsyncCallback<void>): void + +将值写入KvStore数据库，并通过callback方式返回，此方法为异步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| value |Array[<ValuesBucket>]()[] | 是 |表示要插入的数据。 | +| callback |Asyncallback<void> |是 |回调函数。 | + +**示例：** + +```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)); +} +``` + +### putBatch9+ + +putBatch(value: Array<ValuesBucket>): Promise<void> + +将valuesbucket类型的值写入KvStore数据库，并通过Promise方式返回，此方法为异步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| value |Array<[ValuesBucket>](#)[] | 是 |表示要插入的数据。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------- | +| Promise<void> |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)); +} + +``` ### deleteBatch8+ @@ -3440,6 +3635,81 @@ try { } ``` +### getResultSet9+ ### + +getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KvStoreResultSet>): void + +获取与指定Predicate对象匹配的KvStoreResultSet对象，并通过callback方式返回，此方法为异步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| predicates | Predicates | 是 |指示筛选条件,当此参数为null时，应定义处理逻辑。 | +| callback |AsyncCallback<[KvStoreResultSet](#kvstoreresultsetsup8sup)> | 是 |回调函数，获取与指定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); +} +``` +### getResultSet9+ ### + +getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KvStoreResultSet> + +获取与指定Predicate对象匹配的KvStoreResultSet对象，并通过Promise方式返回，此方法为异步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| predicates |[Predicates](#) | 是 |指示筛选条件,当此参数为null时，应定义处理逻辑。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------- | +|Promise<[KvStoreResultSet](#kvstoreresultset8)> |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); +} +``` ### closeResultSet8+ ### closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void @@ -3769,8 +4039,60 @@ try { } ``` +### on('dataChange')9+ ### + +on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void + +订阅指定类型的数据变更通知，此方法为同步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| event |string | 是 |订阅的事件名，固定为'dataChange'，表示数据变更事件。 | +| type |[SubscribeType](#subscribetype) | 是 |表示订阅的类型。 | +| listener |Callback<[ChangeNotification](#changenotification)> | 是 |回调函数。 | + +**示例：** + +```js +let kvStore; +kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { + console.log("dataChange callback call data: " + JSON.stringify(data)); +}); + +``` + +### off('dataChange')9+ ### + +off(event:'dataChange', listener?: Callback<ChangeNotification>): void + +取消订阅数据变更通知，此方法为同步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| event |string | 是 |取消订阅的事件名，固定为'dataChange'，表示数据变更事件。 | +| listener |Callback<[ChangeNotification](#changenotification)> |否 |回调函数。 | + +**示例：** + +```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); +}); +``` +### sync7+ -### sync sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void @@ -3795,6 +4117,48 @@ let kvStore; kvStore.sync('deviceIds', distributedData.SyncMode.PULL_ONLY, 1000); ``` +### sync9+ +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); +} +``` + ### setSyncParam8+ ### setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void @@ -5062,6 +5426,48 @@ try { } ``` +### sync9+ ### + +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')8+ ### on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void @@ -5128,6 +5534,59 @@ try { } ``` +### on('dataChange')9+ ### + +on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void + +订阅指定类型的数据变更通知，此方法为同步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| event |string | 是 |订阅的事件名，固定为'dataChange'，表示数据变更事件。 | +| type |[SubscribeType](#subscribetype) | 是 |表示订阅的类型。 | +| listener |Callback<[ChangeNotification](#changenotification)> | 是 |回调函数。 | + +**示例：** + +```js +let kvStore; +kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { + console.log("dataChange callback call data: " + JSON.stringify(data)); +}); +``` + + +### off('dataChange')9+ ### + +off(event:'dataChange', listener?: Callback<ChangeNotification>): void + +取消订阅数据变更通知，此方法为同步方法。 + +**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core + +**参数：** + +| 参数名 | 参数类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------- | +| event |string | 是 |取消订阅的事件名，固定为'dataChange'，表示数据变更事件。 | +| listener |Callback<[ChangeNotification](#changenotification)> |否 |回调函数。 | + +**示例：** + +```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 同步模式枚举。