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

  • 2022-08-09
  • 浏览 (1137)

@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&lt;string&gt;) => 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&lt;SaveSuccessResponse&gt;): void

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

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

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

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

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

参数：

参数名 类型 必填 说明
deviceId string 是 保存数据的deviceId，当deviceId为”local”，代表存储在本地设备。
callback AsyncCallback&lt;SaveSuccessResponse&gt; 是 回调函数。返回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&lt;SaveSuccessResponse&gt;

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

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

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

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

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

参数：

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

返回值：

类型 说明
Promise&lt;SaveSuccessResponse&gt; 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&lt;RevokeSaveSuccessResponse&gt;): void

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

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

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

参数：

参数名 类型 必填 说明
callback AsyncCallback&lt;RevokeSaveSuccessResponse&gt; 是 回调函数。返回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&lt;RevokeSaveSuccessResponse&gt;

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

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

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

返回值：

类型 说明
Promise&lt;RevokeSaveSuccessResponse&gt; 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&lt;string&gt;) => 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&lt;string&gt;) => 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 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述（仅对系统应用开放）

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

0  赞
  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/d3b1afaa97e14b4eb534af47df5359c9
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录