@ohos.data.distributedDataObject (分布式数据对象)

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

说明：

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

导入模块

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

distributedObject.create⁹⁺

create(context: Context, source: object): DataObject

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

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
context	Context	是	应用的上下文。 FA模型的应用Context定义见Context。 Stage模型的应用Context定义见Context。
source	object	是	设置分布式数据对象的属性。

返回值：

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

示例：

FA模型示例：

// 导入模块
import distributedObject from '@ohos.data.distributedDataObject';
import featureAbility from '@ohos.ability.featureAbility';
import { BusinessError } from '@ohos.base';
// 获取context
let context = featureAbility.getContext();
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("jack", 18, false);
let g_object: distributedObject.DataObject = distributedObject.create(context, source);

Stage模型示例：

// 导入模块
import distributedObject from '@ohos.data.distributedDataObject';
import UIAbility from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';

let g_object: distributedObject.DataObject|null = null;
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage) {
        let source: SourceObject = new SourceObject("jack", 18, false);
        g_object = distributedObject.create(this.context, source);
    }
}

distributedObject.genSessionId

genSessionId(): string

随机创建一个sessionId。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

返回值：

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

示例：

import distributedObject from '@ohos.data.distributedDataObject';
let sessionId: string = distributedObject.genSessionId();

SaveSuccessResponse⁹⁺

save接口回调信息。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

名称	类型	必填	说明
sessionId	string	是	多设备协同的唯一标识。
version	number	是	已保存对象的版本。
deviceId	string	是	存储数据的设备号，标识需要保存对象的设备。"local"表示本地设备，否则表示其他设备的设备号。

RevokeSaveSuccessResponse⁹⁺

revokeSave接口回调信息。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

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

DataObject

表示一个分布式数据对象。在使用以下接口前，需调用create()获取DataObject对象。

setSessionId⁹⁺

setSessionId(sessionId: string, callback: AsyncCallback<void>): void

设置sessionId，使用callback方式异步回调。当可信组网中有多个设备时，多个设备间的对象如果设置为同一个sessionId，就能自动同步。

需要权限： ohos.permission.DISTRIBUTED_DATASYNC。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
sessionId	string	是	分布式数据对象在可信组网中的标识ID。设置为""时表示退出分布式组网。
callback	AsyncCallback<void>	是	加入session的异步回调。

错误码：

以下错误码的详细介绍参见分布式数据对象错误码。

错误码ID	错误信息
15400001	Create table failed.

示例：

// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId(), ()=>{
    console.info("join session");
});
// g_object退出分布式组网
g_object.setSessionId("", ()=>{
    console.info("leave all session");
});

setSessionId⁹⁺

setSessionId(callback: AsyncCallback<void>): void

退出所有已加入的session，使用callback方式异步回调。

需要权限： ohos.permission.DISTRIBUTED_DATASYNC。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	退出所有已加入session的异步回调。

错误码：

以下错误码的详细介绍参见分布式数据对象错误码。

错误码ID	错误信息
15400001	Create table failed.

示例：

// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId(), ()=>{
    console.info("join session");
});
// 退出分布式组网
g_object.setSessionId(() => {
    console.info("leave all session.");
});

setSessionId⁹⁺

setSessionId(sessionId?: string): Promise<void>

设置sessionId，使用Promise异步返回。当可信组网中有多个设备时，多个设备间的对象如果设置为同一个sessionId，就能自动同步。

需要权限： ohos.permission.DISTRIBUTED_DATASYNC。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

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

返回值：

类型	说明
Promise<void>	Promise对象。

错误码：

以下错误码的详细介绍参见分布式数据对象错误码。

错误码ID	错误信息
15400001	Create table failed.

示例：

// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId()).then (()=>{
    console.info("join session.");
    }).catch((error: BusinessError)=>{
        console.info("error:" + error.code + error.message);
});
// 退出分布式组网
g_object.setSessionId().then (()=>{
    console.info("leave all session.");
    }).catch((error: BusinessError)=>{
        console.info("error:" + error.code + error.message);
});

on('change')⁹⁺

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

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

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定为'change'，表示数据变更。
callback	Function	是	变更回调对象实例。 sessionId：标识变更对象的sessionId； fields：标识对象变更的属性名。

示例：

g_object.on("change", (sessionId: string, fields: Array<string>) => {
    console.info("change" + sessionId);
    if (g_object != null && fields != null && fields != undefined) {
        for (let index: number = 0; index < fields.length; index++) {
            console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
        }
    }
});

off('change')⁹⁺

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

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

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定为'change'，表示数据变更。
callback	Function	否	需要删除的数据变更回调，若不设置则删除该对象所有的数据变更回调。 sessionId：标识变更对象的sessionId； fields：标识对象变更的属性名。

示例：

// 删除数据变更回调changeCallback
g_object.off("change", (sessionId: string, fields: Array<string>) => {
    console.info("change" + sessionId);
    if (g_object != null && fields != null && fields != undefined) {
        for (let index: number = 0; index < fields.length; index++) {
            console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
        }
    }
});
// 删除所有的数据变更回调
g_object.off("change");

on('status')⁹⁺

on(type: 'status', callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void

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

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定为'status'，表示对象上下线。
callback	Function	是	监听上下线回调实例。 sessionId：标识变更对象的sessionId； networkId：标识对象设备； status：标识对象为'online'(上线)或'offline'(下线)的状态。

示例：

g_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => {
    console.info("status changed " + sessionId + " " + status + " " + networkId);
});

off('status')⁹⁺

off(type: 'status', callback?:(sessionId: string, networkId: string, status: 'online' | 'offline') => void): void

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

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定为'status'，表示对象上下线。
callback	Function	否	需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。 sessionId：标识变更对象的sessionId； networkId：标识变更对象； status：标识对象为'online'(上线)或'offline'(下线)的状态。

示例：

// 删除上下线回调changeCallback
g_object.off("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => {
    console.info("status changed " + sessionId + " " + status + " " + networkId);
});
// 删除所有的上下线回调
g_object.off("status");

save⁹⁺

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等信息。

示例：

g_object.setSessionId("123456");
g_object.save("local", (err: BusinessError, result:distributedObject.SaveSuccessResponse) => {
    if (err) {
        console.info("save failed, error code = " + err.code);
        console.info("save failed, error message: " + err.message);
        return;
    }
    console.info("save callback");
    console.info("save sessionId: " + result.sessionId);
    console.info("save version: " + result.version);
    console.info("save deviceId:  " + result.deviceId);
});

save⁹⁺

save(deviceId: string): Promise<SaveSuccessResponse>

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

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

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

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

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

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

返回值：

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

示例：

g_object.setSessionId("123456");
g_object.save("local").then((result: distributedObject.SaveSuccessResponse) => {
    console.info("save callback");
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
}).catch((err: BusinessError) => {
    console.info("save failed, error code = " + err.code);
    console.info("save failed, error message: " + err.message);
});

revokeSave⁹⁺

revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void

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

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

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

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

示例：

g_object.setSessionId("123456");
// 持久化数据
g_object.save("local", (err: BusinessError, result: distributedObject.SaveSuccessResponse) => {
    if (err) {
        console.info("save failed, error code = " + err.code);
        console.info("save failed, error message: " + err.message);
        return;
    }
    console.info("save callback");
    console.info("save sessionId: " + result.sessionId);
    console.info("save version: " + result.version);
    console.info("save deviceId:  " + result.deviceId);
});
// 删除持久化保存的数据
g_object.revokeSave((err: BusinessError, result: distributedObject.RevokeSaveSuccessResponse) => {
    if (err) {
      console.info("revokeSave failed, error code = " + err.code);
      console.info("revokeSave failed, error message: " + err.message);
      return;
    }
    console.info("revokeSave callback");
    console.info("revokeSave sessionId " + result.sessionId);
});

revokeSave⁹⁺

revokeSave(): Promise<RevokeSaveSuccessResponse>

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

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

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

返回值：

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

示例：

g_object.setSessionId("123456");
// 持久化数据
g_object.save("local").then((result: distributedObject.SaveSuccessResponse) => {
    console.info("save callback");
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
}).catch((err: BusinessError) => {
    console.info("save failed, error code = " + err.code);
    console.info("save failed, error message: " + err.message);
});
// 删除持久化保存的数据
g_object.revokeSave().then((result: distributedObject.RevokeSaveSuccessResponse) => {
    console.info("revokeSave callback");
    console.info("sessionId" + result.sessionId);
}).catch((err: BusinessError)=> {
    console.info("revokeSave failed, error code = " + err.code);
    console.info("revokeSave failed, error message = " + err.message);
});

distributedObject.createDistributedObject^(deprecated)

createDistributedObject(source: object): DistributedObject

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

说明：

从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用distributedObject.create替代。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

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

返回值：

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

示例：

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("jack", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);

DistributedObject^(deprecated)

表示一个分布式数据对象。在使用以下接口前，需调用createDistributedObject()获取DistributedObject对象。

setSessionId^(deprecated)

setSessionId(sessionId?: string): boolean

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

说明：

从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用setSessionId替代。

需要权限： ohos.permission.DISTRIBUTED_DATASYNC。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

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

返回值：

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

示例：

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("jack", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);
// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId());
// 设置为""退出分布式组网
g_object.setSessionId("");

on('change')^(deprecated)

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

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

说明：

从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用on('change')替代。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定为'change'，表示数据变更。
callback	Function	是	变更回调对象实例。 sessionId：标识变更对象的sessionId； fields：标识对象变更的属性名。

示例：

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("jack", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);
g_object.on("change", (sessionId: string, fields: Array<string>) => {
    console.info("change" + sessionId);
    if (fields != null && fields != undefined) {
        for (let index: number = 0; index < fields.length; index++) {
            console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
        }
    }
});

off('change')^(deprecated)

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

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

说明：

从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用off('change')替代。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定为'change'，表示数据变更。
callback	Function	否	需要删除的数据变更回调，若不设置则删除该对象所有的数据变更回调。 sessionId：标识变更对象的sessionId； fields：标识对象变更的属性名。

示例：

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("jack", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);
// 删除数据变更回调changeCallback
g_object.off("change", (sessionId: string, fields: Array<string>) => {
    console.info("change" + sessionId);
    if (fields != null && fields != undefined) {
        for (let index: number = 0; index < fields.length; index++) {
            console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
        }
    }
});
// 删除所有的数据变更回调
g_object.off("change");

on('status')^(deprecated)

on(type: 'status', callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void

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

说明：

从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用on('status')替代。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定为'status'，表示对象上下线。
callback	Function	是	监听上下线回调实例。 sessionId：标识变更对象的sessionId； networkId：标识对象设备； status：标识对象为'online'(上线)或'offline'(下线)的状态。

示例：

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("jack", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);

g_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => {
    console.info("status changed " + sessionId + " " + status + " " + networkId);
});

off('status')^(deprecated)

off(type: 'status', callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void

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

说明：

从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用off('status')替代。

系统能力： SystemCapability.DistributedDataManager.DataObject.DistributedObject

参数：

参数名	类型	必填	说明
type	string	是	事件类型，固定为'status'，表示对象上下线。
callback	Function	否	需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。 sessionId：标识变更对象的sessionId； networkId：标识变更对象； status：标识对象为'online'(上线)或'offline'(下线)的状态。

示例：

import distributedObject from '@ohos.data.distributedDataObject';
class SourceObject {
    name: string
    age: number
    isVis: boolean

    constructor(name: string, age: number, isVis: boolean) {
        this.name = name
        this.age = age
        this.isVis = isVis
    }
}

let source: SourceObject = new SourceObject("jack", 18, false);
let g_object: distributedObject.DistributedObject = distributedObject.createDistributedObject(source);
// 删除上下线回调changeCallback
g_object.off("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => {
    console.info("status changed " + sessionId + " " + status + " " + networkId);
});
// 删除所有的上下线回调
g_object.off("status");

@ohos.data.distributedDataObject (分布式数据对象)

导入模块

distributedObject.create9+

distributedObject.genSessionId

SaveSuccessResponse9+

RevokeSaveSuccessResponse9+

DataObject

setSessionId9+

setSessionId9+

setSessionId9+

on('change')9+

off('change')9+

on('status')9+

off('status')9+

save9+

save9+

revokeSave9+

revokeSave9+

distributedObject.createDistributedObject(deprecated)

DistributedObject(deprecated)

setSessionId(deprecated)

on('change')(deprecated)

off('change')(deprecated)

on('status')(deprecated)

off('status')(deprecated)

distributedObject.create⁹⁺

SaveSuccessResponse⁹⁺

RevokeSaveSuccessResponse⁹⁺

setSessionId⁹⁺

setSessionId⁹⁺

setSessionId⁹⁺

on('change')⁹⁺

off('change')⁹⁺

on('status')⁹⁺

off('status')⁹⁺

save⁹⁺

save⁹⁺

revokeSave⁹⁺

revokeSave⁹⁺

distributedObject.createDistributedObject^(deprecated)

DistributedObject^(deprecated)

setSessionId^(deprecated)

on('change')^(deprecated)

off('change')^(deprecated)

on('status')^(deprecated)

off('status')^(deprecated)