add distributedobject docs

Signed-off-by: Nli_juntao <lijuntao9@huawei.com>

zh-cn/application-dev/database/Readme-CN.md

@@ -9,3 +9,6 @@
 - 轻量级数据存储
   - [轻量级数据存储概述](database-preference-overview.md)
   - [轻量级数据存储开发指导](database-preference-guidelines.md)
+- 分布式数据对象
+  - [分布式数据对象概述](database-distributedobject-overview.md)
+  - [分布式数据对象开发指导](database-distributedobject-guidelines.md)

zh-cn/application-dev/database/database-distributedobject-guidelines.md

+# 分布式数据对象开发指导
+
+## 场景介绍
+
+分布式数据对象通过屏蔽设备间复杂的数据交互处理，提供了与本地变量类似的极简操作，当设备1的应用A的分布式数据对象增、删、改数据后，设备2的应用A也可以获取到对应的数据变化，同时还能监听数据变更以及对端数据对象的上下线。分布式数据对象支持的数据类型包括数字型、字符型、布尔型等基本类型，同时也支持数组、基本类型嵌套等复杂类型。
+
+
+## 接口说明
+
+### 创建数据对象实例
+
+创建一个分布式数据对象实例，用户可以通过source指定分布式对象中的属性。
+
+
+**表1** 分布式数据对象实例创建接口
+| 包名 | 接口名 | 描述 | 
+| -------- | -------- | -------- |
+| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | 创建一个分布式数据对象实例，用于数据操作 | 
+
+### 创建分布式数据对象sessionId
+
+创建一个随机的sessionId，可将其设置为一个分布式数据对象的sessionId。
+
+**表2** 分布式数据对象sessionId创建接口
+| 包名 | 接口名 | 描述 | 
+| -------- | -------- | -------- |
+| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | 创建一个sessionId，可作为分布式数据对象的sessionId | 
+
+### 设置分布式数据对象sessionId
+
+设置分布式数据对象的sessionId，sessionId是一次（多设备）协同的唯一标识，同步的多个数据对象需要关联同一个sessionId。
+
+**表3** 分布式数据对象sessionId设置接口
+| 包名 | 接口名 | 描述 | 
+| -------- | -------- | -------- |
+| ohos.data.distributedDataObject| setSessionId(sessionId?: string): boolean | 为分布式数据对象设置sessionId | 
+
+### 订阅数据变更
+
+订阅数据变更需要指定Callback作为回调方法，订阅的数据对象发生数据变更后，Callback被回调。
+
+**表4** 分布式数据对象数据变更订阅接口
+| 类名 | 接口名 | 描述 | 
+| -------- | -------- | -------- |
+| DistributedDataObject| on(type: 'change', callback: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void | 订阅数据变更。 | 
+| DistributedDataObject| off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void | 注销订阅。 |
+
+### 订阅数据对象上下线
+
+订阅数据对象上下线需要指定Callback作为回调方法，订阅的数据对象上线/下线后，对端的数据对象会收到Callback回调。
+
+**表5** 分布式数据对象数据上下线订阅接口
+| 类名 | 接口名 | 描述 | 
+| -------- | -------- | -------- |
+| DistributedDataObject| on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' \\| 'offline' }>): void | 订阅数据对象上下线。 | 
+| DistributedDataObject| off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' \\| 'offline' }>): void | 注销订阅。 |
+
+
+
+## 开发步骤
+
+以一次分布式数据对象同步为例，说明开发步骤。
+
+1. 准备工作，导入@ohos.data.distributedDataObject模块到开发环境。
+   ```js
+   import distributedObject from '@ohos.data.distributedDataObject'
+   ```
+
+2. 获取分布式数据对象实例。
+
+   以下为创建分布式数据对象的代码示例：
+   ```js
+   var local_object = distributedObject.createDistributedObject({{name:undefined, age:undefined, isVis:true, 
+                  parent:undefined, list:undefined}});
+   ```
+
+
+3. 加入同步组网。同步组网中的数据对象分为发起方和被拉起方。
+   
+   以下为加入同步组网的代码示例:
+
+   发起方：
+   ```js
+   local_object.setSessionId(distributedObject.genSessionId());
+   //将生成的local_object.__sessionId通过Intent传到对端设备
+   ```
+   被拉起方：
+   ```js
+   //获取Intent中的sessionId
+   remote_object.setSessionId(sessionId);
+   ```
+
+4. 监听对象数据变更。可支持监听本地数据或对端数据的变更，以  callback作为变更回调实例。
+
+   以下为监听对象数据变更的代码示例。
+   
+   ```js
+   changeCallback : function (sessionId, changeData) {
+        console.info("change" + sessionId);
+
+        if (changeData != null && changeData != undefined) {
+            changeData.forEach(element => {
+                console.info("changed !" + element + " " + local_object[element]);
+        });
+        }
+    } 
+    local_object.on("change", this.changeCallback);
+   ```
+    
+
+5. 修改对象属性，对象属性支持基本类型（数字类型、布尔类型、字符串类型）以及复杂类型（数组、基本类型嵌套等）。
+   
+   以下为修改分布式数据对象属性的代码示例：
+   ```js
+   local_object.name = "jack";
+   local_object.age = 19;
+   local_object.isVis = false;
+   local_object.parent = {mother:"jack mom",father:"jack Dad"};
+   local_object.list = [{mother:"jack mom"}, {father:"jack Dad"}];
+   ```
+
+   > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
+   > 针对复杂类型的数据修改，目前支持对根属性的修改，暂不支持对下级属性的修改。示例如下：
+   ```js
+   //支持的修改方式
+   local_object.parent = {mother:"mom", father:"dad"};
+   //不支持的修改方式
+   local_object.parent.mother = "mom";
+   ```
+
+6. 访问对象。可以通过直接获取的方式访问到分布式数据对象的属性，且该数据为组网内的最新数据。
+   
+   以下为访问对象的代码示例：
+   ```js
+   console.info("name " + local_object["name"]); 
+   ```
+7. 删除监听数据变更。可以指定删除监听的数据变更回调；也可以不指定，这将会删除该分布式数据对象的所有数据变更回调。
+
+   以下为取消监听数据变更的代码示例：
+   ```js
+   //删除变更回调changeCallback
+   local_object.off("change", changeCallback);
+   //删除所有的变更回调
+   local_object.off("change"); 
+   ```
+8. 监听分布式对象的上下线。可以监听对端分布式数据对象的上下线。
+   以下为访问对象的代码示例：
+   ```js
+    statusCallback : function (sessionId, networkid, status) {
+      this.response += "status changed " + sessionId + " " + status + " " + networkId;
+    }
+
+    local_object.on("status", this.changeCallback);
+   ```
+9. 删除监听分布式对象的上下线。可以指定删除监听的上下线回调；也可以不指定，这将会删除该分布式数据对象的所有上下线回调。
+    
+    以下为取消监听数据变更的代码示例：
+   ```js
+   //删除上下线回调changeCallback
+   local_object.off("status", changeCallback);
+   //删除所有的上下线回调
+   local_object.off("status");
+   ```
+10. 退出同步组网。分布式对象退出组网后，本地的数据变更对端不会同步。
+  
+  以下为退出同步组网的代码示例：
+   ```js
+   local_object.setSessionId("");
+   ```
+   
+   
+
+
+

zh-cn/application-dev/database/database-distributedobject-overview.md

+# 分布式数据对象概述
+
+分布式数据对象管理框架是一款面向对象的内存数据管理框架，向应用开发者提供内存对象的创建、查询、删除、修改、订阅等基本数据对象的管理能力，同时具备分布式能力，满足超级终端场景下，相同应用多设备间的数据对象协同需求。
+
+
+## 基本概念
+
+- **分布式内存数据库**
+  
+  分布式内存数据库将数据缓存在内存中，以便应用获得更快的数据存取速度，不会将数据进行持久化，若数据库关闭，则数据不会保留。
+
+
+- **分布式数据对象**
+
+  分布式数据对象是一个JS对象型的封装，每一个分布式数据对象实例会创建一个内存数据库，每个应用程序创建的内存数据库相互隔离，对分布式数据对象的“读取”或“赋值”会自动映射到对应数据库的put/get操作。
+
+  分布式数据对象的生命周期包括3个状态：**未初始化**、**本地数据对象**和**分布式数据对象**。
+
+  - **未初始化**：未实例化，或已被销毁。
+  - **本地数据对象**：已创建对应的分布式内存数据库，但是还无法进行数据同步。
+  - **分布式数据对象**：已创建对应的分布式内存数据库，且设备在线（设备数=2），可以跨设备同步数据，若设备掉线，分布式数据对象退化为本地数据对象。
+
+
+## 运作机制
+
+分布式数据对象生长在分布式内存数据库之上，在分布式内存数据库上进行了JS对象型的封装，能像操作本地变量一样操作分布式数据对象，数据的跨设备同步由系统自动完成。
+
+**图1** 分布式数据对象运行机制
+
+![how-distributedobject-works](figures/how-distributedobject-works.PNG)
+
+
+
+
+## 约束与限制
+
+- 不同设备间只有相同bundleName的应用才能直接同步。
+
+- 不建议创建过多分布式对象，每个分布式对象将占用100-150KB内存。
+
+- 每个对象大小不超过500KB。
+
+- 如对复杂类型的数据进行修改，仅支持修改根属性，暂不支持下级属性修改。
+  
+- 支持JS接口间的互通，与其他语言不互通。
+

zh-cn/application-dev/reference/apis/js-apis-data-distributedobject.md

+# 分布式对象
+
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
+> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+
+
+## 导入模块
+
+```js
+import distributedObject from '@ohos.data.distributedDataObject'
+```
+
+
+## 权限
+
+无
+
+
+## distributedDataObject.createDistributedObject
+
+createDistributedObject(source: object): DistributedObject
+
+
+创建一个分布式对象distributedObject，用户可以通过source指定分布式对象中的属性，属性支持基本类型以及复杂类型，返回值是创建好的分布式对象。
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | object | source | 是 | 设置distributedObject的属性。 |
+  
+
+- 示例：
+  ```js
+  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"}});
+  ```
+
+
+## distributedObject.genSessionId()
+
+genSessionId(): string
+
+随机创建一个sessionId，返回值是随机创建的sessionId。
+
+
+- 返回值：
+  | 类型 | 说明 |
+  | -------- | -------- |
+  | string | 随机创建的sessionId。 |
+
+- 示例：
+  ```js
+  import distributedObject from '@ohos.data.distributedDataObject'
+  var sessionId = distributedObject.genSessionId();
+  ```
+
+
+## DistributedObject
+
+表示一个分布式对象。
+### setSessionId
+
+setSessionId(sessionId?: string): boolean
+
+设置同步的sessionId,当可信组网中有多个设备时，多个设备间的对象如果设置为同一个sessionId,就能自动同步。sessionId是指定的sessionId,如果要退出分布式组网，设置为""或不设置均可。结果以boolean形式返回，true标识设置sessionId成功
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | sessionId | string | 是 | 分布式对象在可信组网中的标识ID。 |
+  
+
+- 示例：
+  ```js
+  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("");
+  ```
+
+
+### on('change')
+
+on(type: 'change', callback: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void
+
+监听分布式对象的变更，type需固定为'change'，callback是变更时触发的回调，回调参数sessionId标识变更对象的sessionId,fields标识对象变更的属性名
+
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 事件类型，固定为'change'，表示数据变更。 |
+  | callback | Callback<{ sessionId: string, fields: Array&lt;string&gt; }> | 是 | 变更回调对象实例。 |
+
+- 示例：
+  ```js
+  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 : function (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", this.changeCallback);
+  ```
+
+### off('change')
+
+off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void
+
+当不再进行数据变更监听时，使用此接口删除对象的变更监听，type固定为'change'，callback为可选参数，若不设置则表示删除该对象所有的变更监听
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 事件类型，固定为'change'，表示数据变更。 |
+  | callback | Callback<{ sessionId: string, fields: Array&lt;string&gt; }> | 否 | 需要删除的变更回调，若不设置则删除该对象所有的变更回调。 |
+
+
+示例：
+  ```js
+  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 : function (sessionId, changeData) {
+        console.info("change" + sessionId);
+  }
+
+  g_object.on("change", this.changeCallback);
+  //删除变更回调changeCallback
+  g_object.off("change", changeCallback);
+  //删除所有的变更回调
+  g_object.off("change");
+  ```
+
+### on('status')
+
+on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void
+
+监听分布式对象的上下线，type需固定为'status'，callback是分布式对象上下线时触发的回调，回调参数sessionId标识变更对象的sessionId,networkId标识对象设备的networkId，status标识对象为'online'(上线)或'offline'(下线)的状态
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 |
+  | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \\| 'offline' }> | 是 | 监听上下线回调实例。 |
+
+示例：
+  ```js
+  import distributedObject from '@ohos.data.distributedDataObject'
+  var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, 
+                 parent:{mother:"jack mom",father:"jack Dad"}});
+  statusCallback : function (sessionId, networkid, status) {
+      this.response += "status changed " + sessionId + " " + status + " " + networkId;
+  }
+
+  g_object.on("status", this.changeCallback);
+  ```
+
+### off('status')
+
+off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void
+
+
+当不再进行对象上下线监听时，使用此接口删除对象的上下线监听，type固定为'status'，callback为可选参数，若不设置则表示删除该对象所有的上下线监听
+
+
+- 参数：
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 |
+  | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \\| 'offline' }> | 否 | 需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。 |
+
+
+示例：
+  ```js
+  import distributedObject from '@ohos.data.distributedDataObject'
+  statusCallback : function (sessionId, networkId, status) {
+      this.response += "status changed " + sessionId + " " + status + " " + networkId;
+  }
+
+  g_object.on("status", this.changeCallback);
+  //删除上下线回调changeCallback
+  g_object.off("status", changeCallback);
+  //删除所有的上下线回调
+  g_object.off("status");
+  ```