harmony 鸿蒙@ohos.data.distributedDataObject (分布式数据对象)
@ohos.data.distributedDataObject (分布式数据对象)
本模块提供管理基本数据对象的相关能力,包括创建、查询、删除、修改、订阅等;同时支持相同应用多设备间的分布式数据对象协同能力。
说明:
本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
导入模块
import distributedObject from '@ohos.data.distributedDataObject';
distributedObject.create9+
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("amy", 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("amy", 18, false);
let g_object: distributedObject.DataObject = 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();
SaveSuccessResponse9+
save接口回调信息。
系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
sessionId | string | 是 | 多设备协同的唯一标识。 |
version | number | 是 | 已保存对象的版本。 |
deviceId | string | 是 | 存储数据的设备号,标识需要保存对象的设备。默认为”local”,标识本地设备;可自定义设置其他标识设备的字符串。 |
RevokeSaveSuccessResponse9+
revokeSave接口回调信息。
系统能力: SystemCapability.DistributedDataManager.DataObject.DistributedObject
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
sessionId | string | 是 | 多设备协同的唯一标识。 |
DataObject
表示一个分布式数据对象。在使用以下接口前,需调用create()获取DataObject对象。
setSessionId9+
setSessionId(sessionId: string, callback: AsyncCallback<void>): void
设置同步的sessionId,当可信组网中有多个设备时,多个设备间的对象如果设置为同一个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");
});
setSessionId9+
setSessionId(callback: AsyncCallback<void>): void
退出所有已加入的session。
需要权限: 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.");
});
setSessionId9+
setSessionId(sessionId?: string): Promise<void>
设置同步的sessionId,当可信组网中有多个设备时,多个设备间的对象如果设置为同一个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’)9+
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 (fields != null && fields != undefined) {
for (let index: number = 0; index < fields.length; index++) {
console.info("changed !" + fields[index] + " " + g_object[fields[index]]);
}
}
});
off(‘change’)9+
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 (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’)9+
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’)9+
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");
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等信息。 |
示例:
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);
});
save9+
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);
});
revokeSave9+
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);
});
revokeSave9+
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("amy", 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("amy", 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("amy", 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("amy", 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("amy", 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("amy", 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");
你可能感兴趣的鸿蒙文章
harmony 鸿蒙BundleStatusCallback
harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)
harmony 鸿蒙@ohos.distributedBundle (分布式包管理)
harmony 鸿蒙@ohos.bundle (Bundle模块)
harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦