js-apis-pasteboard.md 47.7 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
import pasteboard from '@ohos.pasteboard';
```

15
## 常量
Z
zengyawen 已提交
16

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

19 20 21
| 名称 | 参数类型 | 值 | 说明 |
| -------- | -------- | -------- | -------- |
| MAX_RECORD_NUM<sup>7+</sup> | number | 512 | 单个PasteData中所能包含的最大条目数。 |
22 23 24 25 26
| MIMETYPE_TEXT_HTML<sup>7+</sup> | string | 'text/html' | HTML内容的MIME类型定义。 |
| MIMETYPE_TEXT_WANT<sup>7+</sup> | string | 'text/want' | Want内容的MIME类型定义。 |
| MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | 'text/plain' | 纯文本内容的MIME类型定义。 |
| MIMETYPE_TEXT_URI<sup>7+</sup> | string | 'text/uri' | URI内容的MIME类型定义。 |
| MIMETYPE_PIXELMAP<sup>9+</sup> | string | 'pixelMap' | 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
  ```js
65 66
  let dataXml = new ArrayBuffer(256);
  let pasteData = pasteboard.createData('app/xml', dataXml);
67
  ```
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
| [PasteDataRecord](#pastedatarecord7) | 一条新建的自定义数据内容条目。 |

**示例:**

  ```js
93 94
  let dataXml = new ArrayBuffer(256);
  let pasteDataRecord = pasteboard.createRecord('app/xml', dataXml);
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
  ```

## pasteboard.getSystemPasteboard

getSystemPasteboard(): SystemPasteboard

获取系统剪贴板对象。

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

**返回值:**

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

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

113
```js
114
let 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
let 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>";
let 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
let object = {
186 187 188
    bundleName: "com.example.aafwk.test",
    abilityName: "com.example.aafwk.test.TwoAbility"
};
189
let 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
```js
218
let pasteData = pasteboard.createPlainTextData('content');
219
```
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
let 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
```js
275 276
let 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>";
let record = pasteboard.createHtmlTextRecord(html);
277
```
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
```js
305
let object = {
306 307 308
    bundleName: "com.example.aafwk.test",
    abilityName: "com.example.aafwk.test.TwoAbility"
};
309
let record = pasteboard.createWantRecord(object);
310
```
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
let 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
let 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
```js
421 422 423
let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');
record.convertToTextV9((err, data) => {
    if (err) {
424
        console.error(`Failed to convert to text. Cause: ${err.message}`);
425 426
        return;
    }
427
    console.info(`Succeeded in converting to text. Data: ${data}`);
428 429
});
```
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
```js
448
let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');
449
record.convertToTextV9().then((data) => {
450
    console.info(`Succeeded in converting to text. Data: ${data}`);
451
}).catch((err) => {
452
    console.error(`Failed to convert to text. Cause: ${err.message}`);
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

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

**参数:**

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

**示例:**

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

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

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

**返回值:**

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

**示例:**

```js
506
let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');
507
record.convertToText().then((data) => {
508
    console.info(`Succeeded in converting to text. Data: ${data}`);
509
}).catch((err) => {
510
    console.error(`Failed to convert to text. Cause: ${err.message}`);
511 512
});
```
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
```js
539 540
let pasteData = pasteboard.createPlainTextData('hello');
let plainText = pasteData.getPrimaryText();
541
```
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
```js
560 561 562
let 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>";
let pasteData = pasteboard.createHtmlData(html);
let htmlText = pasteData.getPrimaryHtml();
563
```
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
```js
582 583
let object = { 
    bundleName: "com.example.aafwk.test",
584 585
    abilityName: "com.example.aafwk.test.TwoAbility"
};
586 587
let pasteData = pasteboard.createWantData(object);
let want = pasteData.getPrimaryWant();
588
```
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
```js
607 608
let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt');
let uri = pasteData.getPrimaryUri();
609
```
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
| [image.PixelMap](js-apis-image.md#pixelmap7) | PixelMap内容。 |

**示例:**

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

630 631
let buffer = new ArrayBuffer(128);
let opt = {
632 633 634 635 636
  size: { height: 3, width: 5 },
  pixelFormat: 3,
  editable: true,
  alphaType: 1,
  scaleMode: 1
637
};
638
image.createPixelMap(buffer, opt).then((pixelMap) => {
639 640 641
    let pasteData = pasteboard.createPixelMapData(pixelMap);
    let pixelMap = pasteData.getPrimaryPixelMap();
});
642
```
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 665 666
let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt');
let textRecord = pasteboard.createPlainTextRecord('hello');
let 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>";
let htmlRecord = pasteboard.createHtmlTextRecord(html);
667 668
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
以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)
690
| 错误码ID | 错误信息 |
691
| -------- | -------- |
692
| 12900002 | The number of record exceeds the maximum limit. |
693

694 695 696
**示例:**

  ```js
697 698
  let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt');
  let dataXml = new ArrayBuffer(256);
699 700 701
  pasteData.addRecord('app/xml', dataXml);
  ```

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

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

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

708 709 710
**系统能力:** SystemCapability.MiscServices.Pasteboard

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

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

716
**示例:**
Z
zengyawen 已提交
717

718
```js
719 720
let pasteData = pasteboard.createPlainTextData('hello');
let types = pasteData.getMimeTypes();
721
```
Z
zengyawen 已提交
722 723 724 725 726

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

getPrimaryMimeType(): string

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

729 730 731
**系统能力:** SystemCapability.MiscServices.Pasteboard

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

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

737
**示例:**
Z
zengyawen 已提交
738

739
```js
740 741
let pasteData = pasteboard.createPlainTextData('hello');
let type = pasteData.getPrimaryMimeType();
742
```
Z
zengyawen 已提交
743 744 745 746 747

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

getProperty(): PasteDataProperty

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

750 751 752
**系统能力:** SystemCapability.MiscServices.Pasteboard

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

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

758
**示例:**
Z
zengyawen 已提交
759

760
```js
761 762
let pasteData = pasteboard.createPlainTextData('hello');
let property = pasteData.getProperty();
763
```
Z
zengyawen 已提交
764

765
### setProperty<sup>9+</sup>
766

767
setProperty(property: PasteDataProperty): void
768

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

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

773
**参数:**
774 775 776

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

779
**示例:**
780

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

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

getRecord(index: number): PasteDataRecord

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

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

**参数:**

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

**返回值:**

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

808
**错误码:**
809

810
以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)
811
| 错误码ID | 错误信息 |
812
| -------- | -------- |
813
| 12900001 | The index is out of range. |
814

815 816 817
**示例:**

```js
818 819
let pasteData = pasteboard.createPlainTextData('hello');
let record = pasteData.getRecord(0);
820
```
Z
zengyawen 已提交
821 822 823 824 825

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

getRecordCount(): number

826 827 828
获取剪贴板内容中条目的个数。

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

830
**返回值:**
Z
zengyawen 已提交
831

Z
zengyawen 已提交
832 833 834
| 类型 | 说明 |
| -------- | -------- |
| number | 条目的个数。 |
Z
zengyawen 已提交
835

836
**示例:**
Z
zengyawen 已提交
837

838
```js
839 840
let pasteData = pasteboard.createPlainTextData('hello');
let count = pasteData.getRecordCount();
841
```
Z
zengyawen 已提交
842 843 844 845 846

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

getTag(): string

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

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

851
**返回值:**
Z
zengyawen 已提交
852

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

857
**示例:**
Z
zengyawen 已提交
858

859
```js
860 861
let pasteData = pasteboard.createPlainTextData('hello');
let tag = pasteData.getTag();
862
```
Z
zengyawen 已提交
863

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

hasType(mimeType: string): boolean

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

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

**参数:**

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

**返回值:**

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

**示例:**

```js
887 888
let pasteData = pasteboard.createPlainTextData('hello');
let hasType = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN);
889 890
```

891
### removeRecord<sup>9+</sup>
Z
zengyawen 已提交
892

893
removeRecord(index: number): void
Z
zengyawen 已提交
894

895
移除剪贴板内容中指定下标的条目。
896 897

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

899
**参数:**
Z
zengyawen 已提交
900

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

905
**错误码:**
906

907
以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)
908
| 错误码ID | 错误信息 |
909
| -------- | -------- |
910
| 12900001 | The index is out of range. |
911

912
**示例:**
Z
zengyawen 已提交
913

914
```js
915
let pasteData = pasteboard.createPlainTextData('hello');
916
pasteData.removeRecord(0);
917
```
Z
zengyawen 已提交
918

919
### replaceRecord<sup>9+</sup>
Z
zengyawen 已提交
920

921
replaceRecord(index: number, record: PasteDataRecord): void
Z
zengyawen 已提交
922

923
替换剪贴板内容中指定下标的条目。
924 925

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

927
**参数:**
Z
zengyawen 已提交
928

Z
zengyawen 已提交
929 930 931
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定的下标。 |
932
| record | [PasteDataRecord](#pastedatarecord7) | 是 | 新条目的内容。 |
Z
zengyawen 已提交
933

934
**错误码:**
935

936
以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)
937
| 错误码ID | 错误信息 |
938
| -------- | -------- |
939
| 12900001 | The index is out of range. |
940

941
**示例:**
Z
zengyawen 已提交
942

943
```js
944 945
let pasteData = pasteboard.createPlainTextData('hello');
let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');
946
pasteData.replaceRecord(0, record);
947
```
948
### addHtmlRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
949

950
addHtmlRecord(htmlText: string): void
951

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

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

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

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
965
| htmlText | string | 是 | HTML内容。 |
966 967 968 969

**示例:**

```js
970 971
let pasteData = pasteboard.createPlainTextData('hello');
let 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>";
972
pasteData.addHtmlRecord(html);
973
```
Z
zengyawen 已提交
974

975
### addWantRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
976

977
addWantRecord(want: Want): void
Z
zengyawen 已提交
978

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

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

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

988
**参数:**
Z
zengyawen 已提交
989

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

994
**示例:**
Z
zengyawen 已提交
995

996
```js
997 998
let pasteData = pasteboard.createPlainTextData('hello');
let object = { 
999 1000 1001 1002
    bundleName: "com.example.aafwk.test",    
    abilityName: "com.example.aafwk.test.TwoAbility"
};
pasteData.addWantRecord(object);
1003
```
Z
zengyawen 已提交
1004

1005
### addTextRecord<sup>(deprecated)</sup>
1006

1007
addTextRecord(text: string): void
1008

1009 1010 1011 1012 1013 1014
向当前剪贴板内容中添加一条纯文本条目,并将MIME_TEXT_PLAIN添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空,否则添加失败。

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

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

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1022
| text | string | 是 | 纯文本内容。 |
1023 1024 1025 1026

**示例:**

```js
1027 1028
let pasteData = pasteboard.createPlainTextData('hello');
pasteData.addTextRecord('good');
Z
zengyawen 已提交
1029 1030
```

1031
### addUriRecord<sup>(deprecated)</sup>
Z
zengyawen 已提交
1032

1033
addUriRecord(uri: string): void
Z
zengyawen 已提交
1034

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

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

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

1044
**参数:**
Z
zengyawen 已提交
1045

Z
zengyawen 已提交
1046 1047
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1048
| uri | string | 是 | URI内容。 |
Z
zengyawen 已提交
1049

1050
**示例:**
Z
zengyawen 已提交
1051

1052
```js
1053 1054
let pasteData = pasteboard.createPlainTextData('hello');
pasteData.addUriRecord('dataability:///com.example.myapplication1/user.txt');
1055
```
1056
### getRecordAt<sup>(deprecated)</sup>
Z
zengyawen 已提交
1057

1058
getRecordAt(index: number): PasteDataRecord
Z
zengyawen 已提交
1059

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

1065 1066 1067
**系统能力:** SystemCapability.MiscServices.Pasteboard

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

1069 1070 1071
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定条目的下标。 |
Z
zengyawen 已提交
1072

1073 1074
**返回值:**

Z
zengyawen 已提交
1075 1076
| 类型 | 说明 |
| -------- | -------- |
1077
| [PasteDataRecord](#pastedatarecord7) | 指定下标的条目。 |
Z
zengyawen 已提交
1078

1079
**示例:**
Z
zengyawen 已提交
1080

1081
```js
1082 1083
let pasteData = pasteboard.createPlainTextData('hello');
let record = pasteData.getRecordAt(0);
1084
```
Z
zengyawen 已提交
1085

1086
### hasMimeType<sup>(deprecated)</sup>
1087

1088
hasMimeType(mimeType: string): boolean
1089

1090 1091 1092 1093
检查剪贴板内容中是否有指定的数据类型。
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[hasType](#hastype9)替代。
1094 1095 1096 1097 1098 1099 1100

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

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1101 1102 1103 1104 1105 1106 1107
| mimeType | string | 是 | 待查询的数据类型。 |

**返回值:**

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

**示例:**

```js
1112 1113
let pasteData = pasteboard.createPlainTextData('hello');
let hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);
1114
```
1115
### removeRecordAt<sup>(deprecated)</sup>
1116

1117
removeRecordAt(index: number): boolean
1118

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

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

1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140
**参数:**

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

**返回值:**

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

**示例:**

```js
1141 1142
let pasteData = pasteboard.createPlainTextData('hello');
let isRemove = pasteData.removeRecordAt(0);
1143 1144 1145 1146 1147 1148 1149 1150 1151
```
### replaceRecordAt<sup>(deprecated)</sup>

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

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

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

**参数:**

1157 1158 1159 1160
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| index | number | 是 | 指定的下标。 |
| record | [PasteDataRecord](#pastedatarecord7) | 是 | 替换后的条目。 |
1161 1162 1163 1164 1165

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
1166
| boolean | 成功替换返回true,失败返回false。 |
1167 1168 1169 1170

**示例:**

```js
1171 1172 1173
let pasteData = pasteboard.createPlainTextData('hello');
let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');
let isReplace = pasteData.replaceRecordAt(0, record);
1174 1175 1176 1177 1178 1179 1180 1181 1182
```

## SystemPasteboard

系统剪贴板对象。

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

```js
1183
let systemPasteboard = pasteboard.getSystemPasteboard();
1184
```
Z
zengyawen 已提交
1185

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

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

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

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

1194
**参数:**
Z
zengyawen 已提交
1195

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

1201
**示例:**
Z
zengyawen 已提交
1202

1203
```js
1204 1205
let systemPasteboard = pasteboard.getSystemPasteboard();
let listener = () => {
1206 1207 1208
    console.info('The system pasteboard has changed.');
};
systemPasteboard.on('update', listener);
1209
```
Z
zengyawen 已提交
1210

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

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

1215
取消订阅系统剪贴板内容变化事件。
1216 1217

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

1219
**参数:**
Z
zengyawen 已提交
1220

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

1226
**示例:**
Z
zengyawen 已提交
1227

1228
```js
1229 1230
let listener = () => {
    console.info('The system pasteboard has changed.');
1231
};
1232
systemPasteboard.off('update', listener);
1233
```
Z
zengyawen 已提交
1234

1235
### clearData<sup>9+</sup>
1236

1237
clearData(callback: AsyncCallback&lt;void&gt;): void
1238

1239
清空系统剪贴板内容,使用callback异步回调。
1240 1241 1242 1243 1244 1245 1246

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

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1247
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当成功清空时,err为undefined;否则为错误对象。 |
1248 1249 1250 1251

**示例:**

```js
1252
systemPasteboard.clearData((err, data) => { 
1253
    if (err) {
1254
        console.error(`Failed to clear the pasteboard. Cause: ${err.message}`);
1255
        return;
1256
    }
1257
    console.info('Succeeded in clearing the pasteboard.');
1258 1259 1260
});
```

1261
### clearData<sup>9+</sup>
1262

1263
clearData(): Promise&lt;void&gt;
1264

1265
清空系统剪贴板内容,使用Promise异步回调。
1266 1267 1268 1269 1270 1271 1272

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

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
1273
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
1274 1275 1276 1277

**示例:**

```js
1278 1279
systemPasteboard.clearData().then((data) => { 
    console.info('Succeeded in clearing the pasteboard.');
1280 1281
}).catch((err) => {
    console.error(`Failed to clear the pasteboard. Cause: ${err.message}`);
1282
});
1283
```
Z
zengyawen 已提交
1284

1285
### setData<sup>9+</sup>
Z
zengyawen 已提交
1286

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

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

1291 1292 1293
**系统能力:** SystemCapability.MiscServices.Pasteboard

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

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

1300
**错误码:**
1301

1302
以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)
1303
| 错误码ID | 错误信息 |
1304
| -------- | -------- |
1305
| 12900003 | Another copy or paste is in progress. |
1306
| 12900004 | Replication is prohibited. |
1307

1308
**示例:**
Z
zengyawen 已提交
1309

1310
```js
1311 1312
let pasteData = pasteboard.createPlainTextData('content');
let systemPasteboard = pasteboard.getSystemPasteboard();
1313 1314 1315 1316 1317 1318 1319
systemPasteboard.setData(pasteData, (err, data) => { 
    if (err) {
        console.error('Failed to set PasteData. Cause: ' + err.message);
        return;
    }
    console.info('Succeeded in setting PasteData.');
});
1320
```
Z
zengyawen 已提交
1321

1322
### setData<sup>9+</sup>
Z
zengyawen 已提交
1323

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

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

1328 1329 1330
**系统能力:** SystemCapability.MiscServices.Pasteboard

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

1332 1333 1334 1335 1336 1337 1338 1339 1340
| 参数名 | 类型 | 说明 |
| -------- | -------- | -------- |
| data | [PasteData](#pastedata) | PasteData对象。 |

**返回值:**

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

1342
**错误码:**
1343

1344
以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)
1345
| 错误码ID | 错误信息 |
1346
| -------- | -------- |
1347
| 12900003 | Another copy or paste is in progress. |
1348
| 12900004 | Replication is prohibited. |
1349

1350
**示例:**
Z
zengyawen 已提交
1351

1352
```js
1353 1354
let pasteData = pasteboard.createPlainTextData('content');
let systemPasteboard = pasteboard.getSystemPasteboard();
1355 1356 1357 1358 1359
systemPasteboard.setData(pasteData).then((data) => {
    console.info('Succeeded in setting PasteData.');
}).catch((err) => {
    console.error('Failed to set PasteData. Cause: ' + err.message);
});
1360
```
Z
zengyawen 已提交
1361

1362
### getData<sup>9+</sup>
Z
zengyawen 已提交
1363

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

1366
读取系统剪贴板内容,使用callback异步回调。
1367 1368

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

1370
**参数:**
Z
zengyawen 已提交
1371

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

1376
**错误码:**
1377

1378
以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)
1379
| 错误码ID | 错误信息 |
1380
| -------- | -------- |
1381
| 12900003 | Another copy or paste is in progress. |
1382

1383 1384 1385
**示例:**

```js
1386
let systemPasteboard = pasteboard.getSystemPasteboard();
1387
systemPasteboard.getData((err, pasteData) => {  
1388
    if (err) {
1389
        console.error('Failed to get PasteData. Cause: ' + err.message);
1390 1391
        return;
    }
1392
    let text = pasteData.getPrimaryText();
1393 1394
});
```
Z
zengyawen 已提交
1395

1396
### getData<sup>9+</sup>
Z
zengyawen 已提交
1397

1398
getData(): Promise&lt;PasteData&gt;
Z
zengyawen 已提交
1399

1400
读取系统剪贴板内容,使用Promise异步回调。
1401 1402

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

1404
**返回值:**
Z
zengyawen 已提交
1405

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

1410
**错误码:**
1411

1412
以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)
1413
| 错误码ID | 错误信息 |
1414
| -------- | -------- |
1415
| 12900003 | Another copy or paste is in progress. |
1416

1417
**示例:**
Z
zengyawen 已提交
1418

1419
```js
1420
let systemPasteboard = pasteboard.getSystemPasteboard();
1421
systemPasteboard.getData().then((pasteData) => { 
1422
    let text = pasteData.getPrimaryText();
1423
}).catch((err) => {
1424 1425
    console.error('Failed to get PasteData. Cause: ' + err.message);
})
1426
```
Z
zengyawen 已提交
1427

1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446
### 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) {
1447
        console.error(`Failed to check the PasteData. Cause: ${err.message}`);
1448 1449
        return;
    }
1450
    console.info(`Succeeded in checking the PasteData. Data: ${data}`);
1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471
});
```

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

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

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

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

**返回值:**

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

**示例:**

```js
systemPasteboard.hasData().then((data) => { 
1472
    console.info(`Succeeded in checking the PasteData. Data: ${data}`);
1473
}).catch((err) => {
1474
    console.error(`Failed to check the PasteData. Cause: ${err.message}`);
1475 1476
});
```
Z
zengyawen 已提交
1477

1478
### clear<sup>(deprecated)</sup>
Z
zengyawen 已提交
1479

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

1482
清空系统剪贴板内容,使用callback异步回调。
1483 1484 1485
> **说明:**
>
> 从 API Version 7 开始支持,从 API Version 9 开始废弃,建议使用[pasteboard.clearData](#cleardata9)替代。
1486 1487

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

1489
**参数:**
Z
zengyawen 已提交
1490

Z
zengyawen 已提交
1491 1492
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
1493 1494 1495 1496 1497 1498 1499
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当成功清空时,err为undefined;否则为错误对象。 |

**示例:**

```js
systemPasteboard.clear((err, data) => { 
    if (err) {        
1500
        console.error(`Failed to clear the PasteData. Cause: ${err.message}`);
1501
        return;
1502 1503 1504 1505
    }
    console.info('Succeeded in clearing the PasteData.');
});
```
Z
zengyawen 已提交
1506

1507
### clear<sup>(deprecated)</sup>
Z
zengyawen 已提交
1508

1509
clear(): Promise&lt;void&gt;
Z
zengyawen 已提交
1510

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

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

1518
**返回值:**
Z
zengyawen 已提交
1519

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

1524
**示例:**
Z
zengyawen 已提交
1525

1526 1527 1528 1529
```js
systemPasteboard.clear().then((data) => { 
    console.info('Succeeded in clearing the PasteData.');
}).catch((err) => {    
1530
    console.error(`Failed to clear the PasteData. Cause: ${err.message}`);
1531
});
1532 1533
```

1534
### getPasteData<sup>(deprecated)</sup>
1535

1536
getPasteData( callback: AsyncCallback&lt;PasteData&gt;): void
1537

1538 1539 1540 1541
读取系统剪贴板内容,使用callback异步回调。
> **说明:**
>
> 从 API Version 6 开始支持,从 API Version 9 开始废弃,建议使用[getData](#getdata9)替代。
1542 1543 1544 1545 1546 1547 1548

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

**参数:**

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

**示例:**

```js
1554 1555
let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData((err, pasteData) => {
1556 1557 1558
    if (err) {
        console.error('Failed to get PasteData. Cause: ' + err.message);
        return;
1559
    }
1560
    let text = pasteData.getPrimaryText();
1561 1562 1563
});
```

1564
### getPasteData<sup>(deprecated)</sup>
1565

1566
getPasteData(): Promise&lt;PasteData&gt;
1567

1568 1569 1570 1571
读取系统剪贴板内容,使用Promise异步回调。
> **说明:**
>
> 从 API Version 6 开始支持,从 API Version 9 开始废弃,建议使用[getData](#getdata9-1)替代。
1572 1573 1574 1575 1576

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

**返回值:**

1577 1578 1579 1580 1581 1582 1583
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[PasteData](#pastedata)&gt; | Promise对象,返回系统剪贴板数据。 |

**示例:**

```js
1584
let systemPasteboard = pasteboard.getSystemPasteboard();
1585
systemPasteboard.getPasteData().then((pasteData) => { 
1586
    let text = pasteData.getPrimaryText();
1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599
}).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)替代。
1600

1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

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

**示例:**

```js
systemPasteboard.hasPasteData((err, data) => {
    if (err) {
1614
        console.error(`Failed to check the PasteData. Cause: ${err.message}`);
1615 1616
        return;
    }
1617
    console.info(`Succeeded in checking the PasteData. Data: ${data}`);
1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628
});
```

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

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

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

1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641
**系统能力:** SystemCapability.MiscServices.Pasteboard

**返回值:**

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

**示例:**

```js
systemPasteboard.hasPasteData().then((data) => { 
1642
    console.info(`Succeeded in checking the PasteData. Data: ${data}`);
1643
}).catch((err) => {
1644
    console.error(`Failed to check the PasteData. Cause: ${err.message}`);
1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655
});
```

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

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

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

1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

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

**示例:**

```js
1669 1670
let pasteData = pasteboard.createPlainTextData('content');
let systemPasteboard = pasteboard.getSystemPasteboard();
1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686
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)替代。
1687

1688 1689 1690 1691 1692 1693 1694 1695 1696 1697
**系统能力:** SystemCapability.MiscServices.Pasteboard

**参数:**

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

**返回值:**

1698 1699 1700 1701 1702 1703 1704
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |

**示例:**

```js
1705 1706
let pasteData = pasteboard.createPlainTextData('content');
let systemPasteboard = pasteboard.getSystemPasteboard();
1707 1708 1709 1710
systemPasteboard.setPasteData(pasteData).then((data) => {
    console.info('Succeeded in setting PasteData.');
}).catch((err) => {
    console.error('Failed to set PasteData. Cause: ' + err.message);
1711
});
1712
```