README_zh.md
1# 分布式对象用户手册
2
3分布式数据对象管理框架是一款面向对象的内存数据管理框架，向应用开发者提供内存对象的创建、查询、删除、修改、订阅等基本数据对象的管理能力，同时具备分布式能力，满足超级终端场景下，相同应用多设备间的数据对象协同需求。
4
5## 基本概念
6
7分布式数据对象提供JS接口，让开发者能以使用本地对象的方式使用分布式对象。
8
9## 约束与限制
10
11• 不同设备间只有相同bundleName的应用才能直接同步
12
13• 不建议创建过多分布式对象，每个分布式对象将占用100-150KB内存
14
15• 每个对象大小不超过500KB
16
17• 支持JS接口间的互通，与其他语言不互通。
18
19| 类型名称 | 类型描述 |
20| ----------- | ----------------------------------------- |
21| number | 数字 |
22| string | 字符串 |
23| boolean | 布尔 |
24
25## 开发指导
26
27### 接口说明
28
29#### 引用分布式对象头文件
30
31```
32import distributedObject from '@ohos.data.distributedDataObject'
33```
34
35#### 接口
36
37| 接口名称 | 描述 |
38| ------------------------------------------------------------ | ------------------------------------------------------------ |
39| function createDistributedObject(source: object): DistributedObject; | 创建分布式对象<br>source中指定分布式对象中的属性<br>返回值是创建出的分布式对象，接口见DistrubutedObject |
40| function genSessionId(): string; | 随机创建sessionId<br>返回值是随机创建的sessionId |
41
42#### DistrubutedObject
43
44| 接口名称 | 描述 |
45| ------------------------------------------------------------ | ------------------------------------------------------------ |
46| setSessionId(sessionId?: string): boolean; | 设置同步的sessionId,可信组网中有多个设备时，多个设备间的对象如果设置为同一个sessionId,就能自动同步<br>sessionId是指定的sessionId,如果要退出分布式组网，设置为“”或不设置均可<br>返回值是操作结果，true标识设置session成功 |
47| on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void; | 监听对象的变更<br>type固定为'change'<br>callback是变更时触发的回调，回调参数sessionId标识变更对象的sessionId,fields标识对象变更的属性名 |
48| off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> } | 删除对象的变更监听<br>type固定为'change'<br>callback为可选参数，不设置表示删除该对象所有变更监听 |
49
50## • 开发步骤
51
52 #### 1.引入接口
53```
54import distributedObject from '@ohos.data.distributedDataObject'
55
56```
57
58 #### 2.创建对象
59```c
60// 创建对象，对象包含三个属性，name,age和isVis
61var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
62```
63 #### 3.加入同步组网
64
65发起方
66
67```
68g_object.setSessionId(distributedObject.genSessionId());
69
70//将生成的g_object.__sessionId通过Intent传到对端设备
71```
72
73被拉起方
74
75```
76//获取Intent中的sessionId
77g_object.setSessionId(sessionId);
78```
79
80
81
82 #### 4.监听对象变更
83
84```c
85changeCallback : function (sessionId, changeData) {
86 console.info("change" + sessionId + " " + this.response);
87
88 if (changeData != null && changeData != undefined) {
89 changeData.forEach(element => {
90 console.info("changed !" + element + " " + g_object[element]);
91 });
92 }
93}
94g_object.on("change", this.changeCallback);
95```
96#### 4.修改对象属性
97
98```c
99g_object.name = "jack";
100g_object.age = 19;
101g_object.isVis = false; // 对端设备收到change回调，fields为name,age和isVis
102```
103#### 5.访问对象
104```c
105console.info("name " + g_object["name"]); //访问到的是组网内最新数据
106```
107#### 6.退出同步组网
108
109```c
110g_object.setSessionId("");
111```
112
113