HarmonyOSAPI：@ohos.data.distributedData (分布式数据管理)

joytrian

发布于 2023-4-4 16:36

浏览

0收藏

版本：v3.1 Beta

@ohos.data.distributedData (分布式数据管理)

sync

sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void

在手动同步方式下，触发数据库同步。关于分布式数据服务的同步方式说明，请见分布式数据服务概述。

此接口能力在HarmonyOS 3.1Beta1暂不支持。

需要权限： ohos.permission.DISTRIBUTED_DATASYNC。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
deviceIds	string[]	是	同一组网环境下，需要同步的设备的deviceId列表。
mode	SyncMode	是	同步模式。
delayMs	number	否	可选参数，允许延时时间，单位：ms（毫秒）。

示例：

let kvStore;
kvStore.sync(['deviceIds'], distributedData.SyncMode.PULL_ONLY, 1000);1.
2.

on('dataChange')⁸⁺

on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void

订阅指定类型的数据变更通知。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
event	string	是	订阅的事件名，固定为'dataChange'，表示数据变更事件。
type	SubscribeType	是	表示订阅的类型。
listener	Callback<ChangeNotification>	是	回调函数。

示例：

let kvStore;
kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) {
    console.log("dataChange callback call data: " + JSON.stringify(data));
});1.
2.
3.
4.

on('syncComplete')⁸⁺

on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void

订阅同步完成事件回调通知。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
event	string	是	订阅的事件名，固定为'syncComplete'，表示同步完成事件。
syncCallback	Callback<Array<[string, number]>>	是	回调函数。用于向调用方发送同步结果的回调。

示例：

let kvStore;
const KEY_TEST_FLOAT_ELEMENT = 'key_test_float';
const VALUE_TEST_FLOAT_ELEMENT = 321.12;
try {
    kvStore.on('syncComplete', function (data) {
        console.log('syncComplete ' + data)
    });
    kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then((data) => {
        console.log('syncComplete put success');
    }).catch((error) => {
        console.log('syncComplete put fail ' + error);
    });
}catch(e) {
    console.log('syncComplete put e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.

off('dataChange')⁸⁺

off(event:'dataChange', listener?: Callback<ChangeNotification>): void

取消订阅数据变更通知。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
event	string	是	取消订阅的事件名，固定为'dataChange'，表示数据变更事件。
listener	Callback<ChangeNotification>	否	回调函数。

示例：

let kvStore;
class KvstoreModel {
    call(data) {
        console.log("dataChange: " + data);
    }
    subscribeDataChange() {
        if (kvStore != null) {
            kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call);
        }
    }
    unsubscribeDataChange() {
        if (kvStore != null) {
            kvStore.off('dataChange', this.call);
        }
    }
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.

off('syncComplete')⁸⁺

off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void

取消订阅同步完成事件回调通知。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
event	string	是	取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。
syncCallback	Callback<Array<[string, number]>>	否	回调函数。用于向调用方发送同步结果的回调。

示例：

let kvStore;
class KvstoreModel {
    call(data) {
        console.log("syncComplete: " + data);
    }
    subscribeSyncComplete() {
        if (kvStore != null) {
            kvStore.on('syncComplete', this.call);
        }
    }
    unsubscribeSyncComplete() {
        if (kvStore != null) {
            kvStore.off('syncComplete', this.call);
        }
    }
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.

setSyncParam⁸⁺

setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void

设置数据库同步允许的默认延迟，使用callback异步回调。

此接口能力在HarmonyOS 3.1Beta1暂不支持。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
defaultAllowedDelayMs	number	是	表示数据库同步允许的默认延迟，以毫秒为单位。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
try {
    const defaultAllowedDelayMs = 500;
    kvStore.setSyncParam(defaultAllowedDelayMs, function (err,data) {
        console.log('SetSyncParam put success');
    });
}catch(e) {
    console.log('testSingleKvStoreSetSyncParam e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.

setSyncParam⁸⁺

setSyncParam(defaultAllowedDelayMs: number): Promise<void>

设置数据库同步允许的默认延迟，使用Promise异步回调。

此接口能力在HarmonyOS 3.1Beta1暂不支持。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
defaultAllowedDelayMs	number	是	表示数据库同步允许的默认延迟，以毫秒为单位。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

示例：

let kvStore;
try {
    const defaultAllowedDelayMs = 500;
    kvStore.setSyncParam(defaultAllowedDelayMs).then((err) => {
        console.log('SetSyncParam put success');
    }).catch((err) => {
        console.log('SetSyncParam put fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('SetSyncParam e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

getSecurityLevel⁸⁺

getSecurityLevel(callback: AsyncCallback<SecurityLevel>): void

获取数据库的安全级别，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<SecurityLevel>	是	回调函数。返回数据库的安全级别。

示例：

let kvStore;
try {
    kvStore.getSecurityLevel(function (err,data) {
        console.log('getSecurityLevel success');
    });
}catch(e) {
    console.log('GetSecurityLevel e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.

getSecurityLevel⁸⁺

getSecurityLevel(): Promise<SecurityLevel>

获取数据库的安全级别，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

返回值：

类型	说明
Promise<SecurityLevel>	Promise对象。返回数据库的安全级别。

示例：

let kvStore;
try {
    kvStore.getSecurityLevel().then((data) => {
        console.log(' getSecurityLevel success');
    }).catch((err) => {
        console.log('getSecurityLevel fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetSecurityLevel e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

DeviceKVStore⁸⁺

设备协同数据库，继承自KVStore，提供查询数据和同步数据的方法。

设备协同数据库，以设备维度对数据进行区分，每台设备仅能写入和修改本设备的数据，其它设备的数据对其是只读的，无法修改其它设备的数据。

比如，可以使用设备协同数据库实现设备间的图片分享，可以查看其他设备的图片，但无法修改和删除其他设备的图片。

在调用DeviceKVStore的方法前，需要先通过getKVStore构建一个DeviceKVStore实例。

get⁸⁺

get(deviceId: string, key: string, callback: AsyncCallback<boolean|string|number|Uint8Array>): void

获取与指定设备ID和key匹配的string值，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	标识要查询其数据的设备。
key	string	是	表示要查询key值的键。
callback	AsyncCallback<boolean\|string\|number\|Uint8Array>	是	回调函数，返回匹配给定条件的字符串值。

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string_2';
const VALUE_TEST_STRING_ELEMENT = 'value-string-002';
try{
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err,data) {
        console.log('put success');
        kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, function (err,data) {
            console.log('get success');
        });
    })
}catch(e) {
    console.log('get e' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

get⁸⁺

get(deviceId: string, key: string): Promise<boolean|string|number|Uint8Array>

获取与指定设备ID和key匹配的string值，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	标识要查询其数据的设备。
key	string	是	表示要查询key值的键。

返回值：

类型	说明
Promise<boolean\|string\|number\|Uint8Array>	Promise对象。返回匹配给定条件的字符串值。

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string_2';
const VALUE_TEST_STRING_ELEMENT = 'value-string-002';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(async (data) => {
        console.log(' put success');
        kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log('get success');
        }).catch((err) => {
            console.log('get fail ' + JSON.stringify(err));
        });
    }).catch((error) => {
        console.log('put error' + error);
    });
} catch (e) {
    console.log('Get e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

getEntries⁸⁺

getEntries(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void

获取与指定设备ID和key前缀匹配的所有键值对，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	标识要查询其数据的设备。
keyPrefix	string	是	表示要匹配的键前缀。
callback	AsyncCallback<Entry[]>	是	回调函数，返回满足给定条件的所有键值对的列表。

示例：

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + entries);
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        kvStore.getEntries('localDeviceId', 'batch_test_string_key', function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        });
    });
}catch(e) {
    console.log('PutBatch e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.

getEntries⁸⁺

getEntries(deviceId: string, keyPrefix: string): Promise<Entry[]>

获取与指定设备ID和key前缀匹配的所有键值对，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	标识要查询其数据的设备。
keyPrefix	string	是	表示要匹配的键前缀。

返回值：

类型	说明
Promise<Entry[]>	Promise对象。返回匹配给定条件的所有键值对的列表。

示例：

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + entries);
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        kvStore.getEntries('localDeviceId', 'batch_test_string_key').then((entries) => {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
            console.log('entries[0].value: ' + JSON.stringify(entries[0].value));
            console.log('entries[0].value.value: ' + entries[0].value.value);
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('PutBatch e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.

getEntries⁸⁺

getEntries(query: Query, callback: AsyncCallback<Entry[]>): void

获取与指定Query对象匹配的键值对列表，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
query	Query	是	表示查询对象。
callback	AsyncCallback<Entry[]>	是	回调函数，返回与指定Query对象匹配的键值对列表。

示例：

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.getEntries(query, function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        });
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.

getEntries⁸⁺

getEntries(query: Query): Promise<Entry[]>

获取与指定Query对象匹配的键值对列表，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
query	Query	是	表示查询对象。

返回值：

类型	说明
Promise<Entry[]>	Promise对象。返回与指定Query对象匹配的键值对列表。

示例：

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getEntries(query).then((entries) => {
            console.log('getEntries success');
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('GetEntries putBatch fail ' + JSON.stringify(err))
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.

getEntries⁸⁺

getEntries(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void

获取与指定设备ID和Query对象匹配的键值对列表，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	键值对所属的设备ID。
query	Query	是	表示查询对象。
callback	AsyncCallback<Entry[]>	是	回调函数。返回与指定设备ID和Query对象匹配的键值对列表。

示例：

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        var query = new distributedData.Query();
        query.deviceId('localDeviceId');
        query.prefixKey("batch_test");
        kvStore.getEntries('localDeviceId', query, function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        })
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.

getEntries⁸⁺

getEntries(deviceId: string, query: Query): Promise<Entry[]>

获取与指定设备ID和Query对象匹配的键值对列表，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	键值对所属的设备ID。
query	Query	是	表示查询对象。

返回值：

类型	说明
Promise<Entry[]>	Promise对象。返回与指定设备ID和Query对象匹配的键值对列表。

示例：

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        var query = new distributedData.Query();
        query.deviceId('localDeviceId');
        query.prefixKey("batch_test");
        kvStore.getEntries('localDeviceId', query).then((entries) => {
            console.log('getEntries success');
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.

getResultSet⁸⁺

getResultSet(deviceId: string, keyPrefix: string, callback: AsyncCallback<KvStoreResultSet>): void

获取与指定设备ID和key前缀匹配的KvStoreResultSet对象，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	标识要查询其数据的设备。
keyPrefix	string	是	表示要匹配的键前缀。
callback	AsyncCallback<KvStoreResultSet>	是	回调函数。返回与指定设备ID和key前缀匹配的KvStoreResultSet对象。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('localDeviceId', 'batch_test_string_key', async function (err, result) {
        console.log('getResultSet succeed.');
        resultSet = result;
        kvStore.closeResultSet(resultSet, function (err, data) {
            console.log('closeResultSet success');
        })
    });
}catch(e) {
    console.log('GetResultSet e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

getResultSet⁸⁺

getResultSet(deviceId: string, keyPrefix: string): Promise<KvStoreResultSet>

获取与指定设备ID和key前缀匹配的KvStoreResultSet对象，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	标识要查询其数据的设备。
keyPrefix	string	是	表示要匹配的键前缀。

返回值：

类型	说明
Promise<KvStoreResultSet>	Promise对象。返回与指定设备ID和key前缀匹配的KvStoreResultSet对象。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('localDeviceId', 'batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSet e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

getResultSet⁸⁺

getResultSet(query: Query, callback: AsyncCallback<KvStoreResultSet>): void

获取与指定Query对象匹配的KvStoreResultSet对象，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
query	Query	是	表示查询对象。
callback	AsyncCallback<KvStoreResultSet>	是	回调函数，返回与指定Query对象匹配的KvStoreResultSet对象。

示例：

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.getResultSet(query, async function (err, result) {
            console.log('getResultSet succeed.');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                console.log('closeResultSet success');
            })
        });
    });
} catch(e) {
    console.log('GetResultSet e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.

getResultSet⁸⁺

getResultSet(query: Query): Promise<KvStoreResultSet>

获取与指定Query对象匹配的KvStoreResultSet对象，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
query	Query	是	表示查询对象。

返回值：

类型	说明
Promise<KvStoreResultSet>	Promise对象。返回与指定Query对象匹配的KvStoreResultSet对象。

示例：

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + err);
    });
    const query = new distributedData.Query();
    query.deviceId('localDeviceId');
    query.prefixKey("batch_test");
    console.log("GetResultSet " + query.getSqlLike());
    kvStore.getResultSet(query).then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSet e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.

getResultSet⁸⁺

getResultSet(deviceId: string, query: Query, callback: AsyncCallback<KvStoreResultSet>): void

获取与指定设备ID和Query对象匹配的KvStoreResultSet对象，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	KvStoreResultSet对象所属的设备ID。
query	Query	是	表示查询对象。
callback	AsyncCallback<KvStoreResultSet>	是	回调函数。返回与指定设备ID和Query对象匹配的KvStoreResultSet对象。

示例：

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSet('localDeviceId', query, async function (err, result) {
            console.log('getResultSet succeed.');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                console.log('closeResultSet success');
            })
        });
    });
} catch(e) {
    console.log('GetResultSet e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.

getResultSet⁸⁺

getResultSet(deviceId: string, query: Query): Promise<KvStoreResultSet>

获取与指定设备ID和Query对象匹配的KvStoreResultSet对象，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	KvStoreResultSet对象所属的设备ID。
query	Query	是	表示查询对象。

返回值：

类型	说明
Promise<KvStoreResultSet>	Promise对象。返回与指定设备ID和Query对象匹配的KvStoreResultSet对象。

示例：

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('GetResultSet putBatch success');
    }).catch((err) => {
        console.log('PutBatch putBatch fail ' + JSON.stringify(err));
    });
    const query = new distributedData.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSet('localDeviceId', query).then((result) => {
        console.log('GetResultSet getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('GetResultSet getResultSet failed: ' + JSON.stringify(err));
    });
    query.deviceId('localDeviceId');
    console.log("GetResultSet " + query.getSqlLike());
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('GetResultSet closeResultSet success');
    }).catch((err) => {
        console.log('GetResultSet closeResultSet fail ' + JSON.stringify(err));
    });

}catch(e) {
    console.log('GetResultSet e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.

closeResultSet⁸⁺

closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void

关闭由DeviceKVStore.getResultSet返回的KvStoreResultSet对象，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
resultSet	KvStoreResultSet	是	指示要关闭的KvStoreResultSet对象。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
try {
    console.log('CloseResultSet success');
    let resultSet = null;
    kvStore.closeResultSet(resultSet, function (err, data) {
        if (err == undefined) {
            console.log('closeResultSet success');
        } else {
            console.log('closeResultSet fail');
        }
    });
}catch(e) {
    console.log('CloseResultSet e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.

closeResultSet⁸⁺

closeResultSet(resultSet: KvStoreResultSet): Promise<void>

关闭由DeviceKVStore.getResultSet返回的KvStoreResultSet对象，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
resultSet	KvStoreResultSet	是	指示要关闭的KvStoreResultSet对象。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

示例：

let kvStore;
try {
    console.log('CloseResultSet success');
    let resultSet = null;
    kvStore.closeResultSet(resultSet).then(() => {
        console.log('closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('CloseResultSet e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

getResultSize⁸⁺

getResultSize(query: Query, callback: AsyncCallback<number>): void

获取与指定Query对象匹配的结果数，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
query	Query	是	表示查询对象。
callback	AsyncCallback<number>	是	回调函数，返回与指定Query对象匹配的结果数。

示例：

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.getResultSize(query, async function (err, resultSize) {
            console.log('getResultSet succeed.');
        });
    });
} catch(e) {
    console.log('GetResultSize e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.

getResultSize⁸⁺

getResultSize(query: Query): Promise<number>

获取与指定Query对象匹配的结果数，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
query	Query	是	表示查询对象。

返回值：

类型	说明
Promise<number>	Promise对象。返回与指定Query对象匹配的结果数。

示例：

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
    const query = new distributedData.Query();
    query.prefixKey("batch_test");
    query.deviceId('localDeviceId');
    kvStore.getResultSize(query).then((resultSize) => {
        console.log('getResultSet succeed.');
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSize e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.

getResultSize⁸⁺

getResultSize(deviceId: string, query: Query, callback: AsyncCallback<number>): void;

获取与指定设备ID和Query对象匹配的结果数，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	KvStoreResultSet对象所属的设备ID。
query	Query	是	表示查询对象。
callback	AsyncCallback<number>	是	回调函数。返回与指定设备ID和Query对象匹配的结果数。

示例：

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSize('localDeviceId', query, async function (err, resultSize) {
            console.log('getResultSet succeed.');
        });
    });
} catch(e) {
    console.log('GetResultSize e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.

getResultSize⁸⁺

getResultSize(deviceId: string, query: Query): Promise<number>

获取与指定设备ID和Query对象匹配的结果数，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	KvStoreResultSet对象所属的设备ID。
query	Query	是	表示查询对象。

返回值：

类型	说明
Promise<number>	Promise对象。返回与指定设备ID和Query对象匹配的结果数。

示例：

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
    var query = new distributedData.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSize('localDeviceId', query).then((resultSize) => {
        console.log('getResultSet succeed.');
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSize e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.

removeDeviceData⁸⁺

removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void

从当前数据库中删除指定设备的数据，使用callback异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	标识要删除其数据的设备。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-string-001';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err,data) {
        console.log('RemoveDeviceData  put success');
        const deviceid = 'no_exist_device_id';
        kvStore.removeDeviceData(deviceid, async function (err,data) {
            if (err == undefined) {
                console.log('removeDeviceData success');
            } else {
                console.log('removeDeviceData fail');
                kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, async function (err,data) {
                    console.log('RemoveDeviceData get success');
                });
            }
        });
    });
}catch(e) {
    console.log('RemoveDeviceData e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.

removeDeviceData⁸⁺

removeDeviceData(deviceId: string): Promise<void>

从当前数据库中删除指定设备的数据，使用Promise异步回调。

系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数：

参数名	类型	必填	说明
deviceId	string	是	标识要删除其数据的设备。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-string-001';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((err) => {
        console.log('RemoveDeviceData put success');
    }).catch((err) => {
        console.log('RemoveDeviceData put fail ' + JSON.stringify(err));
    });
    const deviceid = 'no_exist_device_id';
    kvStore.removeDeviceData(deviceid).then((err) => {
        console.log('removeDeviceData success');
    }).catch((err) => {
        console.log('removeDeviceData fail ' + JSON.stringify(err));
    });
    kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => {
        console.log('RemoveDeviceData get success data:' + data);
    }).catch((err) => {
        console.log('RemoveDeviceData get fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('RemoveDeviceData e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.

sync⁸⁺

sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void

在手动同步方式下，触发数据库同步。关于分布式数据服务的同步方式说明，请见分布式数据服务概述。

此接口能力在HarmonyOS 3.1Beta1暂不支持。

需要权限： ohos.permission.DISTRIBUTED_DATASYNC。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
deviceIds	string[]	是	需要同步DeviceKvStore数据库的设备ID列表。
mode	SyncMode	是	同步模式。
delayMs	number	否	可选参数，允许延时时间，单位：ms（毫秒）。

示例：

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;
        kvStore.sync(devices, mode);
    });
}catch(e) {
    console.log('Sync e' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.

on('dataChange')⁸⁺

on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void

订阅指定类型的数据变更通知。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
event	string	是	订阅的事件名，固定为'dataChange'，表示数据变更事件。
type	SubscribeType	是	表示订阅的类型。
listener	Callback<ChangeNotification>	是	回调函数。

示例：

let kvStore;
kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) {
    console.log("dataChange callback call data: " + JSON.stringify(data));
});1.
2.
3.
4.

on('syncComplete')⁸⁺

on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void

订阅同步完成事件回调通知。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
event	string	是	订阅的事件名，固定为'syncComplete'，表示同步完成事件。
syncCallback	Callback<Array<[string, number]>>	是	回调函数。用于向调用方发送同步结果的回调。

示例：

let kvStore;
const KEY_TEST_FLOAT_ELEMENT = 'key_test_float';
const VALUE_TEST_FLOAT_ELEMENT = 321.12;
try {
    kvStore.on('syncComplete', function (data) {
        console.log('syncComplete ' + data)
    });
    kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then((data) => {
        console.log('syncComplete put success');
    }).catch((error) => {
        console.log('syncComplete put fail ' + error);
    });
}catch(e) {
    console.log('syncComplete put e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.

off('dataChange')⁸⁺

off(event:'dataChange', listener?: Callback<ChangeNotification>): void

取消订阅数据变更通知。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
event	string	是	取消订阅的事件名，固定为'dataChange'，表示数据变更事件。
listener	Callback<ChangeNotification>	否	回调函数。

示例：

let kvStore;
class KvstoreModel {
    call(data) {
        console.log("dataChange: " + data);
    }
    subscribeDataChange() {
        if (kvStore != null) {
            kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call);
        }
    }
    unsubscribeDataChange() {
        if (kvStore != null) {
            kvStore.off('dataChange', this.call);
        }
    }
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.

off('syncComplete')⁸⁺

off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void

取消订阅同步完成事件回调通知。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

参数：

参数名	类型	必填	说明
event	string	是	取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。
syncCallback	Callback<Array<[string, number]>>	否	回调函数。用于向调用方发送同步结果的回调。

示例：

let kvStore;
class KvstoreModel {
    call(data) {
        console.log("syncComplete: " + data);
    }
    subscribeSyncComplete() {
        if (kvStore != null) {
            kvStore.on('syncComplete', this.call);
        }
    }
    unsubscribeSyncComplete() {
        if (kvStore != null) {
            kvStore.off('syncComplete', this.call);
        }
    }
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.

SyncMode

同步模式枚举。

系统能力： SystemCapability.DistributedDataManager.KVStore.Core

名称	值	说明
PULL_ONLY	0	表示只能从远端拉取数据到本端。
PUSH_ONLY	1	表示只能从本端推送数据到远端。
PUSH_PULL	2	表示从本端推送数据到远端，然后从远端拉取数据到本端。

文章转载自：https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-distributed-data-0000001478181709-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001478181709__syncmode

分类

卡片开发

三方库

标签

HarmonyOS API

已于2023-4-4 16:36:18修改

51CTO

51CTO博客

51CTO学堂

HarmonyOSAPI：@ohos.data.distributedData (分布式数据管理)

@ohos.data.distributedData (分布式数据管理)

sync

on('dataChange')8+

on('syncComplete')8+

off('dataChange')8+

off('syncComplete')8+

setSyncParam8+

setSyncParam8+

getSecurityLevel8+

getSecurityLevel8+

DeviceKVStore8+

get8+

get8+

getEntries8+

getEntries8+

getEntries8+

getEntries8+

getEntries8+

getEntries8+

getResultSet8+​

getResultSet8+

getResultSet8+

getResultSet8+

getResultSet8+

getResultSet8+

closeResultSet8+

closeResultSet8+

getResultSize8+

getResultSize8+

getResultSize8+

getResultSize8+

removeDeviceData8+

removeDeviceData8+

sync8+

on('dataChange')8+

on('syncComplete')8+

off('dataChange')8+

off('syncComplete')8+

SyncMode

目录

订阅鸿蒙技术特刊，精选内容抢先看

on('dataChange')⁸⁺

on('syncComplete')⁸⁺

off('dataChange')⁸⁺

off('syncComplete')⁸⁺

setSyncParam⁸⁺

setSyncParam⁸⁺

getSecurityLevel⁸⁺

getSecurityLevel⁸⁺

DeviceKVStore⁸⁺

get⁸⁺

get⁸⁺

getEntries⁸⁺

getEntries⁸⁺

getEntries⁸⁺

getEntries⁸⁺

getEntries⁸⁺

getEntries⁸⁺

getResultSet⁸⁺

getResultSet⁸⁺

getResultSet⁸⁺

getResultSet⁸⁺

getResultSet⁸⁺

getResultSet⁸⁺

closeResultSet⁸⁺

closeResultSet⁸⁺

getResultSize⁸⁺

getResultSize⁸⁺

getResultSize⁸⁺

getResultSize⁸⁺

removeDeviceData⁸⁺

removeDeviceData⁸⁺

sync⁸⁺

on('dataChange')⁸⁺

on('syncComplete')⁸⁺

off('dataChange')⁸⁺

off('syncComplete')⁸⁺