js-apis-data-distributedobject.md 14.7 KB
Newer Older
A
Annie_wang 已提交
1
# @ohos.data.distributedDataObject (Distributed Data Object)
A
annie_wangli 已提交
2

A
Annie_wang 已提交
3
The **distributedDataObject** module provides basic data object management, including creating, querying, deleting, modifying, and subscribing to data objects, and distributed data object collaboration for the same application among multiple devices.
A
Annie_wang 已提交
4

A
Annie_wang 已提交
5
> **NOTE**<br/>
A
Annie_wang 已提交
6
>
A
annie_wangli 已提交
7 8 9 10 11 12
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.


## Modules to Import

```js
A
Annie_wang 已提交
13
import distributedObject from '@ohos.data.distributedDataObject';
A
annie_wangli 已提交
14 15 16 17 18 19 20
```

## distributedDataObject.createDistributedObject

createDistributedObject(source: object): DistributedObject


A
annie_wangli 已提交
21
Creates a distributed data object.
A
annie_wangli 已提交
22

A
annie_wangli 已提交
23
**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
A
annie_wangli 已提交
24

A
annie_wangli 已提交
25
**Parameters**
A
Annie_wang 已提交
26 27 28
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| source | object | Yes| Attribute of the distributed data object to create.|
A
Annie_wang 已提交
29

A
Annie_wang 已提交
30
**Return value**
A
Annie_wang 已提交
31 32 33
| Type| Description|
| -------- | -------- |
| [DistributedObject](#distributedobject) | Distributed data object created.|
A
annie_wangli 已提交
34 35

**Example**
A
Annie_wang 已提交
36 37 38 39 40
```js
import distributedObject from '@ohos.data.distributedDataObject';
// Create a distributed data object, which contains attributes of four types, namely, string, number, boolean, and object.
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
```
A
annie_wangli 已提交
41 42


A
Annie_wang 已提交
43
## distributedObject.genSessionId
A
annie_wangli 已提交
44 45 46

genSessionId(): string

A
annie_wangli 已提交
47
Creates a random session ID.
A
annie_wangli 已提交
48

A
annie_wangli 已提交
49
**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
A
annie_wangli 已提交
50

A
Annie_wang 已提交
51
**Return value**
A
Annie_wang 已提交
52 53 54
| Type| Description|
| -------- | -------- |
| string | Session ID created.|
A
annie_wangli 已提交
55

A
annie_wangli 已提交
56
**Example**
A
Annie_wang 已提交
57 58 59 60
```js
import distributedObject from '@ohos.data.distributedDataObject';
var sessionId = distributedObject.genSessionId();
```
A
annie_wangli 已提交
61

A
Annie_wang 已提交
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
## SaveSuccessResponse<sup>9+</sup>

Called when the **Save()** API is successfully called.

**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject

| Name| Type| Description|
| -------- | -------- | -------- |
| sessionId | string | Unique ID for multi-device collaboration.|
| version | number |Version of the distributed data object saved.|
| deviceId | string | ID of the device where the distributed data object is stored. The default value is **local**, which identifies a local device. You can set it as required.|

## RevokeSaveSuccessResponse<sup>9+</sup>

Called when the **revokeSave()** API is successfully called.

**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject

| Name| Type| Description|
| -------- | -------- | -------- |
| sessionId | string | Unique ID for multi-device collaboration.|
A
annie_wangli 已提交
83 84 85

## DistributedObject

A
Annie_wang 已提交
86
Represents a distributed data object.
A
annie_wangli 已提交
87

A
annie_wangli 已提交
88 89 90 91
### setSessionId

setSessionId(sessionId?: string): boolean

A
annie_wangli 已提交
92
Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network.
A
annie_wangli 已提交
93

A
Annie_wang 已提交
94 95
**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC

A
annie_wangli 已提交
96 97 98
**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject

**Parameters**
A
annie_wangli 已提交
99

A
Annie_wang 已提交
100 101 102
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| sessionId | string | No| ID of a distributed data object on a trusted network. To remove a distributed data object from the network, set this parameter to "" or leave it empty.|
A
annie_wangli 已提交
103

A
Annie_wang 已提交
104
**Return value**
A
annie_wangli 已提交
105

A
Annie_wang 已提交
106 107 108
| Type| Description|
| -------- | -------- |
| boolean | Returns **true** if the session ID is set successfully;<br>returns **false** otherwise. |
A
Annie_wang 已提交
109

A
annie_wangli 已提交
110 111
**Example**

A
Annie_wang 已提交
112 113 114 115 116 117 118 119
```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"}});;
// Add g_object to the distributed network.
g_object.setSessionId(distributedObject.genSessionId());
// Remove g_object from the distributed network.
g_object.setSessionId("");
```
A
annie_wangli 已提交
120 121 122 123 124 125


### on('change')

on(type: 'change', callback: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void

A
Annie_wang 已提交
126
Subscribes to the changes of this distributed data object.
A
annie_wangli 已提交
127

A
annie_wangli 已提交
128
**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
A
annie_wangli 已提交
129

A
annie_wangli 已提交
130
**Parameters**
A
Annie_wang 已提交
131 132 133 134
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type to subscribe to. The value is **change**, which indicates data changes.|
| callback | Callback<{ sessionId: string, fields: Array&lt;string&gt; }> | Yes| Callback used to return the changes of the distributed data object.<br>**sessionId** indicates the session ID of the distributed data object.<br>**fields** indicates the changed attributes of the distributed data object.|
A
annie_wangli 已提交
135

A
annie_wangli 已提交
136
**Example**
A
Annie_wang 已提交
137 138
```js
import distributedObject from '@ohos.data.distributedDataObject';  
A
Annie_wang 已提交
139
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
A
Annie_wang 已提交
140 141 142 143 144 145 146 147 148 149
globalThis.changeCallback = (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", globalThis.changeCallback);
```
A
annie_wangli 已提交
150 151 152 153 154

### off('change')

off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void

A
Annie_wang 已提交
155
Unsubscribes from the changes of this distributed data object.
A
annie_wangli 已提交
156

A
annie_wangli 已提交
157
**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
A
annie_wangli 已提交
158

A
annie_wangli 已提交
159
**Parameters**
A
Annie_wang 已提交
160 161 162 163
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type to unsubscribe from. The value is **change**, which indicates data changes.|
| callback | Callback<{ sessionId: string, fields: Array&lt;string&gt; }> | No| Callback to be unregistered. If this parameter is not set, all data change callbacks of the object will be unregistered.<br>**sessionId** indicates the session ID of the distributed data object.<br>**fields** indicates the changed attributes of the distributed data object.|
A
annie_wangli 已提交
164 165


A
annie_wangli 已提交
166
**Example**
A
Annie_wang 已提交
167 168
```js
import distributedObject from '@ohos.data.distributedDataObject';  
A
Annie_wang 已提交
169
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
A
Annie_wang 已提交
170 171 172 173 174
// Unregister the specified data change callback.
g_object.off("change", globalThis.changeCallback);
// Unregister all data change callbacks.
g_object.off("change");
```
A
annie_wangli 已提交
175 176 177 178 179

### on('status')

on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void

A
Annie_wang 已提交
180
Subscribes to the status change (online or offline) of this distributed data object.
A
annie_wangli 已提交
181

A
annie_wangli 已提交
182
**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
A
annie_wangli 已提交
183

A
annie_wangli 已提交
184
**Parameters**
A
Annie_wang 已提交
185 186 187 188
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type to subscribe to. The value is **status**, which indicates the status change (online or offline) of the distributed data object.|
| callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | Yes| Callback used to return the status change.<br>**sessionId**: session ID of the distributed data object.<br>**networkId**: object device ID, that is, **deviceId**.<br>**status** indicates the object status, which can be online or offline.|
A
annie_wangli 已提交
189 190

**Example**
A
Annie_wang 已提交
191 192 193 194 195
```js
import distributedObject from '@ohos.data.distributedDataObject';
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
}
A
Annie_wang 已提交
196
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
A
Annie_wang 已提交
197 198
g_object.on("status", globalThis.statusCallback);
```
A
annie_wangli 已提交
199 200 201 202 203 204

### off('status')

off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void


A
Annie_wang 已提交
205
Unsubscribes from the status change (online or offline) of this distributed data object.
A
annie_wangli 已提交
206

A
annie_wangli 已提交
207
**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject
A
annie_wangli 已提交
208

A
annie_wangli 已提交
209
**Parameters**
A
Annie_wang 已提交
210 211 212 213
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type to unsubscribe from. The value is **status**, which indicates the status change (online or offline) of the distributed data object.|
| callback | Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }> | No| Callback used to return the status change. If this parameter is not specified, this API unsubscribes from all callbacks of this distributed data object.<br>**sessionId**: session ID of the distributed data object.<br>**deviceId** indicates the device ID of the distributed data object.<br>**status** indicates the status, which can be online or offline.|
A
annie_wangli 已提交
214 215


A
annie_wangli 已提交
216
**Example**
A
Annie_wang 已提交
217 218
```js
import distributedObject from '@ohos.data.distributedDataObject'; 
A
Annie_wang 已提交
219
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
A
Annie_wang 已提交
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
}
// Unsubscribe from the specified status change callback for the distributed data object.
g_object.off("status",globalThis.statusCallback);
// Unsubscribe from all status change callbacks for the distributed data object.
g_object.off("status");
```

### save<sup>9+</sup>

save(deviceId: string, callback: AsyncCallback&lt;SaveSuccessResponse&gt;): void

Saves a distributed data object. This API uses an asynchronous callback to return the result.

If the application is active, the saved data will not be released. When the application exits and restarts, the data saved on the device will be restored.

The saved data will be released in the following cases:

- The data is stored for more than 24 hours.
- The application has been uninstalled.
- Data is successfully restored.

**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject

**Parameters**
A
Annie_wang 已提交
246 247 248 249
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| deviceId | string | Yes| ID of the device where data is stored. The value **local** indicates the local device.|
| callback | AsyncCallback&lt;[SaveSuccessResponse](#savesuccessresponse9)&gt; | Yes| Callback used to return **SaveSuccessResponse**, which contains information such as session ID, version, and device ID.|
A
Annie_wang 已提交
250 251

**Example**
A
Annie_wang 已提交
252 253 254 255 256 257 258 259 260 261 262 263
```js
import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
g_object.setSessionId("123456");
g_object.save("local", (status, result)=>{
    console.log("save status = " + status);
    console.log("save callback");
    console.info("save sessionId: " + result.sessionId);
    console.info("save version: " + result.version);
    console.info("save deviceId:  " + result.deviceId);
});
```
A
Annie_wang 已提交
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281

### save<sup>9+</sup>

save(deviceId: string): Promise&lt;SaveSuccessResponse&gt;

Saves a distributed data object. This API uses a promise to return the result.

If the application is active, the saved data will not be released. When the application exits and restarts, the data saved on the device will be restored.

The saved data will be released in the following cases:

- The data is stored for more than 24 hours.
- The application has been uninstalled.
- Data is successfully restored.

**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject

**Parameters**
A
Annie_wang 已提交
282 283 284
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| deviceId | string | Yes| ID of the device where the data is saved. The default value is **local**, which indicates the local device. |
A
Annie_wang 已提交
285

A
Annie_wang 已提交
286
**Return value**
A
Annie_wang 已提交
287

A
Annie_wang 已提交
288 289 290
| Type| Description|
| -------- | -------- |
| Promise&lt;[SaveSuccessResponse](#savesuccessresponse9)&gt; | Promise used to return **SaveSuccessResponse**, which contains information such as session ID, version, and device ID.|
A
Annie_wang 已提交
291 292 293

**Example**

A
Annie_wang 已提交
294 295 296 297 298 299 300 301 302 303 304 305 306
```js
import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
g_object.setSessionId("123456");
g_object.save("local").then((result)=>{
    console.log("save callback");
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
}, ()=>{
    console.error("save failed");
});
```
A
Annie_wang 已提交
307 308 309

### revokeSave<sup>9+</sup>

A
Annie_wang 已提交
310
revokeSave(callback: AsyncCallback&lt;RevokeSaveSuccessResponse&gt;): void
A
Annie_wang 已提交
311 312 313 314 315 316 317 318 319

Revokes the saving operation of a distributed data object. This API uses an asynchronous callback to return the result.

If the object is saved on the local device, the data saved on all trusted devices will be deleted.
If the object is stored on another device, the data on the local device will be deleted.

**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject

**Parameters**
A
Annie_wang 已提交
320 321 322
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)&gt; | No| Callback used to return **RevokeSaveSuccessResponse**, which contains the session ID.|
A
Annie_wang 已提交
323 324 325

**Example**

A
Annie_wang 已提交
326 327 328 329 330 331 332 333
```js
import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
g_object.setSessionId("123456");
g_object.revokeSave((result, data) =>{
  console.log("revokeSave callback");
});
```
A
Annie_wang 已提交
334 335 336

### revokeSave<sup>9+</sup>

A
Annie_wang 已提交
337
revokeSave(): Promise&lt;RevokeSaveSuccessResponse&gt;
A
Annie_wang 已提交
338 339 340 341 342 343 344 345

Revokes the saving operation of a distributed data object. This API uses a promise to return the result.

If the object is saved on the local device, the data saved on all trusted devices will be deleted.
If the object is stored on another device, the data on the local device will be deleted.

**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject

A
Annie_wang 已提交
346
**Return value**
A
Annie_wang 已提交
347

A
Annie_wang 已提交
348 349 350
| Type| Description|
| -------- | -------- |
| Promise&lt;[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)&gt; | Promise used to return **RevokeSaveSuccessResponse**, which contains the session ID.|
A
Annie_wang 已提交
351 352 353

**Example**

A
Annie_wang 已提交
354 355 356 357 358 359 360 361 362 363 364
```js
import distributedObject from '@ohos.data.distributedDataObject';
var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false});
g_object.setSessionId("123456");
g_object.revokeSave().then((result)=>{
    console.log("revokeSave callback");
    console.log("sessionId" + result.sessionId);
}, ()=>{
    console.error("revokeSave failed");
});
```