分布式数据对象


分布式数据对象

本模块提供管理基本数据对象的相关能力,包括创建、查询、删除、修改、订阅等;同时支持相同应用多设备间的分布式数据对象协同能力。

说明:

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

导入模块

import distributedObject from '@ohos.data.distributedDataObject';
1

distributedDataObject.createDistributedObject

createDistributedObject(source: object): DistributedObject

创建一个分布式数据对象。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
source object 设置分布式数据对象的属性。

返回值:

类型 说明
DistributedObject 创建完成的分布式数据对象。

示例:

import distributedObject from '@ohos.data.distributedDataObject';
// 创建对象,对象包含4个属性类型,string,number,boolean和Object
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
1
2
3

distributedObject.genSessionId

genSessionId(): string

随机创建一个sessionId。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

返回值:

类型 说明
string 随机创建的sessionId。

示例:

import distributedObject from '@ohos.data.distributedDataObject';
var sessionId = distributedObject.genSessionId();
1
2

SaveSuccessResponse9+

save接口回调信息。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

名称 类型 说明
sessionId string 多设备协同的唯一标识。
version number 已保存对象的版本。
deviceId string 存储数据的设备号,标识需要保存对象的设备。默认为"local",标识本地设备;可自定义设置其他标识设备的字符串。

RevokeSaveSuccessResponse9+

revokeSave接口回调信息。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

名称 类型 说明
sessionId string 多设备协同的唯一标识。

DistributedObject

表示一个分布式数据对象。

setSessionId

setSessionId(sessionId?: string): boolean

设置同步的sessionId,当可信组网中有多个设备时,多个设备间的对象如果设置为同一个sessionId,就能自动同步。

需要权限: ohos.permission.DISTRIBUTED_DATASYNC。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
sessionId string 分布式数据对象在可信组网中的标识ID。如果要退出分布式组网,设置为""或不设置均可。

返回值:

类型 说明
boolean true:标识设置sessionId成功。
false:标识设置sessionId失败。

示例:

import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});;
// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId());
// 设置为""退出分布式组网
g_object.setSessionId("");
1
2
3
4
5
6

on('change')

on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void

监听分布式数据对象的变更。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
type string 事件类型,固定为'change',表示数据变更。
callback Callback<{ sessionId: string, fields: Array<string> }> 变更回调对象实例。
sessionId:标识变更对象的sessionId;
fields:标识对象变更的属性名。

示例:

import distributedObject from '@ohos.data.distributedDataObject';  
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
globalThis.changeCallback = (sessionId, changeData) => {
    console.info("change" + sessionId);
    if (changeData != null && changeData != undefined) {
        changeData.forEach(element => {
        console.info("changed !" + element + " " + g_object[element]);
        });
    }
}
g_object.on("change", globalThis.changeCallback);
1
2
3
4
5
6
7
8
9
10
11

off('change')

off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void

当不再进行数据变更监听时,使用此接口删除对象的变更监听。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
type string 事件类型,固定为'change',表示数据变更。
callback Callback<{ sessionId: string, fields: Array<string> }> 需要删除的数据变更回调,若不设置则删除该对象所有的数据变更回调。
sessionId:标识变更对象的sessionId;
fields:标识对象变更的属性名。

示例:

import distributedObject from '@ohos.data.distributedDataObject';  
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
// 删除数据变更回调changeCallback
g_object.off("change", globalThis.changeCallback);
// 删除所有的数据变更回调
g_object.off("change");
1
2
3
4
5
6

on('status')

on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void

监听分布式数据对象的上下线。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
type string 事件类型,固定为'status',表示对象上下线。
callback Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }> 监听上下线回调实例。
sessionId:标识变更对象的sessionId;
networkId:标识对象设备,即deviceId;
status:标识对象为'online'(上线)或'offline'(下线)的状态。

示例:

import distributedObject from '@ohos.data.distributedDataObject';
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
}
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
g_object.on("status", globalThis.statusCallback);
1
2
3
4
5
6

off('status')

off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void

当不再进行对象上下线监听时,使用此接口删除对象的上下线监听。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
type string 事件类型,固定为'status',表示对象上下线。
callback Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }> 需要删除的上下线回调,若不设置则删除该对象所有的上下线回调。
sessionId:标识变更对象的sessionId;
deviceId:标识变更对象的deviceId;
status:标识对象为'online'(上线)或'offline'(下线)的状态。

示例:

import distributedObject from '@ohos.data.distributedDataObject'; 
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
}
// 删除上下线回调changeCallback
g_object.off("status",globalThis.statusCallback);
// 删除所有的上下线回调
g_object.off("status");
1
2
3
4
5
6
7
8
9

save9+

save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void

保存分布式数据对象。使用callback方式异步回调。

对象数据保存成功后,当应用存在时不会释放对象数据,当应用退出后,重新进入应用时,恢复保存在设备上的数据。

有以下几种情况时,保存的数据将会被释放:

  • 存储时间超过24小时。
  • 应用卸载。
  • 成功恢复数据之后。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
deviceId string 保存数据的deviceId,当deviceId为"local",代表存储在本地设备。
callback AsyncCallback<SaveSuccessResponse> 回调函数。返回SaveSuccessResponse,包含sessionId、version、deviceId等信息。

示例:

import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
g_object.setSessionId("123456");
g_object.save("local", (status, result) => {
    console.log("save status = " + status);
    console.log("save callback");
    console.info("save sessionId: " + result.sessionId);
    console.info("save version: " + result.version);
    console.info("save deviceId:  " + result.deviceId);
});
1
2
3
4
5
6
7
8
9
10

save9+

save(deviceId: string): Promise<SaveSuccessResponse>

保存分布式数据对象。使用Promise方式作为异步回调。

对象数据保存成功后,当应用存在时不会释放对象数据,当应用退出后,重新进入应用时,恢复保存在设备上的数据。

有以下几种情况时,保存的数据将会被释放:

  • 存储时间超过24小时。
  • 应用卸载。
  • 成功恢复数据之后。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
deviceId string 保存数据的设备号,当deviceId默认为"local",标识需要保存对象的设备。

返回值:

类型 说明
Promise<SaveSuccessResponse> Promise对象。返回SaveSuccessResponse,包含sessionId、version、deviceId等信息。

示例:

import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
g_object.setSessionId("123456");
g_object.save("local").then((result) => {
    console.log("save callback");
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
}, () => {
    console.error("save failed");
});
1
2
3
4
5
6
7
8
9
10
11

revokeSave9+

revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void

撤回保存的分布式数据对象。使用callback方式作为异步方法。

如果对象保存在本地设备,那么将删除所有受信任设备上所保存的数据。 如果对象保存在其他设备,那么将删除本地设备上的数据。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

参数:

参数名 类型 必填 说明
callback AsyncCallback<RevokeSaveSuccessResponse> 回调函数。返回RevokeSaveSuccessResponse,包含sessionId。

示例:

import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
g_object.setSessionId("123456");
g_object.revokeSave((result, data) => {
  console.log("revokeSave callback");
});
1
2
3
4
5
6

revokeSave9+

revokeSave(): Promise<RevokeSaveSuccessResponse>

撤回保存的分布式数据对象。使用Promise方式作为异步方法。

如果对象保存在本地设备,那么将删除所有受信任设备上所保存的数据。 如果对象保存在其他设备,那么将删除本地设备上的数据。

系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject。

返回值:

类型 说明
Promise<RevokeSaveSuccessResponse> Promise对象。返回RevokeSaveSuccessResponse,包含sessionId。

示例:

import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
g_object.setSessionId("123456");
g_object.revokeSave().then((result) => {
    console.log("revokeSave callback");
    console.log("sessionId" + result.sessionId);
}, () => {
    console.error("revokeSave failed");
});
1
2
3
4
5
6
7
8
9