Skip to content

D
Docs

OpenHarmony / Docs
接近 2 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs
未验证 提交 3087a5d5 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!8781 【轻量级 PR】：update zh-cn/application-dev/database/database-distributedobject-guidelines.md. 

Merge pull request !8781 from 葛亚芳/N/A
上级 30a56021 452894e7
隐藏空白更改
内联 并排
Showing with 99 addition and 87 deletion
zh-cn/application-dev/database/database-distributedobject-guidelines.md
浏览文件 @ 3087a5d5
......@@ -2,22 +2,23 @@
## 场景介绍
分布式数据对象通过屏蔽设备间复杂的数据交互处理，提供了与本地变量类似的极简操作，当设备1的应用A的分布式数据对象增、删、改数据后，设备2的应用A也可以获取到对应的数据变化，同时还能监听数据变更以及对端数据对象的上下线。分布式数据对象支持的数据类型包括数字型、字符型、布尔型等基本类型，同时也支持数组、基本类型嵌套等复杂类型。
分布式数据对象为开发者在分布式应用场景下提供简单易用的功能接口，可实现多设备间同应用的数据协同，同时设备间还可以监听对象的状态和数据变更。
比如，当设备1上应用A的分布式数据对象增、删、改数据后，设备2上应用A也可以获取到对应的数据变化，同时还能监听数据变更以及对端数据对象的上下线。
## 接口说明
具体分布式数据对象相关功能接口请见[分布式数据对象](../reference/apis/js-apis-data-distributedobject.md)。
分布式数据对象相关功能接口请见[分布式数据对象](../reference/apis/js-apis-data-distributedobject.md)。
### 创建数据对象实例
创建一个分布式数据对象实例，用户可以通过source指定分布式对象中的属性。
创建一个分布式数据对象实例，开发者可以通过source指定分布式对象中的属性。
**表1** 分布式数据对象实例创建接口
| 包名 | 接口名 | 描述 |
| 包名 | 接口名 | 描述 |
| -------- | -------- | -------- |
| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | 创建一个分布式数据对象实例，用于数据操作 <br>-&nbsp;source：设置distributedObject的属性。<br>-&nbsp;DistributedObject：返回值是创建好的分布式对象。|
| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | 创建一个分布式数据对象实例，用于数据操作。 <br>-&nbsp;source：设置distributedObject的属性。<br>-&nbsp;DistributedObject：返回值是创建好的分布式对象。 |
### 创建分布式数据对象sessionId
......@@ -35,16 +36,17 @@
**表3** 分布式数据对象sessionId设置接口
| 类名 | 接口名 | 描述 |
| -------- | -------- | -------- |
| DistributedDataObject | setSessionId(sessionId?: string): boolean | 为分布式数据对象设置sessionId <br>&nbsp;sessionId：分布式对象在可信组网中的标识ID。如果要退出分布式组网，设置为""或不设置均可。|
| DistributedDataObject | setSessionId(sessionId?: string): boolean | 为分布式数据对象设置sessionId。<br>&nbsp;sessionId：分布式对象在可信组网中的标识ID。如果要退出分布式组网，设置为""或不设置均可。 |
### 订阅数据变更
订阅数据变更需要指定Callback作为回调方法，订阅的数据对象发生数据变更后，Callback被回调。
**表4** 分布式数据对象数据变更订阅接口
| 类名 | 接口名 | 描述 |
| 类名 | 接口名 | 描述 |
| -------- | -------- | -------- |
| DistributedDataObject| on(type: 'change', callback: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void | 订阅数据变更。 |
| 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 | 注销订阅。需要删除的变更回调，若不设置则删除该对象所有的变更回调。 |
### 订阅数据对象上下线
......@@ -73,8 +75,6 @@
| 类名 | 接口名 | 描述 |
| -------- | -------- | -------- |
| DistributedDataObject | save(deviceId: string): Promise&lt;SaveSuccessResponse&gt; | 保存数据对象。 |
| DistributedDataObject| save(deviceId: string, callback: AsyncCallback&lt;SaveSuccessResponse&gt;): void | 保存数据对象。 |
| DistributedDataObject | revokeSave(callback: AsyncCallback&lt;RevokeSaveSuccessResponse&gt;): void | 撤回已保存的数据对象。 |
| DistributedDataObject| revokeSave(): Promise&lt;RevokeSaveSuccessResponse&gt; | 撤回已保存的数据对象。 |
## 开发步骤
......@@ -82,11 +82,15 @@
以一次分布式数据对象同步为例，说明开发步骤。
1. 准备工作，导入@ohos.data.distributedDataObject模块到开发环境。
```js
import distributedObject from '@ohos.data.distributedDataObject';
```
2. 请求权限。需要在`config.json`里面进行配置请求权限，示例代码如下：
```
```
2. 请求权限。
需要在`config.json`文件里进行配置请求权限（FA模型），示例代码如下：
```json
{
"module": {
"reqPermissions": [
......@@ -96,8 +100,11 @@
]
}
}
```
这个权限还需要在应用首次启动的时候弹窗获取用户授权，可以通过如下代码实现：
```
Stage模型下的权限请求请参见[权限声明-Stage模型](../security/accesstoken-guidelines.md#stage模型)。
这个权限还需要在应用首次启动的时候弹窗获取用户授权，可以通过如下代码实现：
```js
import featureAbility from '@ohos.ability.featureAbility';
......@@ -110,34 +117,50 @@
})
console.info('end grantPermission');
}
grantPermission();
```
3. 获取分布式数据对象实例。
以下为创建分布式数据对象的代码示例：
```js
var local_object = distributedObject.createDistributedObject({name:undefined, age:undefined, isVis:true,
parent:undefined, list:undefined});
var local_object = distributedObject.createDistributedObject({
name: undefined,
age: undefined,
isVis: true,
parent: undefined,
list: undefined
});
var sessionId = distributedObject.genSessionId();
```
4. 加入同步组网。同步组网中的数据对象分为发起方和被拉起方。
以下为加入同步组网的代码示例:
```js
//发起方
var local_object = distributedObject.createDistributedObject({name:"jack", age:18, isVis:true,
parent:{mother:"jack mom",father:"jack Dad"},list:[{mother:"jack mom"}, {father:"jack Dad"}]});
// 发起方
var local_object = distributedObject.createDistributedObject({
name: "jack",
age: 18,
isVis: true,
parent: { mother: "jack mom", father: "jack Dad" },
list: [{ mother: "jack mom" }, { father: "jack Dad" }]
});
local_object.setSessionId(sessionId);
//被拉起方
var remote_object = distributedObject.createDistributedObject({name:undefined, age:undefined, isVis:true,
parent:undefined, list:undefined});
// 被拉起方
var remote_object = distributedObject.createDistributedObject({
name: undefined,
age: undefined,
isVis: true,
parent: undefined,
list: undefined
});
// 收到status上线后remote_object同步数据，即name变成jack,age是18
remote_object.setSessionId(sessionId);
//收到status上线后remote_object同步数据，即name变成jack,age是18
```
5. 监听对象数据变更。可监听对端数据的变更，以callback作为变更回调实例。
......@@ -146,56 +169,61 @@
```js
function changeCallback(sessionId, changeData) {
console.info("change" + sessionId);
console.info("change" + sessionId);
if (changeData != null && changeData != undefined) {
changeData.forEach(element => {
console.info("changed !" + element + " " + local_object[element]);
});
}
}
// 发起方要在changeCallback里刷新界面，则需要将正确的this绑定给changeCallback
local_object.on("change", this.changeCallback.bind(this));
if (changeData != null && changeData != undefined) {
changeData.forEach(element => {
console.info("changed !" + element + " " + local_object[element]);
});
}
}
// 发起方要在changeCallback里刷新界面，则需要将正确的this绑定给changeCallback
local_object.on("change", this.changeCallback.bind(this));
```
6. 修改对象属性，对象属性支持基本类型（数字类型、布尔类型、字符串类型）以及复杂类型（数组、基本类型嵌套等）。
以下为修改分布式数据对象属性的代码示例：
```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"}];
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", father: "dad" };
// 不支持的修改方式
local_object.parent.mother = "mom";
```
7. 访问对象。可以通过直接获取的方式访问到分布式数据对象的属性，且该数据为组网内的最新数据。
以下为访问对象的代码示例：
```js
console.info("name " + local_object["name"]);
```
8. 删除监听数据变更。可以指定删除监听的数据变更回调；也可以不指定，这将会删除该分布式数据对象的所有数据变更回调。
以下为取消监听数据变更的代码示例：
```js
//删除变更回调changeCallback
// 删除变更回调changeCallback
local_object.off("change", changeCallback);
//删除所有的变更回调
// 删除所有的变更回调
local_object.off("change");
```
9. 监听分布式对象的上下线。可以监听对端分布式数据对象的上下线。
以下为访问对象的代码示例：
```js
function statusCallback(sessionId, networkId, status) {
this.response += "status changed " + sessionId + " " + status + " " + networkId;
......@@ -206,57 +234,41 @@
10. 保存和撤回已保存的数据对象。
1.callback方式
```js
// 保存数据对象
local_object.save("local", (result, data)=>{
console.log("save callback");
console.info("save sessionId " + data.sessionId);
console.info("save version " + data.version);
console.info("save deviceId " + data.deviceId);
});
// 撤回保存的数据对象
local_object.revokeSave((result, data) =>{
console.log("revokeSave callback");
console.info("revokeSave sessionId " + data.sessionId);
});
```
2.Promise方式
```js
// 保存数据对象
g_object.save("local").then((result)=>{
console.info("save sessionId " + result.sessionId);
console.info("save version " + result.version);
console.info("save deviceId " + result.deviceId);
}, (result)=>{
console.info("save local failed.");
});
// 撤回保存的数据对象
g_object.revokeSave().then((result)=>{
console.info("revokeSave success.");
}, (result)=>{
console.info("revokeSave failed.");
});
```
```js
// 保存数据对象
g_object.save("local").then((result) => {
console.info("save sessionId " + result.sessionId);
console.info("save version " + result.version);
console.info("save deviceId " + result.deviceId);
}, (result) => {
console.info("save local failed.");
});
// 撤回保存的数据对象
g_object.revokeSave().then((result) => {
console.info("revokeSave success.");
}, (result) => {
console.info("revokeSave failed.");
});
```
11. 删除监听分布式对象的上下线。可以指定删除监听的上下线回调；也可以不指定，这将会删除该分布式数据对象的所有上下线回调。
以下为取消监听数据变更的代码示例：
```js
//删除上下线回调statusCallback
```js
// 删除上下线回调statusCallback
local_object.off("status", this.statusCallback);
//删除所有的上下线回调
// 删除所有的上下线回调
local_object.off("status");
```
```
12. 退出同步组网。分布式对象退出组网后，本地的数据变更对端不会同步。
以下为退出同步组网的代码示例：
```js
local_object.setSessionId("");
```
以下为退出同步组网的代码示例：
```js
local_object.setSessionId("");
```
## 相关实例
针对分布式数据对象，有以下相关实例可供参考：
- [`DistributedNote`：分布式备忘录（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedNote)
- [`DistributedObjectDms`：分布式跑马灯（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedObjectDms)
- [`DistributedObjectDms`：分布式跑马灯（eTS）（API9）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/data/DistributedObjectDms)
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或