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

joytrian

发布于 2023-4-4 16:33

浏览

0收藏

版本：v3.1 Beta

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

KVStore

KVStore数据库实例，提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。

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

put

put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void

添加指定类型键值对到数据库，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要添加数据的key，不能为空且长度不大于MAX_KEY_LENGTH。
value	Uint8Array \| string \| number \| boolean	是	要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于MAX_VALUE_LENGTH。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) {
        if (err != undefined) {
            console.log("put err: " + JSON.stringify(err));
            return;
        }
        console.log("put success");
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.

put

put(key: string, value: Uint8Array | string | number | boolean): Promise<void>

添加指定类型键值对到数据库，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要添加数据的key，不能为空且长度不大于MAX_KEY_LENGTH。
value	Uint8Array \| string \| number \| boolean	是	要添加数据的value，支持Uint8Array、number、 string、boolean，Uint8Array、string 的长度不大于MAX_VALUE_LENGTH。

返回值：

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

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => {
        console.log("put success: " + JSON.stringify(data));
    }).catch((err) => {
        console.log("put err: " + JSON.stringify(err));
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

delete

delete(key: string, callback: AsyncCallback<void>): void

从数据库中删除指定键值的数据，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要删除数据的key，不能为空且长度不大于MAX_KEY_LENGTH。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) {
        if (err != undefined) {
            console.log("put err: " + JSON.stringify(err));
            return;
        }
        console.log("put success");
        kvStore.delete(KEY_TEST_STRING_ELEMENT, function (err,data) {
            if (err != undefined) {
                console.log("delete err: " + JSON.stringify(err));
                return;
            }
            console.log("delete success");
        });
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.

delete

delete(key: string): Promise<void>

从数据库中删除指定键值的数据，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要删除数据的key，不能为空且长度不大于MAX_KEY_LENGTH。

返回值：

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

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => {
        console.log("put success: " + JSON.stringify(data));
        kvStore.delete(KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log("delete success");
        }).catch((err) => {
            console.log("delete err: " + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log("put err: " + JSON.stringify(err));
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

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;
kvStore.on('syncComplete', function (data) {
    console.log("callback call data: " + data);
});1.
2.
3.
4.

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.

putBatch⁸⁺

putBatch(entries: Entry[], callback: AsyncCallback<void>): void

批量插入键值对到KVStore数据库中，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
entries	Entry[]	是	表示要批量插入的键值对。
callback	AsyncCallback<void>	是	回调函数。

示例：

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: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        kvStore.getEntries('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 ' + JSON.stringify(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.

putBatch⁸⁺

putBatch(entries: Entry[]): Promise<void>

批量插入键值对到KVStore数据库中，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
entries	Entry[]	是	表示要批量插入的键值对。

返回值：

类型	说明
Promise<void>	无返回结果的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: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        kvStore.getEntries('batch_test_string_key').then((entries) => {
            console.log('getEntries success');
            console.log('PutBatch ' + JSON.stringify(entries));
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('PutBatch e ' + JSON.stringify(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.

deleteBatch⁸⁺

deleteBatch(keys: string[], callback: AsyncCallback<void>): void

批量删除KVStore数据库中的键值对，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
keys	string[]	是	表示要批量删除的键值对。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
try {
    let entries = [];
    let keys = [];
    for (var i = 0; i < 5; 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);
        keys.push(key + i);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        kvStore.deleteBatch(keys, async function (err,data) {
            console.log('deleteBatch success');
        });
    });
}catch(e) {
    console.log('DeleteBatch 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.

deleteBatch⁸⁺

deleteBatch(keys: string[]): Promise<void>

批量删除KVStore数据库中的键值对，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
keys	string[]	是	表示要批量删除的键值对。

返回值：

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

示例：

let kvStore;
try {
    let entries = [];
    let keys = [];
    for (var i = 0; i < 5; 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);
        keys.push(key + i);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        kvStore.deleteBatch(keys).then((err) => {
            console.log('deleteBatch success');
        }).catch((err) => {
            console.log('deleteBatch fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('DeleteBatch 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.

startTransaction⁸⁺

startTransaction(callback: AsyncCallback<void>): void

启动KVStore数据库中的事务，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
function putBatchString(len, prefix) {
    let entries = [];
    for (var i = 0; i < len; i++) {
        var entry = {
            key : prefix + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    return entries;
}
try {
    var count = 0;
    kvStore.on('dataChange', 0, function (data) {
        console.log('startTransaction 0' + data)
        count++;
    });
    kvStore.startTransaction(async function (err,data) {
        console.log('startTransaction success');
        let entries = putBatchString(10, 'batch_test_string_key');
        console.log('entries: ' + JSON.stringify(entries));
        kvStore.putBatch(entries, async function (err,data) {
            console.log('putBatch success');
        });
    });
}catch(e) {
    console.log('startTransaction 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.

startTransaction⁸⁺

startTransaction(): Promise<void>

启动KVStore数据库中的事务，使用Promise异步回调。

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

返回值：

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

示例：

let kvStore;
try {
    var count = 0;
    kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) {
        console.log('startTransaction ' + JSON.stringify(data));
        count++;
    });
    kvStore.startTransaction().then(async (err) => {
        console.log('startTransaction success');
    }).catch((err) => {
        console.log('startTransaction fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('startTransaction e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.

commit⁸⁺

commit(callback: AsyncCallback<void>): void

提交KVStore数据库中的事务，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。

示例：

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

commit⁸⁺

commit(): Promise<void>

提交KVStore数据库中的事务，使用Promise异步回调。

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

返回值：

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

示例：

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

rollback⁸⁺

rollback(callback: AsyncCallback<void>): void

在KVStore数据库中回滚事务，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。

示例：

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

rollback⁸⁺

rollback(): Promise<void>

在KVStore数据库中回滚事务，使用Promise异步回调。

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

返回值：

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

示例：

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

enableSync⁸⁺

enableSync(enabled: boolean, callback: AsyncCallback<void>): void

设定是否开启同步，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
enabled	boolean	是	设定是否开启同步，true表示开启同步，false表示不启用同步。
callback	AsyncCallback<void>	是	回调函数。

示例：

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

enableSync⁸⁺

enableSync(enabled: boolean): Promise<void>

设定是否开启同步，使用Promise异步回调。

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

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

参数：

参数名	类型	必填	说明
enabled	boolean	是	设定是否开启同步，true表示开启同步，false表示不启用同步。

返回值：

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

示例：

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

setSyncRange⁸⁺

setSyncRange(localLabels: string[], remoteSupportLabels: string[], callback: AsyncCallback<void>): void

设置同步范围标签，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
localLabels	string[]	是	表示本地设备的同步标签。
remoteSupportLabels	string[]	是	表示要同步数据的设备的同步标签。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
try {
    const localLabels = ['A', 'B'];
    const remoteSupportLabels = ['C', 'D'];
    kvStore.setSyncRange(localLabels, remoteSupportLabels, function (err,data) {
        console.log('SetSyncRange put success');
    });
}catch(e) {
    console.log('SetSyncRange e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

setSyncRange⁸⁺

setSyncRange(localLabels: string[], remoteSupportLabels: string[]): Promise<void>

设置同步范围标签，使用Promise异步回调。

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

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

参数：

参数名	类型	必填	说明
localLabels	string[]	是	表示本地设备的同步标签。
remoteSupportLabels	string[]	是	表示要同步数据的设备的同步标签。

返回值：

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

示例：

let kvStore;
try {
    const localLabels = ['A', 'B'];
    const remoteSupportLabels = ['C', 'D'];
    kvStore.setSyncRange(localLabels, remoteSupportLabels).then((err) => {
        console.log('setSyncRange success');
    }).catch((err) => {
        console.log('delete fail ' + err);
    });
}catch(e) {
    console.log('SetSyncRange e ' + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

SubscribeType

订阅类型枚举。

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

名称	值	说明
SUBSCRIBE_TYPE_LOCAL	0	表示订阅本地数据变更。
SUBSCRIBE_TYPE_REMOTE	1	表示订阅远端数据变更。
SUBSCRIBE_TYPE_ALL	2	表示订阅远端和本地数据变更。

ChangeNotification

数据变更时通知的对象，包括数据插入的数据、更新的数据、删除的数据和设备ID。

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

名称	类型	必填	说明
insertEntries	Entry[]	是	数据添加记录。
updateEntries	Entry[]	是	数据更新记录。
deleteEntries	Entry[]	是	数据删除记录。
deviceId	string	是	设备ID，此处为设备UUID。

Entry

存储在数据库中的键值对。

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

名称	类型	必填	说明
key	string	是	键值。
value	Value	是	值对象。

Value

存储在数据库中的值对象。

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

名称	类型	必填	说明
type	ValueType	是	值类型。
value	Uint8Array \| string \| number \| boolean	是	值。

ValueType

数据类型枚举。

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

名称	值	说明
STRING	0	表示值类型为字符串。
INTEGER	1	表示值类型为整数。
FLOAT	2	表示值类型为浮点数。
BYTE_ARRAY	3	表示值类型为字节数组。
BOOLEAN	4	表示值类型为布尔值。
DOUBLE	5	表示值类型为双浮点数。

SingleKVStore

单版本数据库，继承自KVStore数据库，提供查询数据和同步数据的方法。

单版本数据库，不对数据所属设备进行区分，不同设备使用相同键写入数据会互相覆盖。比如，可以使用单版本数据库实现个人日历、联系人数据在不同设备间的数据同步。

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

get

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

获取指定键的值，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要查询数据的key，不能为空且长度不大于MAX_KEY_LENGTH。
callback	AsyncCallback<Uint8Array \| string \| boolean \| number>	是	回调函数。返回获取查询的值。

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) {
        if (err != undefined) {
            console.log("put err: " + JSON.stringify(err));
            return;
        }
        console.log("put success");
        kvStore.get(KEY_TEST_STRING_ELEMENT, function (err,data) {
            console.log("get success data: " + data);
        });
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

get

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

获取指定键的值，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
key	string	是	要查询数据的key，不能为空且长度不大于MAX_KEY_LENGTH。

返回值：

类型	说明
Promise<Uint8Array \| string \| boolean \| number>	Promise对象。返回获取查询的值。

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => {
        console.log("put success: " + JSON.stringify(data));
        kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log("get success data: " + data);
        }).catch((err) => {
            console.log("get err: " + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log("put err: " + JSON.stringify(err));
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

getEntries⁸⁺

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

获取匹配指定键前缀的所有键值对，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
keyPrefix	string	是	表示要匹配的键前缀。
callback	AsyncCallback<Entry[]>	是	回调函数。返回匹配指定前缀的键值对列表。

示例：

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_number_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.INTEGER,
                value : 222
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        kvStore.getEntries('batch_test_number_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.

getEntries⁸⁺

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

获取匹配指定键前缀的所有键值对，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
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('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.Core

参数：

参数名	类型	必填	说明
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");
        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.

getEntries⁸⁺

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

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

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

参数：

参数名	类型	必填	说明
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.

getResultSet⁸⁺

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

从KvStore数据库中获取具有指定前缀的结果集，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
keyPrefix	string	是	表示要匹配的键前缀。
callback	AsyncCallback<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('GetResultSet putBatch success');
        kvStore.getResultSet('batch_test_string_key', async function (err, result) {
            console.log('GetResultSet getResultSet succeed.');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                console.log('GetResultSet 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.

getResultSet⁸⁺

getResultSet(keyPrefix: string): Promise<KvStoreResultSet>

从KVStore数据库中获取具有指定前缀的结果集，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
keyPrefix	string	是	表示要匹配的键前缀。

返回值：

类型	说明
Promise<KvStoreResultSet>	Promise对象。返回具有指定前缀的结果集。

示例：

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 putBatch fail ' + JSON.stringify(err));
    });
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('GetResult getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('GetResult closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResult 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.

getResultSet⁸⁺

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

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

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

参数：

参数名	类型	必填	说明
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");
        kvStore.getResultSet(query, async function (err, result) {
            console.log('getResultSet succeed.');
            resultSet = result;
        });
    });
} 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.

getResultSet⁸⁺

getResultSet(query: Query): Promise<KvStoreResultSet>

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

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

参数：

参数名	类型	必填	说明
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 ' + JSON.stringify(err));
    });
    const query = new distributedData.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSet(query).then((result) => {
        console.log(' getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + 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.

closeResultSet⁸⁺

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

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

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

参数：

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

示例：

let kvStore;
try {
    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.

closeResultSet⁸⁺

closeResultSet(resultSet: KvStoreResultSet): Promise<void>

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

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

参数：

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

返回值：

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

示例：

let kvStore;
try {
    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.

getResultSize⁸⁺

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

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

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

参数：

参数名	类型	必填	说明
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");
        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.

getResultSize⁸⁺

getResultSize(query: Query): Promise<number>

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

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

参数：

参数名	类型	必填	说明
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");
    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.

removeDeviceData⁸⁺

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

删除指定设备的数据，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
deviceId	string	是	表示要删除设备的名称。
callback	AsyncCallback<void>	是	回调函数。

示例：

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');
        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(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.Core

参数：

参数名	类型	必填	说明
deviceId	string	是	表示要删除设备的名称。

返回值：

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

示例：

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string_2';
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('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(KEY_TEST_STRING_ELEMENT).then((data) => {
        console.log('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.

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

分类

卡片开发

三方库

标签

HarmonyOS API

已于2023-4-4 16:33:04修改

51CTO

51CTO博客

51CTO学堂

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

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

KVStore

put

put

delete

delete

on('dataChange')

on('syncComplete')

off('dataChange')8+

off('syncComplete')8+

putBatch8+

putBatch8+

deleteBatch8+

deleteBatch8+

startTransaction8+

startTransaction8+

commit8+

commit8+

rollback8+

rollback8+

enableSync8+

enableSync8+

setSyncRange8+

setSyncRange8+

SubscribeType

ChangeNotification

Entry

Value

ValueType

SingleKVStore

get

get

getEntries8+

getEntries8+

getEntries8+

getEntries8+

getResultSet8+​

getResultSet8+

getResultSet8+

getResultSet8+

closeResultSet8+

closeResultSet8+

getResultSize8+

getResultSize8+

removeDeviceData8+

removeDeviceData8+

目录

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

off('dataChange')⁸⁺

off('syncComplete')⁸⁺

putBatch⁸⁺

putBatch⁸⁺

deleteBatch⁸⁺

deleteBatch⁸⁺

startTransaction⁸⁺

startTransaction⁸⁺

commit⁸⁺

commit⁸⁺

rollback⁸⁺

rollback⁸⁺

enableSync⁸⁺

enableSync⁸⁺

setSyncRange⁸⁺

setSyncRange⁸⁺

getEntries⁸⁺

getEntries⁸⁺

getEntries⁸⁺

getEntries⁸⁺

getResultSet⁸⁺

getResultSet⁸⁺

getResultSet⁸⁺

getResultSet⁸⁺

closeResultSet⁸⁺

closeResultSet⁸⁺

getResultSize⁸⁺

getResultSize⁸⁺

removeDeviceData⁸⁺

removeDeviceData⁸⁺