分布式数据管理

说明： 从 API Version 7 开始支持。

导入模块

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

权限

无

distributedData.createKVManager

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

创建一个KVManager对象实例，用于管理数据库对象，并通过callback方式返回，此方法为异步方法。

• 参数：

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

• 示例：

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

distributedData.createKVManager

createKVManager(config: KVManagerConfig): Promise<KVManager>

创建一个KVManager对象实例，用于管理数据库对象，并通过Promise方式返回，此方法为异步方法。

• 参数：

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

• 返回值：

  类型	说明
  Promise<KVManager>	指定的Promise回调方法，返回创建的KVManager对象实例。

• 示例：

  let kvManager;
  try {
      const kvManagerConfig = {
          bundleName : 'com.example.datamanagertest',
          userInfo : {
              userId : '0',
              userType : 0
          }
      }
      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实例的配置信息，包括调用方的包名和用户信息。

UserInfo

用户信息。

UserType

用户类型。

KVManager

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

getKVStore

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

通过指定Options和storeId，创建并获取KVStore数据库，并通过callback方式返回，此方法为异步方法。

• 参数：

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

• 示例：

  let kvStore;
  try {
      const options = {
          createIfMissing : true,
          encrypt : false,
          backup : false,
          autoSync : true,
          kvStoreType : 1,
          securityLevel : 3,
      };
      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方式返回，此方法为异步方法。

• 参数：

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

• 返回值：

  类型	说明
  Promise<T> <T extends KVStore>	指定的Promise回调方法，返回创建的KVStore数据库实例。

• 示例：

  let kvStore;
  try {
      const options = {
          createIfMissing : true,
          encrypt : false,
          backup : false,
          autoSync : true,
          kvStoreType : 1,
          securityLevel : 3,
      };
      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);
  }

Options

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

KVStoreType

用于指定创建的数据库的类型。

SecurityLevel

用于指定创建的数据库的安全级别。

Constants

KVStore常量。

KVStore

KVStore数据库实例，提供增加数据、删除数据和订阅数据变更、订阅同步完成的方法。在调用KVStore的方法前，需要先通过getKVStore构建一个KVStore实例。

put

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

添加指定类型键值对到数据库，并通过callback方式返回，此方法为异步方法。

• 参数：

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

• 示例

  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);
  }

put

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

添加指定类型键值对到数据库，并通过Promise方式返回，此方法为异步方法。

• 参数：

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

• 返回值：

  类型	说明
  Promise<void>	Promise实例，用于异步处理。

• 示例

  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);
  }

delete

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

从数据库中删除指定键值的数据，并通过callback方式返回，此方法为异步方法。

• 参数：

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

• 示例

  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);
  }

delete

delete(key: string): Promise<void>

从数据库中删除指定键值的数据，并通过Promise方式返回，此方法为异步方法。

• 参数：

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

• 返回值：

  类型	说明
  Promise<void>	Promise实例，用于异步处理。

• 示例

  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);
  }

on

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

订阅指定类型的数据变更通知，此方法为同步方法。

• 参数：

  参数名	类型	说明
  event	'dataChange'	回调函数名称。
  type	SubscribeType	表示订阅的类型。
  observer	Callback<ChangeNotification>	回调函数。

• 示例

  kvStore.on('dataChange', 2, function (data) {
      console.log("dataChange callback call data: " + JSON.stringify(data));
  });

on

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

订阅数据同步完成通知，此方法为同步方法。

• 参数：

  参数名	类型	说明
  event	'syncComplete'	回调函数名称。
  syncCallback	Callback<Array<[string, number]>>	回调函数。

• 示例

  kvStore.on('syncComplete', function (data) {
      console.log("syncComplete callback call data: " + data);
  });

SubscribeType

描述订阅类型。

ChangeNotification

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

Entry

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

Value

存储在数据库中的对象。

ValueType

用于表示数据类型。

只能被内部应用使用。

SingleKVStore

单版本分布式数据库，继承自KVStore，提供查询数据和同步数据的方法。在调用SingleKVStore的方法前，需要先通过getKVStore构建一个KVStore实例。

get

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

获取指定键的值，并通过callback方式返回，此方法为异步方法。

• 参数：

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

• 示例

  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);
  }

get

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

获取指定键的值，并通过Promise方式返回，此方法为异步方法。

• 参数：

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

• 返回值：

  类型	说明
  Promise<Uint8Array | string | boolean | number>	Promise实例，用于获取异步返回结果。

• 示例

  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);
  }

sync

sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void

在手动同步模式下，触发数据库同步，此方法为同步方法。

• 参数：

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

• 示例：

  kvStore.sync(deviceIds, 1, 1000);

SyncMode

用于指定同步模式。