js-apis-pasteboard.md 47.3 KB
Newer Older
Z
zengyawen 已提交
1 2
# 剪贴板

3
本模块主要提供管理系统剪贴板的能力,为系统复制、粘贴功能提供支持。系统剪贴板支持对文本、HTML、URI、Want、PixelMap等内容的操作。
Z
zengyawen 已提交
4

5 6
> **说明:**
> 
Z
zengyawen 已提交
7 8 9 10
> 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

## 导入模块

11
```js
Z
zengyawen 已提交
12 13 14 15 16
import pasteboard from '@ohos.pasteboard';
```

## 属性

17
**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
18 19 20

| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
21 22 23 24 25 26
| MAX_RECORD_NUM<sup>7+</sup> | number | 是 | 否 | 单个PasteData中所能包含的最大条目数。 |
| MIMETYPE_TEXT_HTML<sup>7+</sup> | string | 是 | 否 | HTML内容的MIME类型定义。 |
| MIMETYPE_TEXT_WANT<sup>7+</sup> | string | 是 | 否 | Want内容的MIME类型定义。 |
| MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | 是 | 否 | 纯文本内容的MIME类型定义。 |
| MIMETYPE_TEXT_URI<sup>7+</sup> | string | 是 | 否 | URI内容的MIME类型定义。 |
| MIMETYPE_PIXELMAP<sup>9+</sup> | string | 是 | 否 | PixelMap内容的MIME类型定义。 |
Z
zengyawen 已提交
27

28
## ValueType<sup>9+</sup>
29 30 31 32 33 34 35

用于表示允许的数据字段类型。

**系统能力:** 以下各项对应的系统能力均为SystemCapability.MiscServices.Pasteboard

| 类型 | 说明 |
| -------- | -------- |
36
| string | 表示string的类型。 |
37 38
| image.PixelMap | 表示[image.PixelMap](js-apis-image.md#pixelmap7)的类型。 |
| Want | 表示[Want](js-apis-application-Want.md)的类型。 |
39
| ArrayBuffer | 表示ArrayBuffer的类型。 |
Z
zengyawen 已提交
40

41
## pasteboard.createData<sup>9+</sup>
Z
zengyawen 已提交
42

43
createData(mimeType: string, value: ValueType): PasteData
Z
zengyawen 已提交
44

45
构建一个自定义类型的剪贴板内容对象。
Z
zengyawen 已提交
46

47 48 49
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
50

Z
zengyawen 已提交
51 52
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
53 54
| mimeType | string | 是 | 自定义数据的MIME类型。 |
| value | [ValueType](#valuetype9) | 是 | 自定义数据内容。 |
55 56

**返回值:**
Z
zengyawen 已提交
57

Z
zengyawen 已提交
58 59
| 类型 | 说明 |
| -------- | -------- |
60
| [PasteData](#pastedata) |  剪贴板内容对象。 |
Z
zengyawen 已提交
61

62
**示例:**
Z
zengyawen 已提交
63

64 65 66 67
  ```js
  var dataXml = 'aStringValueType';
  var pasteData = pasteboard.createData('app/xml', dataXml);
  ```
Z
zengyawen 已提交
68

69
## pasteboard.createRecord<sup>9+</sup>
Z
zengyawen 已提交
70

71
createRecord(mimeType: string, value: ValueType):PasteDataRecord;
Z
zengyawen 已提交
72

73
创建一条自定义数据内容条目。
Z
zengyawen 已提交
74

75 76 77
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
78

Z
zengyawen 已提交
79 80
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
81 82
| mimeType | string | 是 | 自定义数据的MIME类型。 |
| value | [ValueType](#valuetype9) | 是 | 自定义数据内容。 |
83 84

**返回值:**
Z
zengyawen 已提交
85

Z
zengyawen 已提交
86 87
| 类型 | 说明 |
| -------- | -------- |
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
| [PasteDataRecord](#pastedatarecord7) | 一条新建的自定义数据内容条目。 |

**示例:**

  ```js
  var dataXml = 'aStringValueType';
  var pasteDataRecord = pasteboard.createRecord('app/xml', dataXml);
  ```

## pasteboard.getSystemPasteboard

getSystemPasteboard(): SystemPasteboard

获取系统剪贴板对象。

**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| [SystemPasteboard](#systempasteboard) | 系统剪贴板对象。 |
Z
zengyawen 已提交
110

111
**示例:**
Z
zengyawen 已提交
112

113
```js
114
var systemPasteboard = pasteboard.getSystemPasteboard();
115
```
Z
zengyawen 已提交
116

117
## ShareOption<sup>9+</sup>
Z
zengyawen 已提交
118

119
可粘贴数据的范围类型枚举。
Z
zengyawen 已提交
120

121
**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
122

123 124
| 名称  | 说明                    |
| -----  | ----------------------- |
125 126 127
| InApp  |表示仅允许同应用内粘贴。 |
| LocalDevice  |表示允许在此设备中任何应用内粘贴。 |
| CrossDevice  |表示允许跨设备在任何应用内粘贴。 |
128 129 130 131 132 133

## pasteboard.createHtmlData<sup>(deprecated)</sup>

createHtmlData(htmlText: string): PasteData

构建一个HTML剪贴板内容对象。
134 135
> **说明:**
>
136
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.createData](#pasteboardcreatedata9)替代。
137 138

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
139

140
**参数:**
Z
zengyawen 已提交
141

Z
zengyawen 已提交
142 143
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
144
| htmlText | string | 是 | HTML内容。 |
145 146

**返回值:**
Z
zengyawen 已提交
147

Z
zengyawen 已提交
148 149
| 类型 | 说明 |
| -------- | -------- |
150
| [PasteData](#pastedata) | 剪贴板内容对象。 |
Z
zengyawen 已提交
151

152
**示例:**
Z
zengyawen 已提交
153

154
```js
155 156
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + "    <h1>HEAD</h1>\n" + "    <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html);
157
```
Z
zengyawen 已提交
158

159
## pasteboard.createWantData<sup>(deprecated)</sup>
Z
zengyawen 已提交
160

161
createWantData(want: Want): PasteData
Z
zengyawen 已提交
162

163
构建一个Want剪贴板内容对象。
164 165
> **说明:**
>
166
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.createData](#pasteboardcreatedata9)替代。
Z
zengyawen 已提交
167

168 169 170
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
171

Z
zengyawen 已提交
172 173
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
174
| want | [Want](js-apis-application-Want.md) | 是 | Want内容。 |
175 176

**返回值:**
Z
zengyawen 已提交
177

Z
zengyawen 已提交
178 179
| 类型 | 说明 |
| -------- | -------- |
180
| [PasteData](#pastedata) | 剪贴板内容对象。 |
Z
zengyawen 已提交
181

182
**示例:**
Z
zengyawen 已提交
183

184
```js
185 186 187 188 189
var object = {
    bundleName: "com.example.aafwk.test",
    abilityName: "com.example.aafwk.test.TwoAbility"
};
var pasteData = pasteboard.createWantData(object);
190
```
Z
zengyawen 已提交
191

192
## pasteboard.createPlainTextData<sup>(deprecated)</sup>
193

194
createPlainTextData(text: string): PasteData
195

196 197 198 199
构建一个纯文本剪贴板内容对象。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.createData](#pasteboardcreatedata9)替代。
200 201 202 203 204 205 206

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
207
| text | string | 是 | 纯文本内容。 |
208 209 210 211 212

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
213
| [PasteData](#pastedata) | 剪贴板内容对象。 |
214 215 216

**示例:**

217 218 219
```js
var pasteData = pasteboard.createPlainTextData("content");
```
220

221
## pasteboard.createUriData<sup>(deprecated)</sup>
Z
zengyawen 已提交
222

223
createUriData(uri: string): PasteData
Z
zengyawen 已提交
224

225
构建一个URI剪贴板内容对象。
226 227
> **说明:**
>
228
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.createData](#pasteboardcreatedata9)替代。
229 230

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
231

232
**参数:**
Z
zengyawen 已提交
233

Z
zengyawen 已提交
234 235
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
236
| uri | string | 是 | URI内容。 |
Z
zengyawen 已提交
237

238 239
**返回值:**

Z
zengyawen 已提交
240 241
| 类型 | 说明 |
| -------- | -------- |
242
| [PasteData](#pastedata) | 剪贴板内容对象。 |
Z
zengyawen 已提交
243

244
**示例:**
Z
zengyawen 已提交
245

246
```js
247
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt");
248
```
249
## pasteboard.createHtmlTextRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
250

251
createHtmlTextRecord(htmlText: string): PasteDataRecord
Z
zengyawen 已提交
252 253

创建一条HTML内容的条目。
254 255
> **说明:**
>
256
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.createRecord](#pasteboardcreaterecord9)替代。
Z
zengyawen 已提交
257

258 259 260
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
261

Z
zengyawen 已提交
262 263
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
Z
zengyawen 已提交
264
| htmlText | string | 是 | HTML内容。 |
Z
zengyawen 已提交
265

266 267
**返回值:**

Z
zengyawen 已提交
268 269 270
| 类型 | 说明 |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | 一条新建的HTML内容条目。 |
Z
zengyawen 已提交
271

272
**示例:**
Z
zengyawen 已提交
273

274 275 276 277
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + "    <h1>HEAD</h1>\n" + "    <p></p>\n" + "</body>\n" + "</html>";
var record = pasteboard.createHtmlTextRecord(html);
```
Z
zengyawen 已提交
278

279
## pasteboard.createWantRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
280

281
createWantRecord(want: Want): PasteDataRecord
Z
zengyawen 已提交
282 283

创建一条Want内容条目。
284 285
> **说明:**
>
286
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.createRecord](#pasteboardcreaterecord9)替代。
Z
zengyawen 已提交
287

288 289 290
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
291

Z
zengyawen 已提交
292 293
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
294 295 296
| want | [Want](js-apis-application-Want.md) | 是 | Want内容。 |

**返回值:**
Z
zengyawen 已提交
297

Z
zengyawen 已提交
298 299
| 类型 | 说明 |
| -------- | -------- |
300
| [PasteDataRecord](#pastedatarecord7) | 一条新建的Want内容条目。 |
Z
zengyawen 已提交
301

302
**示例:**
Z
zengyawen 已提交
303

304 305 306 307 308 309 310
```js
var object = {
    bundleName: "com.example.aafwk.test",
    abilityName: "com.example.aafwk.test.TwoAbility"
};
var record = pasteboard.createWantRecord(object);
```
Z
zengyawen 已提交
311

312
## pasteboard.createPlainTextRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
313

314
createPlainTextRecord(text: string): PasteDataRecord
Z
zengyawen 已提交
315

316
创建一条纯文本内容条目。
317 318
> **说明:**
>
319
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.createRecord](#pasteboardcreaterecord9)替代。
Z
zengyawen 已提交
320

321 322 323
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
324

Z
zengyawen 已提交
325 326
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
327
| text | string | 是 | 纯文本内容。 |
Z
zengyawen 已提交
328

329 330
**返回值:**

Z
zengyawen 已提交
331 332
| 类型 | 说明 |
| -------- | -------- |
333
| [PasteDataRecord](#pastedatarecord7) | 一条新建的纯文本内容条目。 |
Z
zengyawen 已提交
334

335
**示例:**
Z
zengyawen 已提交
336

337
```js
338
var record = pasteboard.createPlainTextRecord("hello");
339
```
Z
zengyawen 已提交
340

341
## pasteboard.createUriRecord<sup>(deprecated)</sup>
342

343
createUriRecord(uri: string): PasteDataRecord
344

345 346 347 348
创建一条URI内容的条目。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.createRecord](#pasteboardcreaterecord9)替代。
349 350 351 352 353 354 355

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
356
| uri | string | 是 | URI内容。 |
357 358 359 360 361

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
362
| [PasteDataRecord](#pastedatarecord7) | 一条新建的URI内容条目。 |
363 364 365 366

**示例:**

```js
367
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
368
```
Z
zengyawen 已提交
369

370

371
## PasteDataProperty<sup>7+</sup>
Z
zengyawen 已提交
372

373
定义了剪贴板中所有内容条目的属性,包含时间戳、数据类型、粘贴范围以及一些附加数据等。
Z
zengyawen 已提交
374

375
**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
376

Z
zengyawen 已提交
377
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
Z
zengyawen 已提交
378
| -------- | -------- | -------- | -------- | -------- |
379 380
| additions<sup>7+</sup> | {[key:string]:object} | 是 | 是 | 设置的其他附加属性数据。 |
| mimeTypes<sup>7+</sup> | Array&lt;string&gt; | 是 | 否 | 剪贴板内容条目的数据类型,非重复的类型列表。 |
381
| tag<sup>7+</sup> | string | 是 | 是 | 用户自定义标签。 |
382 383
| timestamp<sup>7+</sup> | number | 是 | 否 | 剪贴板数据的写入时间戳(单位:ms)。 |
| localOnly<sup>7+</sup> | boolean | 是 | 是 | 配置剪贴板内容是否为“仅在本地”。默认值为true。<br/>- 配置为true时,表示内容仅在本地,不会在设备之间传递。<br/>- 配置为false时,表示内容将在设备间传递。 |
384
| shareOption<sup>9+</sup> | [ShareOption](#shareoption9) | 是 | 是 | 指示剪贴板数据可以粘贴到的范围,如果未设置或设置不正确,则默认值为CrossDevice。 |
Z
zengyawen 已提交
385 386 387 388 389 390 391

## PasteDataRecord<sup>7+</sup>

对于剪贴板中内容记录的抽象定义,称之为条目。剪贴板内容部分由一个或者多个条目构成,例如一条文本内容、一份HTML、一个URI或者一个Want。

### 属性

392
**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
393 394 395

| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
396 397
| htmlText<sup>7+</sup> | string | 是 | 否 | HTML内容。 |
| want<sup>7+</sup> | [Want](js-apis-application-Want.md) | 是 | 否 | Want内容。 |
Z
zengyawen 已提交
398
| mimeType<sup>7+</sup> | string | 是 | 否 | 数据类型。 |
399
| plainText<sup>7+</sup> | string | 是 | 否 | 纯文本内容。 |
Z
zengyawen 已提交
400
| uri<sup>7+</sup> | string | 是 | 否 | URI内容。 |
401
| pixelMap<sup>9+</sup> | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | 否 | PixelMap内容。 |
402
| data<sup>9+</sup> | {[mimeType:&nbsp;string]:&nbsp;ArrayBuffer} | 是 | 否 | 自定义数据内容。 |
Z
zengyawen 已提交
403

404
### convertToTextV9<sup>9+</sup>
Z
zengyawen 已提交
405

406
convertToTextV9(callback: AsyncCallback&lt;string&gt;): void
Z
zengyawen 已提交
407

408
将一个PasteData中的内容强制转换为文本内容,使用callback异步回调。
409 410

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
411

412
**参数:**
Z
zengyawen 已提交
413

414 415 416
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | 是 | 回调函数,当转换成功,err为undefined,data为强制转换的文本内容;否则返回错误信息。 |
Z
zengyawen 已提交
417

418
**示例:**
Z
zengyawen 已提交
419

420 421
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
422 423 424 425 426
record.convertToTextV9((err, data) => {    
    if (err) {        
        console.error('Failed to convert to text. Cause: ' + JSON.stringify(err));        
        return;   
      }
427 428 429
    console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data));
});
```
Z
zengyawen 已提交
430

431
### convertToTextV9<sup>9+</sup>
Z
zengyawen 已提交
432

433
convertToTextV9(): Promise&lt;string&gt;
Z
zengyawen 已提交
434

435
将一个PasteData中的内容强制转换为文本内容,使用Promise异步回调。
Z
zengyawen 已提交
436

437 438
**系统能力:** SystemCapability.MiscServices.Pasteboard

439
**返回值:**
Z
zengyawen 已提交
440

441 442 443
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;string&gt; | Promise对象,返回强制转换的文本内容。 |
Z
zengyawen 已提交
444

445
**示例:**
Z
zengyawen 已提交
446

447 448
```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
449
record.convertToTextV9().then((data) => {
450
    console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data));
451 452
}).catch((err) => {
    console.error('Failed to convert to text. Cause: ' + JSON.stringify(err));
453 454
});
```
Z
zengyawen 已提交
455

456
### convertToText<sup>(deprecated)</sup>
457

458
convertToText(callback: AsyncCallback&lt;string&gt;): void
459 460

将一个PasteData中的内容强制转换为文本内容,使用callback异步回调。
461 462 463
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[convertToTextV9](#converttotextv99)替代。
464 465 466 467 468 469 470 471 472 473 474 475 476

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | 是 | 回调函数,当转换成功,err为undefined,data为强制转换的文本内容;否则返回错误信息。 |

**示例:**

```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
477
record.convertToText((err, data) => {    
478 479 480 481 482 483 484 485
    if (err) {        
        console.error('Failed to convert to text. Cause: ' + JSON.stringify(err));        
        return;   
      }
    console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data));
});
```

486
### convertToText<sup>(deprecated)</sup>
487

488
convertToText(): Promise&lt;string&gt;
489 490

将一个PasteData中的内容强制转换为文本内容,使用Promise异步回调。
491 492
> **说明:**
>
493
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[convertToTextV9](#converttotextv99-1)替代。
494 495 496 497 498 499 500 501 502 503 504 505 506

**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;string&gt; | Promise对象,返回强制转换的文本内容。 |

**示例:**

```js
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
507
record.convertToText().then((data) => {
508 509 510 511 512
    console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to convert to text. Cause: ' + JSON.stringify(err));
});
```
Z
zengyawen 已提交
513 514 515

## PasteData

516 517
剪贴板内容对象。

Z
zengyawen 已提交
518 519
在调用PasteData的接口前,需要先获取一个PasteData对象。

520
**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
521 522 523 524 525 526 527

### getPrimaryText

getPrimaryText(): string

获取首个条目的纯文本内容。

528
**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
529

530 531
**返回值:**

Z
zengyawen 已提交
532 533 534
| 类型 | 说明 |
| -------- | -------- |
| string | 纯文本内容。 |
Z
zengyawen 已提交
535

536
**示例:**
Z
zengyawen 已提交
537

538 539 540 541
```js
var pasteData = pasteboard.createPlainTextData("hello");
var plainText = pasteData.getPrimaryText();
```
Z
zengyawen 已提交
542 543 544 545 546

### getPrimaryHtml<sup>7+</sup>

getPrimaryHtml(): string

547
获取首个条目的HTML内容。
Z
zengyawen 已提交
548

549 550 551
**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**
Z
zengyawen 已提交
552

Z
zengyawen 已提交
553 554
| 类型 | 说明 |
| -------- | -------- |
555
| string | HTML内容。 |
Z
zengyawen 已提交
556

557
**示例:**
Z
zengyawen 已提交
558

559 560 561 562 563
```js
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + "    <h1>HEAD</h1>\n" + "    <p></p>\n" + "</body>\n" + "</html>";
var pasteData = pasteboard.createHtmlData(html);
var htmlText = pasteData.getPrimaryHtml();
```
Z
zengyawen 已提交
564 565 566 567 568 569 570

### getPrimaryWant<sup>7+</sup>

getPrimaryWant(): Want

获取首个条目的Want对象内容。

571 572 573
**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**
Z
zengyawen 已提交
574

Z
zengyawen 已提交
575 576
| 类型 | 说明 |
| -------- | -------- |
ahjxliubao2's avatar
ahjxliubao2 已提交
577
| [Want](js-apis-application-Want.md) | Want对象内容。 |
Z
zengyawen 已提交
578

579
**示例:**
Z
zengyawen 已提交
580

581 582 583 584 585 586 587 588
```js
var object = { 
    bundleName: "com.example.aafwk.test",    
    abilityName: "com.example.aafwk.test.TwoAbility"
};
var pasteData = pasteboard.createWantData(object);
var want = pasteData.getPrimaryWant();
```
Z
zengyawen 已提交
589 590 591 592 593

### getPrimaryUri<sup>7+</sup>

getPrimaryUri(): string

594 595 596
获取首个条目的URI内容。

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
597

598
**返回值:**
Z
zengyawen 已提交
599

Z
zengyawen 已提交
600 601
| 类型 | 说明 |
| -------- | -------- |
602
| string | URI内容。 |
Z
zengyawen 已提交
603

604
**示例:**
Z
zengyawen 已提交
605

606 607 608 609
```js
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt");
var uri = pasteData.getPrimaryUri();
```
Z
zengyawen 已提交
610

611 612 613 614
### getPrimaryPixelMap<sup>9+</sup>

getPrimaryPixelMap(): image.PixelMap

615 616 617
获取首个条目的PixelMap内容。

**系统能力:** SystemCapability.MiscServices.Pasteboard
618

619
**返回值:**
620 621 622

| 类型 | 说明 |
| -------- | -------- |
623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642
| [image.PixelMap](js-apis-image.md#pixelmap7) | PixelMap内容。 |

**示例:**

```js
import image from '@ohos.multimedia.image';

var buffer = new ArrayBuffer(128)
var opt = {
  size: { height: 3, width: 5 },
  pixelFormat: 3,
  editable: true,
  alphaType: 1,
  scaleMode: 1
}
image.createPixelMap(buffer, opt).then((pixelMap) => {
    var pasteData = pasteboard.createPixelMapData(pixelMap);
    var pixelMap = pasteData.getPrimaryPixelMap();
})
```
643

644
### addRecord<sup>7+</sup>
Z
zengyawen 已提交
645

646
addRecord(record: PasteDataRecord): void
Z
zengyawen 已提交
647

648
向当前剪贴板内容中添加一条条目,同时也会将条目类型添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空,否则添加失败。
Z
zengyawen 已提交
649

L
mod  
LVB8189 已提交
650
剪贴板内容中添加的条目达到数量上限512后,后续的添加操作无效。
Z
zengyawen 已提交
651

652 653 654
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
655

Z
zengyawen 已提交
656 657
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
658
| record | [PasteDataRecord](#pastedatarecord7) | 是 | 待添加的条目。 |
Z
zengyawen 已提交
659

660
**示例:**
Z
zengyawen 已提交
661

662
```js
663 664
var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt");
var textRecord = pasteboard.createPlainTextRecord("hello");
665
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + "    <h1>HEAD</h1>\n" + "    <p></p>\n" + "</body>\n" + "</html>";
666 667 668
var htmlRecord = pasteboard.createHtmlTextRecord(html);
pasteData.addRecord(textRecord);
pasteData.addRecord(htmlRecord);
669
```
670 671
### addRecord<sup>9+</sup>

672
addRecord(mimeType: string, value: ValueType): void
673

674
向当前剪贴板内容中添加一条自定义数据内容条目,同时也会将自定义数据类型添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空,否则添加失败。
675 676 677 678 679 680 681 682 683

剪贴板内容中添加的条目达到数量上限512后,后续的添加操作无效。

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
L
mod  
LVB8189 已提交
684
| mimeType | string | 是 | 自定义数据的MIME类型。 |
685
| value | [ValueType](#valuetype9) | 是 | 自定义数据内容。 |
686

687 688 689 690 691
**错误码:**
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 12900002 | if the count of records in PasteData exceeds MAX_RECORD_NUM. |

692 693 694 695
**示例:**

  ```js
  var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt");
696
  var dataXml = 'aStringValueType';
697 698 699
  pasteData.addRecord('app/xml', dataXml);
  ```

Z
zengyawen 已提交
700 701 702 703 704 705
### getMimeTypes<sup>7+</sup>

getMimeTypes(): Array&lt;string&gt;

获取剪贴板中[PasteDataProperty](#pastedataproperty7)的mimeTypes列表,当剪贴板内容为空时,返回列表为空。

706 707 708
**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**
Z
zengyawen 已提交
709

Z
zengyawen 已提交
710 711
| 类型 | 说明 |
| -------- | -------- |
712
| Array&lt;string&gt; | 剪贴板内容条目的数据类型,非重复的类型列表。 |
Z
zengyawen 已提交
713

714
**示例:**
Z
zengyawen 已提交
715

716 717 718 719
```js
var pasteData = pasteboard.createPlainTextData("hello");
var types = pasteData.getMimeTypes();
```
Z
zengyawen 已提交
720 721 722 723 724

### getPrimaryMimeType<sup>7+</sup>

getPrimaryMimeType(): string

725
获取剪贴板内容中首个条目的数据类型。
Z
zengyawen 已提交
726

727 728 729
**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**
Z
zengyawen 已提交
730

Z
zengyawen 已提交
731 732 733
| 类型 | 说明 |
| -------- | -------- |
| string | 首个条目的数据类型。 |
Z
zengyawen 已提交
734

735
**示例:**
Z
zengyawen 已提交
736

737 738 739 740
```js
var pasteData = pasteboard.createPlainTextData("hello");
var type = pasteData.getPrimaryMimeType();
```
Z
zengyawen 已提交
741 742 743 744 745

### getProperty<sup>7+</sup>

getProperty(): PasteDataProperty

746
获取剪贴板内容的属性描述对象。
Z
zengyawen 已提交
747

748 749 750
**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**
Z
zengyawen 已提交
751

Z
zengyawen 已提交
752 753 754
| 类型 | 说明 |
| -------- | -------- |
| [PasteDataProperty](#pastedataproperty7) | 属性描述对象。 |
Z
zengyawen 已提交
755

756
**示例:**
Z
zengyawen 已提交
757

758 759 760 761
```js
var pasteData = pasteboard.createPlainTextData("hello");
var property = pasteData.getProperty();
```
Z
zengyawen 已提交
762

763
### setProperty<sup>9+</sup>
764

765
setProperty(property: PasteDataProperty): void
766

767 768 769
设置剪贴板内容的属性描述对象,当前仅支持设置shareOption属性。

**系统能力:** SystemCapability.MiscServices.Pasteboard
770

771
**参数:**
772 773 774

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
775
| property | [PasteDataProperty](#pastedataproperty7) | 是 | 属性描述对象。 |
776

777
**示例:**
778

779 780 781 782 783 784
```js
var pasteData = pasteboard.createHtmlData('application/xml');
let prop = pasteData.getProperty();
prop.shareOption = pasteboard.ShareOption.InApp;
pasteData.setProperty(prop);
```
785

786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805
### getRecord<sup>9+</sup>

getRecord(index: number): PasteDataRecord

获取剪贴板内容中指定下标的条目。

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定条目的下标。 |

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| [PasteDataRecord](#pastedatarecord7) | 指定下标的条目。 |

806 807 808 809 810 811
**错误码:**
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 12900001 | if type of index is not number. |
| 12900002 | if index is out of the record count of PasteData. |

812 813 814 815 816 817
**示例:**

```js
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecord(0);
```
Z
zengyawen 已提交
818 819 820 821 822

### getRecordCount<sup>7+</sup>

getRecordCount(): number

823 824 825
获取剪贴板内容中条目的个数。

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
826

827
**返回值:**
Z
zengyawen 已提交
828

Z
zengyawen 已提交
829 830 831
| 类型 | 说明 |
| -------- | -------- |
| number | 条目的个数。 |
Z
zengyawen 已提交
832

833
**示例:**
Z
zengyawen 已提交
834

835 836 837 838
```js
var pasteData = pasteboard.createPlainTextData("hello");
var count = pasteData.getRecordCount();
```
Z
zengyawen 已提交
839 840 841 842 843

### getTag<sup>7+</sup>

getTag(): string

844 845 846
获取剪贴板内容中用户自定义的标签内容,如果没有设置用户自定义的标签内容将返回空。

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
847

848
**返回值:**
Z
zengyawen 已提交
849

Z
zengyawen 已提交
850 851
| 类型 | 说明 |
| -------- | -------- |
852
| string | 返回用户自定义的标签内容,如果没有设置用户自定义的标签内容,将返回空。 |
Z
zengyawen 已提交
853

854
**示例:**
Z
zengyawen 已提交
855

856 857 858 859
```js
var pasteData = pasteboard.createPlainTextData("hello");
var tag = pasteData.getTag();
```
Z
zengyawen 已提交
860

861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887
### hasType<sup>9+</sup>

hasType(mimeType: string): boolean

检查剪贴板内容中是否有指定的MIME数据类型。

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| mimeType | string | 是 | 待查询的数据类型。 |

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| boolean | 有指定的数据类型返回true,否则返回false。 |

**示例:**

```js
var pasteData = pasteboard.createPlainTextData("hello");
var hasType = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN);
```

888
### removeRecord<sup>9+</sup>
Z
zengyawen 已提交
889

890
removeRecord(index: number): void
Z
zengyawen 已提交
891

892
移除剪贴板内容中指定下标的条目。
893 894

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
895

896
**参数:**
Z
zengyawen 已提交
897

Z
zengyawen 已提交
898 899
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
900
| index | number | 是 | 指定的下标。 |
Z
zengyawen 已提交
901

902 903 904 905 906
**错误码:**
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 12900002 | if index is out of the record count of PasteData. |

907
**示例:**
Z
zengyawen 已提交
908

909 910
```js
var pasteData = pasteboard.createPlainTextData("hello");
911
pasteData.removeRecord(0);
912
```
Z
zengyawen 已提交
913

914
### replaceRecord<sup>9+</sup>
Z
zengyawen 已提交
915

916
replaceRecord(index: number, record: PasteDataRecord): void
Z
zengyawen 已提交
917

918
替换剪贴板内容中指定下标的条目。
919 920

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
921

922
**参数:**
Z
zengyawen 已提交
923

Z
zengyawen 已提交
924 925 926
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定的下标。 |
927
| record | [PasteDataRecord](#pastedatarecord7) | 是 | 新条目的内容。 |
Z
zengyawen 已提交
928

929 930 931 932 933
**错误码:**
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 12900002 | if index is out of the record count of PasteData. |

934
**示例:**
Z
zengyawen 已提交
935

936 937
```js
var pasteData = pasteboard.createPlainTextData("hello");
938 939
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
pasteData.replaceRecord(0, record);
940
```
941
### addHtmlRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
942

943
addHtmlRecord(htmlText: string): void
944

945
向当前剪贴板内容中添加一条HTML内容条目,并将MIMETYPE_TEXT_HTML添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空,否则添加失败。
946

947 948 949 950
剪贴板内容中添加的条目达到数量上限512后,后续的添加操作无效。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[addRecord](#addrecord9)替代。
951 952 953 954 955 956 957

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
958
| htmlText | string | 是 | HTML内容。 |
959 960 961 962 963

**示例:**

```js
var pasteData = pasteboard.createPlainTextData("hello");
964 965
var html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + "    <h1>HEAD</h1>\n" + "    <p></p>\n" + "</body>\n" + "</html>";
pasteData.addHtmlRecord(html);
966
```
Z
zengyawen 已提交
967

968
### addWantRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
969

970
addWantRecord(want: Want): void
Z
zengyawen 已提交
971

972 973 974
向当前剪贴板内容中添加一条Want条目,并将MIMETYPE_TEXT_WANT添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空,否则添加失败。

剪贴板内容中添加的条目达到数量上限512后,后续的添加操作无效。
975 976
> **说明:**
>
977
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[addRecord](#addrecord9)替代。
978 979

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
980

981
**参数:**
Z
zengyawen 已提交
982

Z
zengyawen 已提交
983 984
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
985
| want | [Want](js-apis-application-Want.md) | 是 | Want对象内容。 |
Z
zengyawen 已提交
986

987
**示例:**
Z
zengyawen 已提交
988

989 990
```js
var pasteData = pasteboard.createPlainTextData("hello");
991 992 993 994 995
var object = { 
    bundleName: "com.example.aafwk.test",    
    abilityName: "com.example.aafwk.test.TwoAbility"
};
pasteData.addWantRecord(object);
996
```
Z
zengyawen 已提交
997

998
### addTextRecord<sup>(deprecated)</sup>
999

1000
addTextRecord(text: string): void
1001

1002 1003 1004 1005 1006 1007
向当前剪贴板内容中添加一条纯文本条目,并将MIME_TEXT_PLAIN添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空,否则添加失败。

剪贴板内容中添加的条目达到数量上限512后,后续的添加操作无效。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[addRecord](#addrecord9)替代。
1008 1009 1010 1011 1012 1013 1014

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1015
| text | string | 是 | 纯文本内容。 |
1016 1017 1018 1019 1020

**示例:**

```js
var pasteData = pasteboard.createPlainTextData("hello");
1021
pasteData.addTextRecord("good");
Z
zengyawen 已提交
1022 1023
```

1024
### addUriRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
1025

1026
addUriRecord(uri: string): void
Z
zengyawen 已提交
1027

1028
向当前剪贴板内容中添加一条URI条目,并将MIMETYPE_TEXT_URI添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空,否则添加失败。
Z
zengyawen 已提交
1029

1030 1031 1032 1033
剪贴板内容中添加的条目达到数量上限512后,后续的添加操作无效。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[addRecord](#addrecord9)替代。
1034 1035

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
1036

1037
**参数:**
Z
zengyawen 已提交
1038

Z
zengyawen 已提交
1039 1040
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1041
| uri | string | 是 | URI内容。 |
Z
zengyawen 已提交
1042

1043
**示例:**
Z
zengyawen 已提交
1044

1045
```js
1046 1047
var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addUriRecord("dataability:///com.example.myapplication1/user.txt");
1048
```
1049
### getRecordAt<sup>(deprecated)</sup>
Z
zengyawen 已提交
1050

1051
getRecordAt(index: number): PasteDataRecord
Z
zengyawen 已提交
1052

1053 1054 1055 1056
获取剪贴板内容中指定下标的条目。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[getRecord](#getrecord9)替代。
Z
zengyawen 已提交
1057

1058 1059 1060
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
1061

1062 1063 1064
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定条目的下标。 |
Z
zengyawen 已提交
1065

1066 1067
**返回值:**

Z
zengyawen 已提交
1068 1069
| 类型 | 说明 |
| -------- | -------- |
1070
| [PasteDataRecord](#pastedatarecord7) | 指定下标的条目。 |
Z
zengyawen 已提交
1071

1072
**示例:**
Z
zengyawen 已提交
1073

1074
```js
1075 1076
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecordAt(0);
1077
```
Z
zengyawen 已提交
1078

1079
### hasMimeType<sup>(deprecated)</sup>
1080

1081
hasMimeType(mimeType: string): boolean
1082

1083 1084 1085 1086
检查剪贴板内容中是否有指定的数据类型。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[hasType](#hastype9)替代。
1087 1088 1089 1090 1091 1092 1093

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1094 1095 1096 1097 1098 1099 1100
| mimeType | string | 是 | 待查询的数据类型。 |

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| boolean | 有指定的数据类型返回true,否则返回false。 |
1101 1102 1103 1104

**示例:**

```js
1105 1106
var pasteData = pasteboard.createPlainTextData("hello");
var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);
1107
```
1108
### removeRecordAt<sup>(deprecated)</sup>
1109

1110
removeRecordAt(index: number): boolean
1111

1112 1113 1114 1115
移除剪贴板内容中指定下标的条目。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[removeRecord](#removerecord9)替代。
1116

1117
**系统能力:** SystemCapability.MiscServices.Pasteboard
1118

1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定的下标。 |

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| boolean | 成功移除返回true,失败返回false。 |

**示例:**

```js
var pasteData = pasteboard.createPlainTextData("hello");
var isRemove = pasteData.removeRecordAt(0);
```
### replaceRecordAt<sup>(deprecated)</sup>

replaceRecordAt(index: number, record: PasteDataRecord): boolean

替换剪贴板内容中指定下标的条目。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[replaceRecord](#replacerecord9)替代。
1145 1146 1147 1148 1149

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

1150 1151 1152 1153
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定的下标。 |
| record | [PasteDataRecord](#pastedatarecord7) | 是 | 替换后的条目。 |
1154 1155 1156 1157 1158

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
1159
| boolean | 成功替换返回true,失败返回false。 |
1160 1161 1162 1163

**示例:**

```js
1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175
var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt");
var isReplace = pasteData.replaceRecordAt(0, record);
```

## SystemPasteboard

系统剪贴板对象。

在调用SystemPasteboard的接口前,需要先通过[getSystemPasteboard](#pasteboardgetsystempasteboard)获取系统剪贴板。

```js
1176 1177
var systemPasteboard = pasteboard.getSystemPasteboard();
```
Z
zengyawen 已提交
1178

1179
### on('update')<sup>7+</sup>
Z
zengyawen 已提交
1180

1181
on(type:  'update', callback: () =&gt;void ): void
Z
zengyawen 已提交
1182

1183
订阅系统剪贴板内容变化事件,当系统剪贴板中内容变化时触发用户程序的回调。
1184 1185

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
1186

1187
**参数:**
Z
zengyawen 已提交
1188

Z
zengyawen 已提交
1189 1190
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1191 1192
| type | string | 是 | 取值为'update',表示系统剪贴板内容变化事件。 |
| callback | function | 是 | 剪贴板中内容变化时触发的用户程序的回调。 |
Z
zengyawen 已提交
1193

1194
**示例:**
Z
zengyawen 已提交
1195

1196 1197
```js
var systemPasteboard = pasteboard.getSystemPasteboard();
1198 1199 1200 1201
var listener = () => {
    console.info('The system pasteboard has changed.');
};
systemPasteboard.on('update', listener);
1202
```
Z
zengyawen 已提交
1203

1204
### off('update')<sup>7+</sup>
Z
zengyawen 已提交
1205

1206
off(type:  'update', callback?: () =&gt;void ): void
Z
zengyawen 已提交
1207

1208
取消订阅系统剪贴板内容变化事件。
1209 1210

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
1211

1212
**参数:**
Z
zengyawen 已提交
1213

1214 1215 1216 1217
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| type | string | 是 | 取值为'update',表示系统剪贴板内容变化事件。 |
| callback | function | 否 | 剪贴板中内容变化时触发的用户程序的回调。 |
Z
zengyawen 已提交
1218

1219
**示例:**
Z
zengyawen 已提交
1220

1221
```js
1222 1223 1224 1225
let listener = () => {
    console.info('The system pasteboard has changed.');
};    
systemPasteboard.off('update', listener);
1226
```
Z
zengyawen 已提交
1227

1228
### clearData<sup>9+</sup>
1229

1230
clearData(callback: AsyncCallback&lt;void&gt;): void
1231

1232
清空系统剪贴板内容,使用callback异步回调。
1233 1234 1235 1236 1237 1238 1239

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1240
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当成功清空时,err为undefined;否则为错误对象。 |
1241 1242 1243 1244

**示例:**

```js
1245 1246
systemPasteboard.clearData((err, data) => { 
    if (err) {        
1247
        console.error('Failed to clear the pasteboard. Cause: ' + JSON.stringify(err));
1248
        return;    
1249
    }
1250
    console.info('Succeeded in clearing the pasteboard.');
1251 1252 1253
});
```

1254
### clearData<sup>9+</sup>
1255

1256
clearData(): Promise&lt;void&gt;
1257

1258
清空系统剪贴板内容,使用Promise异步回调。
1259 1260 1261 1262 1263 1264 1265

**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
1266
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
1267 1268 1269 1270

**示例:**

```js
1271 1272 1273 1274 1275
systemPasteboard.clearData().then((data) => { 
    console.info('Succeeded in clearing the pasteboard.');
}).catch((err) => {    
    console.error('Failed to clear the pasteboard. Cause: ' + JSON.stringify(err));
});
1276
```
Z
zengyawen 已提交
1277

1278
### setData<sup>9+</sup>
Z
zengyawen 已提交
1279

1280
setData(data: PasteData, callback: AsyncCallback&lt;void&gt;): void
Z
zengyawen 已提交
1281

1282
将数据写入系统剪贴板,使用callback异步回调。
Z
zengyawen 已提交
1283

1284 1285 1286
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
1287

Z
zengyawen 已提交
1288 1289
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1290 1291
| data | [PasteData](#pastedata) | 是 | PasteData对象。 |
| callback | AsyncCallback&lt;void> | 是 | 回调函数。当写入成功,err为undefined,否则为错误对象。 |
Z
zengyawen 已提交
1292

1293 1294 1295 1296 1297
**错误码:**
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 12900003 | if another setData is being processed or the system prohibits copying. |

1298
**示例:**
Z
zengyawen 已提交
1299

1300
```js
1301
var pasteData = pasteboard.createPlainTextData("content");
1302
var systemPasteboard = pasteboard.getSystemPasteboard();
1303 1304 1305 1306 1307 1308 1309
systemPasteboard.setData(pasteData, (err, data) => { 
    if (err) {
        console.error('Failed to set PasteData. Cause: ' + err.message);
        return;
    }
    console.info('Succeeded in setting PasteData.');
});
1310
```
Z
zengyawen 已提交
1311

1312
### setData<sup>9+</sup>
Z
zengyawen 已提交
1313

1314
setData(data: PasteData): Promise&lt;void&gt;
Z
zengyawen 已提交
1315

1316
将数据写入系统剪贴板,使用Promise异步回调。
Z
zengyawen 已提交
1317

1318 1319 1320
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**
Z
zengyawen 已提交
1321

1322 1323 1324 1325 1326 1327 1328 1329 1330
| 参数名 | 类型 | 说明 |
| -------- | -------- | -------- |
| data | [PasteData](#pastedata) | PasteData对象。 |

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
Z
zengyawen 已提交
1331

1332 1333 1334 1335 1336
**错误码:**
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 12900003 | if another setData is being processed or the system prohibits copying. |

1337
**示例:**
Z
zengyawen 已提交
1338

1339
```js
1340 1341 1342 1343 1344 1345 1346
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setData(pasteData).then((data) => {
    console.info('Succeeded in setting PasteData.');
}).catch((err) => {
    console.error('Failed to set PasteData. Cause: ' + err.message);
});
1347
```
Z
zengyawen 已提交
1348

1349
### getData<sup>9+</sup>
Z
zengyawen 已提交
1350

1351
getData( callback: AsyncCallback&lt;PasteData&gt;): void
Z
zengyawen 已提交
1352

1353
读取系统剪贴板内容,使用callback异步回调。
1354 1355

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
1356

1357
**参数:**
Z
zengyawen 已提交
1358

Z
zengyawen 已提交
1359 1360
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1361
| callback | AsyncCallback&lt;[PasteData](#pastedata)&gt; | 是 | 回调函数。当读取成功,err为undefined,data为返回的系统剪贴板数据;否则返回错误对象。 |
1362

1363 1364 1365 1366 1367
**错误码:**
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 12900003 | if another getData is being processed. |

1368 1369 1370
**示例:**

```js
1371 1372
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getData((err, pasteData) => {  
1373
    if (err) {
1374
        console.error('Failed to get PasteData. Cause: ' + err.message);
1375 1376
        return;
    }
1377
    var text = pasteData.getPrimaryText();
1378 1379
});
```
Z
zengyawen 已提交
1380

1381
### getData<sup>9+</sup>
Z
zengyawen 已提交
1382

1383
getData(): Promise&lt;PasteData&gt;
Z
zengyawen 已提交
1384

1385
读取系统剪贴板内容,使用Promise异步回调。
1386 1387

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
1388

1389
**返回值:**
Z
zengyawen 已提交
1390

Z
zengyawen 已提交
1391 1392
| 类型 | 说明 |
| -------- | -------- |
1393
| Promise&lt;[PasteData](#pastedata)&gt; | Promise对象,返回系统剪贴板数据。 |
Z
zengyawen 已提交
1394

1395 1396 1397 1398 1399
**错误码:**
| 错误码ID | 错误码信息 |
| -------- | -------- |
| 12900003 | if another getData is being processed. |

1400
**示例:**
Z
zengyawen 已提交
1401

1402
```js
1403 1404 1405
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getData().then((pasteData) => { 
    var text = pasteData.getPrimaryText();
1406
}).catch((err) => {
1407 1408
    console.error('Failed to get PasteData. Cause: ' + err.message);
})
1409
```
Z
zengyawen 已提交
1410

1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459
### hasData<sup>9+</sup>

hasData(callback:  AsyncCallback&lt;boolean&gt;): void

判断系统剪贴板中是否有内容,使用callback异步回调。

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 返回true表示系统剪贴板中有内容,返回false表示系统剪贴板中没有内容。 |

**示例:**

```js
systemPasteboard.hasData((err, data) => {
    if (err) {
        console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err));
        return;
    }
    console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data));
});
```

### hasData<sup>9+</sup>

hasData(): Promise&lt;boolean&gt;

判断系统剪贴板中是否有内容,使用Promise异步回调。

**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | 返回true表示系统剪贴板中有内容,返回false表示系统剪贴板中没有内容。 |

**示例:**

```js
systemPasteboard.hasData().then((data) => { 
    console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err));
});
```
Z
zengyawen 已提交
1460

1461
### clear<sup>(deprecated)</sup>
Z
zengyawen 已提交
1462

1463
clear(callback: AsyncCallback&lt;void&gt;): void
Z
zengyawen 已提交
1464

1465
清空系统剪贴板内容,使用callback异步回调。
1466 1467 1468
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.clearData](#cleardata9)替代。
1469 1470

**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
1471

1472
**参数:**
Z
zengyawen 已提交
1473

Z
zengyawen 已提交
1474 1475
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1476 1477 1478 1479 1480 1481 1482
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当成功清空时,err为undefined;否则为错误对象。 |

**示例:**

```js
systemPasteboard.clear((err, data) => { 
    if (err) {        
1483
        console.error('Failed to clear the PasteData. Cause: ' + JSON.stringify(err));
1484 1485 1486 1487 1488
        return;    
    }
    console.info('Succeeded in clearing the PasteData.');
});
```
Z
zengyawen 已提交
1489

1490
### clear<sup>(deprecated)</sup>
Z
zengyawen 已提交
1491

1492
clear(): Promise&lt;void&gt;
Z
zengyawen 已提交
1493

1494
清空系统剪贴板内容,使用Promise异步回调。
1495 1496 1497
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.clearData](#cleardata9-1)替代。
1498

1499
**系统能力:** SystemCapability.MiscServices.Pasteboard
Z
zengyawen 已提交
1500

1501
**返回值:**
Z
zengyawen 已提交
1502

Z
zengyawen 已提交
1503 1504
| 类型 | 说明 |
| -------- | -------- |
1505
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
Z
zengyawen 已提交
1506

1507
**示例:**
Z
zengyawen 已提交
1508

1509 1510 1511 1512 1513 1514
```js
systemPasteboard.clear().then((data) => { 
    console.info('Succeeded in clearing the PasteData.');
}).catch((err) => {    
    console.error('Failed to clear the PasteData. Cause: ' + JSON.stringify(err));
});
1515 1516
```

1517
### getPasteData<sup>(deprecated)</sup>
1518

1519
getPasteData( callback: AsyncCallback&lt;PasteData&gt;): void
1520

1521 1522 1523 1524
读取系统剪贴板内容,使用callback异步回调。
> **说明:**
>
> 从 API Version 6 开始支持,从 API Version 9 开始废弃,建议使用[getData](#getdata9)替代。
1525 1526 1527 1528 1529 1530 1531

**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1532
| callback | AsyncCallback&lt;[PasteData](#pastedata)&gt; | 是 | 回调函数。当读取成功,err为undefined,data为返回的系统剪贴板数据;否则返回错误对象。 |
1533 1534 1535 1536

**示例:**

```js
1537 1538 1539 1540 1541
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData((err, pasteData) => {  
    if (err) {
        console.error('Failed to get PasteData. Cause: ' + err.message);
        return;
1542
    }
1543
    var text = pasteData.getPrimaryText();
1544 1545 1546
});
```

1547
### getPasteData<sup>(deprecated)</sup>
1548

1549
getPasteData(): Promise&lt;PasteData&gt;
1550

1551 1552 1553 1554
读取系统剪贴板内容,使用Promise异步回调。
> **说明:**
>
> 从 API Version 6 开始支持,从 API Version 9 开始废弃,建议使用[getData](#getdata9-1)替代。
1555 1556 1557 1558 1559

**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**

1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[PasteData](#pastedata)&gt; | Promise对象,返回系统剪贴板数据。 |

**示例:**

```js
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData().then((pasteData) => { 
    var text = pasteData.getPrimaryText();
}).catch((err) => {
    console.error('Failed to get PasteData. Cause: ' + err.message);
})
```

### hasPasteData<sup>(deprecated)</sup>

hasPasteData(callback:  AsyncCallback&lt;boolean&gt;): void

判断系统剪贴板中是否有内容,使用callback异步回调。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[hasData](#hasdata9)替代。
1583

1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | 是 | 返回true表示系统剪贴板中有内容,返回false表示系统剪贴板中没有内容。 |

**示例:**

```js
systemPasteboard.hasPasteData((err, data) => {
    if (err) {
        console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err));
        return;
    }
    console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data));
});
```

### hasPasteData<sup>(deprecated)</sup>

hasPasteData(): Promise&lt;boolean&gt;

判断系统剪贴板中是否有内容,使用Promise异步回调。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[hasData](#hasdata9-1)替代。
1612

1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638
**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;boolean&gt; | 返回true表示系统剪贴板中有内容,返回false表示系统剪贴板中没有内容。 |

**示例:**

```js
systemPasteboard.hasPasteData().then((data) => { 
    console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err));
});
```

### setPasteData<sup>(deprecated)</sup>

setPasteData(data: PasteData, callback: AsyncCallback&lt;void&gt;): void

将数据写入系统剪贴板,使用callback异步回调。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[setData](#setdata9)替代。
1639

1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| data | [PasteData](#pastedata) | 是 | PasteData对象。 |
| callback | AsyncCallback&lt;void> | 是 | 回调函数。当写入成功,err为undefined,否则为错误对象。 |

**示例:**

```js
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData, (err, data) => { 
    if (err) {
        console.error('Failed to set PasteData. Cause: ' + err.message);
        return;
    }
    console.info('Succeeded in setting PasteData.');
});
```
### setPasteData<sup>(deprecated)</sup>

setPasteData(data: PasteData): Promise&lt;void&gt;

将数据写入系统剪贴板,使用Promise异步回调。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[setData](#setdata9-1)替代。
1670

1671 1672 1673 1674 1675 1676 1677 1678 1679 1680
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

| 参数名 | 类型 | 说明 |
| -------- | -------- | -------- |
| data | [PasteData](#pastedata) | PasteData对象。 |

**返回值:**

1681 1682 1683 1684 1685 1686 1687
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |

**示例:**

```js
1688 1689 1690 1691 1692 1693
var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData).then((data) => {
    console.info('Succeeded in setting PasteData.');
}).catch((err) => {
    console.error('Failed to set PasteData. Cause: ' + err.message);
1694
});
1695
```