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

joytrian

发布于 2023-4-4 16:32

浏览

0收藏

版本：v3.1 Beta

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

更新时间: 2023-03-17 18:27

分布式数据管理为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式数据各个接口，应用程序可将数据保存到分布式数据库中，并可对分布式数据库中的数据进行增加、删除、修改、查询、同步等操作。

该模块提供以下分布式数据管理相关的常用功能：

KVManager：数据管理实例，用于获取KVStore的相关信息。
KvStoreResultSet⁸⁺：提供获取KVStore数据库结果集的相关方法，包括查询和移动数据读取位置等。
Query⁸⁺：使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。
KVStore：KVStore数据库实例，提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。
SingleKVStore：单版本分布式数据库，继承自KVStore，不对数据所属设备进行区分，提供查询数据和同步数据的方法。
DeviceKVStore⁸⁺：设备协同数据库，继承自KVStore，以设备维度对数据进行区分，提供查询数据和同步数据的方法。

说明

本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import distributedData from '@ohos.data.distributedData';

distributedData.createKVManager

createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void

创建一个KVManager对象实例，用于管理数据库对象，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
config	KVManagerConfig	是	提供KVManager实例的配置信息，包括调用方的包名和用户信息。
callback	AsyncCallback<KVManager>	是	回调函数。返回创建的KVManager对象实例。

示例：

let kvManager;
try {
    const kvManagerConfig = {
        bundleName : 'com.example.datamanagertest',
        userInfo : {
            userId : '0',
            userType : distributedData.UserType.SAME_USER_ID
        }
    }
    distributedData.createKVManager(kvManagerConfig, function (err, manager) {
        if (err) {
            console.log("Failed to create KVManager: "  + JSON.stringify(err));
            return;
        }
        console.log("Succeeded in creating KVManager");
        kvManager = manager;
    });
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

distributedData.createKVManager

createKVManager(config: KVManagerConfig): Promise<KVManager>

创建一个KVManager对象实例，用于管理数据库对象，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
config	KVManagerConfig	是	提供KVManager实例的配置信息，包括调用方的包名和用户信息。

返回值：

类型	说明
Promise<KVManager>	Promise对象。返回创建的KVManager对象实例。

示例：

let kvManager;
try {
    const kvManagerConfig = {
        bundleName : 'com.example.datamanagertest',
        userInfo : {
            userId : '0',
            userType : distributedData.UserType.SAME_USER_ID
        }
    }
    distributedData.createKVManager(kvManagerConfig).then((manager) => {
        console.log("createKVManager success");
        kvManager = manager;
    }).catch((err) => {
        console.log("createKVManager err: "  + JSON.stringify(err));
    });
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

KVManagerConfig

提供KVManager实例的配置信息，包括调用方的包名和用户信息。

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

名称	类型	必填	说明
userInfo	UserInfo	是	调用方的用户信息。
bundleName	string	是	调用方的包名。

UserInfo

用户信息。

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

名称	类型	必填	说明
userId	string	否	指示要设置的用户ID。
userType	UserType	否	指示要设置的用户类型。

UserType

用户类型枚举。

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

名称	值	说明
SAME_USER_ID	0	使用同一帐户登录不同设备的用户。

KVManager

数据管理实例，用于获取KVStore的相关信息。在调用KVManager的方法前，需要先通过createKVManager构建一个KVManager实例。

getKVStore

getKVStore<T extends KVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void

通过指定Options和storeId，创建并获取KVStore数据库，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
storeId	string	是	数据库唯一标识符，长度不大于MAX_STORE_ID_LENGTH。
options	Options	是	创建KVStore实例的配置信息。
callback	AsyncCallback<T>	是	回调函数。返回创建的KVStore数据库实例。

示例：

let kvStore;
let kvManager;
try {
    const options = {
        createIfMissing : true,
        encrypt : false,
        backup : false,
        autoSync : true,
        kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
        securityLevel : distributedData.SecurityLevel.S2,
    };
    kvManager.getKVStore('storeId', options, function (err, store) {
        if (err) {
            console.log("getKVStore err: "  + JSON.stringify(err));
            return;
        }
        console.log("getKVStore success");
        kvStore = store;
    });
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

getKVStore

getKVStore<T extends KVStore>(storeId: string, options: Options): Promise<T>

通过指定Options和storeId，创建并获取KVStore数据库，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
storeId	string	是	数据库唯一标识符，长度不大于MAX_STORE_ID_LENGTH。
options	Options	是	创建KVStore实例的配置信息。

返回值：

类型	说明
Promise<T> ，<T extends KVStore>	Promise对象。返回创建的KVStore数据库实例。

示例：

let kvStore;
let kvManager;
try {
    const options = {
        createIfMissing : true,
        encrypt : false,
        backup : false,
        autoSync : true,
        kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
        securityLevel : distributedData.SecurityLevel.S2,
    };
    kvManager.getKVStore('storeId', options).then((store) => {
        console.log("getKVStore success");
        kvStore = store;
    }).catch((err) => {
        console.log("getKVStore err: "  + JSON.stringify(err));
    });
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

closeKVStore⁸⁺

closeKVStore(appId: string, storeId: string, kvStore: KVStore, callback: AsyncCallback<void>): void

通过storeId的值关闭指定的KVStore数据库，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
appId	string	是	所调用数据库方的包名。
storeId	string	是	要关闭的数据库唯一标识符，长度不大于MAX_STORE_ID_LENGTH。
kvStore	KVStore	是	要关闭的KVStore数据库。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvStore;
let kvManager;
const options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: true,
    kvStoreType: distributedData.KVStoreType.SINGLE_VERSION,
    schema: '',
    securityLevel: distributedData.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('storeId', options, async function (err, store) {
        console.log('getKVStore success');
        kvStore = store;
        kvManager.closeKVStore('appId', 'storeId', kvStore, function (err, data) {
            console.log('closeKVStore success');
        });
    });
} catch (e) {
    console.log('closeKVStore e ' + e);
}

closeKVStore⁸⁺

closeKVStore(appId: string, storeId: string, kvStore: KVStore): Promise<void>

通过storeId的值关闭指定的KVStore数据库，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
appId	string	是	所调用数据库方的包名。
storeId	string	是	要关闭的数据库唯一标识符，长度不大于MAX_STORE_ID_LENGTH。
kvStore	KVStore	是	要关闭的KVStore数据库。

返回值：

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

示例：

let kvManager;
let kvStore;
const options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: true,
    kvStoreType: distributedData.KVStoreType.SINGLE_VERSION,
    schema: '',
    securityLevel: distributedData.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('storeId', options).then(async (store) => {
        console.log('getKVStore success');
        kvStore = store;
        kvManager.closeKVStore('appId', 'storeId', kvStore).then(() => {
            console.log('closeKVStore success');
        }).catch((err) => {
            console.log('closeKVStore err ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('CloseKVStore getKVStore err ' + JSON.stringify(err));
    });
} catch (e) {
    console.log('closeKVStore e ' + e);
}

deleteKVStore⁸⁺

deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void

通过storeId的值删除指定的KVStore数据库，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
appId	string	是	所调用数据库方的包名。
storeId	string	是	要删除的数据库唯一标识符，长度不大于MAX_STORE_ID_LENGTH。
callback	AsyncCallback<void>	是	回调函数。

示例：

let kvManager;
let kvStore;
const options = {
    createIfMissing : true,
    encrypt : false,
    backup : false,
    autoSync : true,
    kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
    schema : '',
    securityLevel : distributedData.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('store', options, async function (err, store) {
        console.log('getKVStore success');
        kvStore = store;
        kvManager.deleteKVStore('appId', 'storeId', function (err, data) {
            console.log('deleteKVStore success');
        });
    });
} catch (e) {
    console.log('DeleteKVStore e ' + e);
}

deleteKVStore⁸⁺

deleteKVStore(appId: string, storeId: string): Promise<void>

通过storeId的值删除指定的KVStore数据库，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
appId	string	是	所调用数据库方的包名。
storeId	string	是	要删除的数据库唯一标识符，长度不大于MAX_STORE_ID_LENGTH。

返回值：

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

示例：

let kvManager;
let kvStore;
const options = {
    createIfMissing : true,
    encrypt : false,
    backup : false,
    autoSync : true,
    kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
    schema : '',
    securityLevel : distributedData.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('storeId', options).then(async (store) => {
        console.log('getKVStore success');
        kvStore = store;
        kvManager.deleteKVStore('appId', 'storeId').then(() => {
            console.log('deleteKVStore success');
        }).catch((err) => {
            console.log('deleteKVStore err ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('getKVStore err ' + JSON.stringify(err));
    });
} catch (e) {
    console.log('deleteKVStore e ' + e);
}

getAllKVStoreId⁸⁺

getAllKVStoreId(appId: string, callback: AsyncCallback<string[]>): void

获取所有通过getKVStore方法创建的且没有调用deleteKVStore方法删除的KVStore数据库的storeId，使用callback异步回调。

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

参数：

参数名	类型	必填	说明
appId	string	是	所调用数据库方的包名。
callback	AsyncCallback<string[]>	是	回调函数。返回所有创建的KvStore数据库的storeId。

示例：

let kvManager;
try {
    kvManager.getAllKVStoreId('appId', function (err, data) {
        console.log('GetAllKVStoreId success');
        console.log('GetAllKVStoreId size = ' + data.length);
    });
} catch (e) {
    console.log('GetAllKVStoreId e ' + e);
}

getAllKVStoreId⁸⁺

getAllKVStoreId(appId: string): Promise<string[]>

获取所有通过getKVStore方法创建的且没有调用deleteKVStore方法删除的KVStore数据库的storeId，使用Promise异步回调。

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

参数：

参数名	类型	必填	说明
appId	string	是	所调用数据库方的包名。

返回值：

类型	说明
Promise<string[]>	Promise对象。返回所有创建的KvStore数据库的storeId。

示例：

let kvManager;
try {
    console.log('GetAllKVStoreId');
    kvManager.getAllKVStoreId('appId').then((data) => {
        console.log('getAllKVStoreId success');
        console.log('size = ' + data.length);
    }).catch((err) => {
        console.log('getAllKVStoreId err ' + JSON.stringify(err));
    });
} catch(e) {
    console.log('getAllKVStoreId e ' + e);
}

on('distributedDataServiceDie')⁸⁺

on(event: 'distributedDataServiceDie', deathCallback: Callback<void>): void

订阅服务状态变更通知。

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

参数：

参数名	类型	必填	说明
event	string	是	订阅的事件名，固定为'distributedDataServiceDie'，即服务状态变更事件。
deathCallback	Callback<void>	是	回调函数。

示例：

let kvManager;
try {
    console.log('KVManagerOn');
    const deathCallback = function () {
        console.log('death callback call');
    }
    kvManager.on('distributedDataServiceDie', deathCallback);
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

off('distributedDataServiceDie')⁸⁺

off(event: 'distributedDataServiceDie', deathCallback?: Callback<void>): void

取消订阅服务状态变更通知。

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

参数：

参数名	类型	必填	说明
event	string	是	取消订阅的事件名，固定为'distributedDataServiceDie'，即服务状态变更事件。
deathCallback	Callback<void>	否	回调函数。

示例：

let kvManager;
try {
    console.log('KVManagerOff');
    const deathCallback = function () {
        console.log('death callback call');
    }
    kvManager.off('distributedDataServiceDie', deathCallback);
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

Options

用于提供创建数据库的配置信息。

名称	类型	必填	说明
createIfMissing	boolean	否	当数据库文件不存在时是否创建数据库，默认创建。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
encrypt	boolean	否	设置数据库文件是否加密，默认不加密。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
backup	boolean	否	设置数据库文件是否备份，默认备份。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
autoSync	boolean	否	设置数据库文件是否自动同步，默认不自动同步。此接口能力在HarmonyOS 3.1Beta1暂不支持。系统能力： SystemCapability.DistributedDataManager.KVStore.Core 需要权限： ohos.permission.DISTRIBUTED_DATASYNC
kvStoreType	KVStoreType	否	设置要创建的数据库类型，默认为多设备协同数据库。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
securityLevel	SecurityLevel	否	设置数据库安全级别，默认不设置安全级别。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
schema⁸⁺	Schema	否	设置定义存储在数据库中的值。系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

KVStoreType

KVStore数据库类型枚举。

名称	值	说明
DEVICE_COLLABORATION	0	表示多设备协同数据库。数据库特点：数据以设备的维度管理，不存在冲突；支持按照设备的维度查询数据。系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
SINGLE_VERSION	1	表示单版本数据库。数据库特点：数据不分设备，设备之间修改相同的key会覆盖。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
MULTI_VERSION	2	表示多版本数据库。当前暂不支持使用此接口。系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

SecurityLevel

数据库的安全级别枚举。

名称	值	说明
NO_LEVEL	0	表示数据库不设置安全级别。系统能力： SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
S0	1	表示数据库的安全级别为公共级别。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
S1	2	表示数据库的安全级别为低级别，当数据泄露时会产生较低影响。例如，包含壁纸等系统数据的数据库。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
S2	3	表示数据库的安全级别为中级别，当数据泄露时会产生较大影响。例如，包含录音、视频等用户生成数据或通话记录等信息的数据库。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
S3	5	表示数据库的安全级别为高级别，当数据泄露时会产生重大影响。例如，包含用户运动、健康、位置等信息的数据库。系统能力： SystemCapability.DistributedDataManager.KVStore.Core
S4	6	表示数据库的安全级别为关键级别，当数据泄露时会产生严重影响。例如，包含认证凭据、财务数据等信息的数据库。系统能力： SystemCapability.DistributedDataManager.KVStore.Core

Constants

KVStore常量。

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

名称	值	说明
MAX_KEY_LENGTH	1024	数据库中Key允许的最大长度，单位字节。
MAX_VALUE_LENGTH	4194303	数据库中Value允许的最大长度，单位字节。
MAX_KEY_LENGTH_DEVICE	896	最大设备密钥长度，单位字节。
MAX_STORE_ID_LENGTH	128	数据库标识符允许的最大长度，单位字节。
MAX_QUERY_LENGTH	512000	最大查询长度，单位字节。
MAX_BATCH_SIZE	128	最大批处理操作数量。

Schema⁸⁺

表示数据库模式，可以在创建或打开数据库时创建Schema对象并将它们放入Options中。

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

名称	类型	可读	可写	说明
root⁸⁺	FieldNode	是	是	表示json根对象。
indexes⁸⁺	Array<string>	是	是	表示json类型的字符串数组。
mode⁸⁺	number	是	是	表示Schema的模式。
skip⁸⁺	number	是	是	Schema的跳跃大小。

constructor⁸⁺

constructor()

用于创建Schema实例的构造函数。

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

FieldNode⁸⁺

表示 Schema 实例的节点，提供定义存储在数据库中的值的方法。

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

名称	类型	可读	可写	说明
nullable⁸⁺	boolean	是	是	表示数据库字段是否可以为空。
default⁸⁺	string	是	是	表示Fieldnode的默认值。
type⁸⁺	number	是	是	表示指定节点对应数据类型的值。

constructor⁸⁺

constructor(name: string)

用于创建带有string字段FieldNode实例的构造函数。

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

参数：

参数名	类型	必填	说明
name	string	是	FieldNode的值。

appendChild⁸⁺

appendChild(child: FieldNode): boolean

在当前 FieldNode 中添加一个子节点。

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

参数：

参数名	类型	必填	说明
child	FieldNode	是	要附加的域节点。

返回值：

类型	说明
boolean	返回true表示子节点成功添加到FieldNode；返回false则表示操作失败。

示例：

import ddm from '@ohos.data.distributedData';
try {
    let node = new ddm.FieldNode("root");
    let child1 = new ddm.FieldNode("child1");
    let child2 = new ddm.FieldNode("child2");
    let child3 = new ddm.FieldNode("child3");
    node.appendChild(child1);
    node.appendChild(child2);
    node.appendChild(child3);
    console.log("appendNode " + JSON.stringify(node));
    child1 = null;
    child2 = null;
    child3 = null;
    node = null;
} catch (e) {
    console.log("AppendChild " + e);
}

KvStoreResultSet⁸⁺

提供获取KVStore数据库结果集的相关方法，包括查询和移动数据读取位置等。

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

getCount⁸⁺

getCount(): number

获取结果集中的总行数。

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

返回值：

类型	说明
number	返回数据的总行数。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const count = resultSet.getCount();
    console.log("getCount succeed:" + count);
} catch (e) {
    console.log("getCount failed: " + e);
}

getPosition⁸⁺

getPosition(): number

获取结果集中当前的读取位置。

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

返回值：

类型	说明
number	返回当前读取位置。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeeded.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const position = resultSet.getPosition();
    console.log("getPosition succeed:" + position);
} catch (e) {
    console.log("getPosition failed: " + e);
}

moveToFirst⁸⁺

moveToFirst(): boolean

将读取位置移动到第一行。如果结果集为空，则返回false。

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

返回值：

类型	说明
boolean	返回true表示操作成功；返回false则表示操作失败。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved1 = resultSet.moveToFirst();
    console.log("moveToFirst succeed: " + moved1);
} catch (e) {
    console.log("moveToFirst failed " + e);
}

moveToLast⁸⁺

moveToLast(): boolean

将读取位置移动到最后一行。如果结果集为空，则返回false。

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

返回值：

类型	说明
boolean	返回true表示操作成功；返回false则表示操作失败。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved2 = resultSet.moveToLast();
    console.log("moveToLast succeed:" + moved2);
} catch (e) {
    console.log("moveToLast failed: " + e);
}

moveToNext⁸⁺

moveToNext(): boolean

将读取位置移动到下一行。如果结果集为空，则返回false。

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

返回值：

类型	说明
boolean	返回true表示操作成功；返回false则表示操作失败。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved3 = resultSet.moveToNext();
    console.log("moveToNext succeed: " + moved3);
} catch (e) {
    console.log("moveToNext failed: " + e);
}

moveToPrevious⁸⁺

moveToPrevious(): boolean

将读取位置移动到上一行。如果结果集为空，则返回false。

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

返回值：

类型	说明
boolean	返回true表示操作成功；返回false则表示操作失败。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved4 = resultSet.moveToPrevious();
    console.log("moveToPrevious succeed:" + moved4);
} catch (e) {
    console.log("moveToPrevious failed: " + e);
}

move⁸⁺

move(offset: number): boolean

将读取位置移动到当前位置的相对偏移量。

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

参数：

参数名	类型	必填	说明
offset	number	是	表示与当前位置的相对偏移量，负偏移表示向后移动，正偏移表示向前移动。

返回值：

类型	说明
boolean	返回true表示操作成功；返回false则表示操作失败。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved5 = resultSet.move(1);
    console.log("move succeed:" + moved5);
} catch (e) {
    console.log("move failed: " + e);
}

moveToPosition⁸⁺

moveToPosition(position: number): boolean

将读取位置从 0 移动到绝对位置。

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

参数：

参数名	类型	必填	说明
position	number	是	表示绝对位置。

返回值：

类型	说明
boolean	返回true表示操作成功；返回false则表示操作失败。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved6 = resultSet.moveToPosition(1);
    console.log("moveToPosition succeed: " + moved6);
} catch (e) {
    console.log("moveToPosition failed: " + e);
}

isFirst⁸⁺

isFirst(): boolean

检查读取位置是否为第一行。

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

返回值：

类型	说明
boolean	返回true表示读取位置为第一行；返回false表示读取位置不是第一行。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const isfirst = resultSet.isFirst();
    console.log("Check isFirst succeed:" + isfirst);
} catch (e) {
    console.log("Check isFirst failed: " + e);
}

isLast⁸⁺

isLast(): boolean

检查读取位置是否为最后一行。

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

返回值：

类型	说明
boolean	返回true表示读取位置为最后一行；返回false表示读取位置不是最后一行。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const islast = resultSet.isLast();
    console.log("Check isLast succeed: " + islast);
} catch (e) {
    console.log("Check isLast failed: " + e);
}

isBeforeFirst⁸⁺

isBeforeFirst(): boolean

检查读取位置是否在第一行之前。

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

返回值：

类型	说明
boolean	返回true表示读取位置在第一行之前；返回false表示读取位置不在第一行之前。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const isbeforefirst = resultSet.isBeforeFirst();
    console.log("Check isBeforeFirst succeed: " + isbeforefirst);
} catch (e) {
    console.log("Check isBeforeFirst failed: " + e);
}

isAfterLast⁸⁺

isAfterLast(): boolean

检查读取位置是否在最后一行之后。

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

返回值：

类型	说明
boolean	返回true表示读取位置在最后一行之后；返回false表示读取位置不在最后一行之后。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const isafterlast = resultSet.isAfterLast();
    console.log("Check isAfterLast succeed:" + isafterlast);
} catch (e) {
    console.log("Check isAfterLast failed: " + e);
}

getEntry⁸⁺

getEntry(): Entry

从当前位置获取对应的键值对。

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

返回值：

类型	说明
Entry	返回键值对。

示例：

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const entry  = resultSet.getEntry();
    console.log("getEntry succeed:" + JSON.stringify(entry));
} catch (e) {
    console.log("getEntry failed: " + e);
}

Query⁸⁺

使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。

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

constructor⁸⁺

constructor()

用于创建Schema实例的构造函数。

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

reset⁸⁺

reset(): Query

重置Query对象。

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

返回值：

类型	说明
Query	返回重置的Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.equalTo("key", "value");
    console.log("query is " + query.getSqlLike());
    query.reset();
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("simply calls should be ok :" + e);
}

equalTo⁸⁺

equalTo(field: string, value: number|string|boolean): Query

构造一个Query对象来查询具有指定字段的条目，其值等于指定的值。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
value	number\|string\|boolean	是	表示指定的值。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.equalTo("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

notEqualTo⁸⁺

notEqualTo(field: string, value: number|string|boolean): Query

构造一个Query对象以查询具有指定字段且值不等于指定值的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
value	number\|string\|boolean	是	表示指定的值。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

greaterThan⁸⁺

greaterThan(field: string, value: number|string|boolean): Query

构造一个Query对象以查询具有大于指定值的指定字段的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
value	number\|string\|boolean	是	表示指定的值。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.greaterThan("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

lessThan⁸⁺

lessThan(field: string, value: number|string): Query

构造一个Query对象以查询具有小于指定值的指定字段的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
value	number\|string	是	表示指定的值。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.lessThan("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

greaterThanOrEqualTo⁸⁺

greaterThanOrEqualTo(field: string, value: number|string): Query

构造一个Query对象以查询具有指定字段且值大于或等于指定值的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
value	number\|string	是	表示指定的值。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.greaterThanOrEqualTo("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

lessThanOrEqualTo⁸⁺

lessThanOrEqualTo(field: string, value: number|string): Query

构造一个Query对象以查询具有指定字段且值小于或等于指定值的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
value	number\|string	是	表示指定的值。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.lessThanOrEqualTo("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

isNull⁸⁺

isNull(field: string): Query

构造一个Query对象以查询具有值为null的指定字段的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.isNull("field");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

inNumber⁸⁺

inNumber(field: string, valueList: number[]): Query

构造一个Query对象以查询具有指定字段的条目，其值在指定的值列表中。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
valueList	number[]	是	表示指定的值列表。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.inNumber("field", [0, 1]);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

inString⁸⁺

inString(field: string, valueList: string[]): Query

构造一个Query对象以查询具有指定字段的条目，其值在指定的字符串值列表中。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
valueList	string[]	是	表示指定的字符串值列表。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.inString("field", ['test1', 'test2']);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

notInNumber⁸⁺

notInNumber(field: string, valueList: number[]): Query

构造一个Query对象以查询具有指定字段的条目，该字段的值不在指定的值列表中。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
valueList	number[]	是	表示指定的值列表。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.notInNumber("field", [0, 1]);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

notInString⁸⁺

notInString(field: string, valueList: string[]): Query

构造一个Query对象以查询具有指定字段且值不在指定字符串值列表中的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
valueList	string[]	是	表示指定的字符串值列表。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.notInString("field", ['test1', 'test2']);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

like⁸⁺

like(field: string, value: string): Query

构造一个Query对象以查询具有与指定字符串值相似的指定字段的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
value	string	是	表示指定的字符串值。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.like("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

unlike⁸⁺

unlike(field: string, value: string): Query

构造一个Query对象以查询具有与指定字符串值不相似的指定字段的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。
value	string	是	表示指定的字符串值。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.unlike("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

and⁸⁺

and(): Query

构造一个带有与条件的查询对象。

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

返回值：

类型	说明
Query	返回查询对象。

示例：

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value1");
    query.and();
    query.notEqualTo("field", "value2");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

or⁸⁺

or(): Query

构造一个带有或条件的Query对象。

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

返回值：

类型	说明
Query	返回查询对象。

示例：

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value1");
    query.or();
    query.notEqualTo("field", "value2");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

orderByAsc⁸⁺

orderByAsc(field: string): Query

构造一个Query对象，将查询结果按升序排序。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value");
    query.orderByAsc("field");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

orderByDesc⁸⁺

orderByDesc(field: string): Query

构造一个Query对象，将查询结果按降序排序。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value");
    query.orderByDesc("field");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

limit⁸⁺

limit(total: number, offset: number): Query

构造一个Query对象来指定结果的数量和开始位置。

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

参数：

参数名	类型	必填	说明
total	number	是	表示指定的结果数。
offset	number	是	表示起始位置。

返回值：

类型	说明
Query	返回Query对象。

示例：

let total = 10;
let offset = 1;
try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value");
    query.limit(total, offset);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

isNotNull⁸⁺

isNotNull(field: string): Query

构造一个Query对象以查询具有值不为null的指定字段的条目。

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

参数：

参数名	类型	必填	说明
fieId	string	是	表示指定字段，不能包含' ^ '。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.isNotNull("field");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

beginGroup⁸⁺

beginGroup(): Query

创建一个带有左括号的查询条件组。

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

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.beginGroup();
    query.isNotNull("field");
    query.endGroup();
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

endGroup⁸⁺

endGroup(): Query

创建一个带有右括号的查询条件组。

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

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.beginGroup();
    query.isNotNull("field");
    query.endGroup();
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

prefixKey⁸⁺

prefixKey(prefix: string): Query

创建具有指定键前缀的查询条件。

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

参数：

参数名	类型	必填	说明
prefix	string	是	表示指定的键前缀。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.prefixKey("$.name");
    query.prefixKey("0");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

setSuggestIndex⁸⁺

setSuggestIndex(index: string): Query

设置一个指定的索引，将优先用于查询。

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

参数：

参数名	类型	必填	说明
index	string	是	指示要设置的索引。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.setSuggestIndex("$.name");
    query.setSuggestIndex("0");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
   console.log("duplicated calls should be ok :" + e);
}

deviceId⁸⁺

deviceId(deviceId:string):Query

添加设备ID作为key的前缀。

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

参数：

参数名	类型	必填	说明
deviceId	string	是	指示查询的设备ID。

返回值：

类型	说明
Query	返回Query对象。

示例：

try {
    let query = new distributedData.Query();
    query.deviceId("deviceId");
    console.log("query is " + query.getSqlLike());
} catch (e) {
    console.log("should be ok on Method Chaining : " + e);
}

getSqlLike⁸⁺

getSqlLike():string

获取Query对象的查询语句。

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

返回值：

类型	说明
string	返回一个字段列中包含对应子串的结果。

示例：

try {
    let query = new distributedData.Query();
    let sql1 = query.getSqlLike();
    console.log("GetSqlLike sql=" + sql1);
} catch (e) {
    console.log("duplicated calls should be ok : " + e);
}

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

分类

卡片开发

三方件

标签

HarmonyOS API

已于2023-4-4 16:32:25修改

51CTO

51CTO博客

51CTO学堂

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

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

导入模块

distributedData.createKVManager

distributedData.createKVManager

KVManagerConfig

UserInfo

UserType

KVManager

getKVStore

getKVStore

closeKVStore8+

closeKVStore8+

deleteKVStore8+

deleteKVStore8+

getAllKVStoreId8+

getAllKVStoreId8+

on('distributedDataServiceDie')8+

off('distributedDataServiceDie')8+

Options

KVStoreType

SecurityLevel

Constants

Schema8+

constructor8+

FieldNode8+

constructor8+

appendChild8+

KvStoreResultSet8+

getCount8+

getPosition8+

moveToFirst8+

moveToLast8+

moveToNext8+

moveToPrevious8+

move8+

moveToPosition8+

isFirst8+

isLast8+

isBeforeFirst8+

isAfterLast8+

getEntry8+

Query8+

constructor8+

reset8+

equalTo8+

notEqualTo8+

greaterThan8+

lessThan8+

greaterThanOrEqualTo8+

lessThanOrEqualTo8+

isNull8+

inNumber8+

inString8+

notInNumber8+

notInString8+

like8+

unlike8+

and8+

or8+

orderByAsc8+

orderByDesc8+

limit8+

isNotNull8+

beginGroup8+

endGroup8+

prefixKey8+

setSuggestIndex8+

deviceId8+

getSqlLike8+

目录

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

closeKVStore⁸⁺

closeKVStore⁸⁺

deleteKVStore⁸⁺

deleteKVStore⁸⁺

getAllKVStoreId⁸⁺

getAllKVStoreId⁸⁺

on('distributedDataServiceDie')⁸⁺

off('distributedDataServiceDie')⁸⁺

Schema⁸⁺

constructor⁸⁺

FieldNode⁸⁺

constructor⁸⁺

appendChild⁸⁺

KvStoreResultSet⁸⁺

getCount⁸⁺

getPosition⁸⁺

moveToFirst⁸⁺

moveToLast⁸⁺

moveToNext⁸⁺

moveToPrevious⁸⁺

move⁸⁺

moveToPosition⁸⁺

isFirst⁸⁺

isLast⁸⁺

isBeforeFirst⁸⁺

isAfterLast⁸⁺

getEntry⁸⁺

Query⁸⁺

constructor⁸⁺

reset⁸⁺

equalTo⁸⁺

notEqualTo⁸⁺

greaterThan⁸⁺

lessThan⁸⁺

greaterThanOrEqualTo⁸⁺

lessThanOrEqualTo⁸⁺

isNull⁸⁺

inNumber⁸⁺

inString⁸⁺

notInNumber⁸⁺

notInString⁸⁺

like⁸⁺

unlike⁸⁺

and⁸⁺

or⁸⁺

orderByAsc⁸⁺

orderByDesc⁸⁺

limit⁸⁺

isNotNull⁸⁺

beginGroup⁸⁺

endGroup⁸⁺

prefixKey⁸⁺

setSuggestIndex⁸⁺

deviceId⁸⁺

getSqlLike⁸⁺