1/* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15import type { AsyncCallback } from './basic'; 16import type Want from './@ohos.app.ability.Want'; 17import type image from './@ohos.multimedia.image'; 18 19/** 20 * systemPasteboard 21 * @syscap SystemCapability.MiscServices.Pasteboard 22 */ 23declare namespace pasteboard { 24 /** 25 * Indicates the maximum number of records allowed in a PasteData object. 26 * @since 7 27 */ 28 const MAX_RECORD_NUM: number; 29 /** 30 * Indicates MIME types of HTML text. 31 * @since 7 32 */ 33 const MIMETYPE_TEXT_HTML: string; 34 /** 35 * Indicates MIME types of wants. 36 * @since 7 37 */ 38 const MIMETYPE_TEXT_WANT: string; 39 /** 40 * Indicates MIME types of plain text. 41 * @since 7 42 */ 43 const MIMETYPE_TEXT_PLAIN: string; 44 /** 45 * Indicates MIME types of URIs. 46 * @since 7 47 */ 48 const MIMETYPE_TEXT_URI: string; 49 /** 50 * Indicates MIME type of PixelMap. 51 * @syscap SystemCapability.MiscServices.Pasteboard 52 * @since 9 53 */ 54 const MIMETYPE_PIXELMAP: string; 55 56 /** 57 * Indicates type of value. 58 * @syscap SystemCapability.MiscServices.Pasteboard 59 * @since 9 60 */ 61 type ValueType = string | image.PixelMap | Want | ArrayBuffer; 62 63 /** 64 * Creates a PasteData object for PasteData#MIMETYPE_TEXT_HTML. 65 * @param htmlText To save the Html text content. 66 * @returns Containing the contents of the clipboard content object. 67 * @since 7 68 * @deprecated since 9 69 * @useinstead ohos.pasteboard.pasteboard#createData 70 */ 71 function createHtmlData(htmlText: string): PasteData; 72 73 /** 74 * Creates a PasteData object for PasteData#MIMETYPE_TEXT_WANT. 75 * @param want To save the want of content. 76 * @returns Containing the contents of the clipboard content object. 77 * @since 7 78 * @deprecated since 9 79 * @useinstead ohos.pasteboard.pasteboard#createData 80 */ 81 function createWantData(want: Want): PasteData; 82 83 /** 84 * Creates a PasteData object for PasteData#MIMETYPE_TEXT_PLAIN. 85 * @param text To save the text of content. 86 * @returns Containing the contents of the clipboard content object. 87 * @since 6 88 * @deprecated since 9 89 * @useinstead ohos.pasteboard.pasteboard#createData 90 */ 91 function createPlainTextData(text: string): PasteData; 92 93 /** 94 * Creates a PasteData object for PasteData#MIMETYPE_TEXT_URI. 95 * @param uri To save the uri of content. 96 * @returns Containing the contents of the clipboard content object. 97 * @since 7 98 * @deprecated since 9 99 * @useinstead ohos.pasteboard.pasteboard#createData 100 */ 101 function createUriData(uri: string): PasteData; 102 103 /** 104 * Creates a PasteData object with MIME type and value. 105 * @param { string } mimeType - indicates MIME type of value. 106 * @param { ValueType } value - indicates the content that is set to PasteData. 107 * @returns { PasteData } a new PasteData object which contains mimeType and value. 108 * @throws { BusinessError } 401 - if type of mimeType is not string, or the value can not match the mimeType correctly. 109 * @syscap SystemCapability.MiscServices.Pasteboard 110 * @since 9 111 */ 112 function createData(mimeType: string, value: ValueType): PasteData; 113 114 /** 115 * Creates a Record object for PasteData#MIMETYPE_TEXT_HTML. 116 * @param htmlText To save the Html text content. 117 * @returns The content of a new record 118 * @since 7 119 * @deprecated since 9 120 * @useinstead ohos.pasteboard.pasteboard#createRecord 121 */ 122 function createHtmlTextRecord(htmlText: string): PasteDataRecord; 123 124 /** 125 * Creates a Record object for PasteData#MIMETYPE_TEXT_WANT. 126 * @param want To save the want of content. 127 * @returns The content of a new record 128 * @since 7 129 * @deprecated since 9 130 * @useinstead ohos.pasteboard.pasteboard#createRecord 131 */ 132 function createWantRecord(want: Want): PasteDataRecord; 133 134 /** 135 * Creates a Record object for PasteData#MIMETYPE_TEXT_PLAIN. 136 * @param text To save the text of content. 137 * @returns The content of a new record 138 * @since 7 139 * @deprecated since 9 140 * @useinstead ohos.pasteboard.pasteboard#createRecord 141 */ 142 function createPlainTextRecord(text: string): PasteDataRecord; 143 144 /** 145 * Creates a Record object for PasteData#MIMETYPE_TEXT_URI. 146 * @param uri To save the uri of content. 147 * @returns The content of a new record 148 * @since 7 149 * @deprecated since 9 150 * @useinstead ohos.pasteboard.pasteboard#createRecord 151 */ 152 function createUriRecord(uri: string): PasteDataRecord; 153 154 /** 155 * Creates a record object with MIME type and value. 156 * @param { string } mimeType - indicates MIME type of value. 157 * @param { ValueType } value - content to be saved. 158 * @returns { PasteDataRecord } a new PasteDataRecord object which contains mimeType and value. 159 * @throws { BusinessError } 401 - if type of mimeType is not string, or the value can not match the mimeType correctly. 160 * @syscap SystemCapability.MiscServices.Pasteboard 161 * @since 9 162 */ 163 function createRecord(mimeType: string, value: ValueType): PasteDataRecord; 164 165 /** 166 * get SystemPasteboard 167 * @returns The system clipboard object 168 * @since 6 169 */ 170 function getSystemPasteboard(): SystemPasteboard; 171 172 /** 173 * Types of scope that PasteData can be pasted. 174 * @enum { number } 175 * @syscap SystemCapability.MiscServices.Pasteboard 176 * @since 9 177 */ 178 enum ShareOption { 179 /** 180 * INAPP indicates that only paste in the same app is allowed. 181 * @syscap SystemCapability.MiscServices.Pasteboard 182 * @since 9 183 */ 184 INAPP, 185 /** 186 * LOCALDEVICE indicates that paste in any app in this device is allowed. 187 * @syscap SystemCapability.MiscServices.Pasteboard 188 * @since 9 189 */ 190 LOCALDEVICE, 191 /** 192 * CROSSDEVICE indicates that paste in any app across devices is allowed. 193 * @syscap SystemCapability.MiscServices.Pasteboard 194 * @since 9 195 */ 196 CROSSDEVICE, 197 } 198 199 interface PasteDataProperty { 200 /** 201 * additional property data. key-value pairs. 202 * @since 7 203 */ 204 additions: { 205 [key: string]: object; 206 }; 207 /** 208 * non-repeating MIME types of all records in PasteData. 209 * @since 7 210 */ 211 readonly mimeTypes: Array<string>; 212 /** 213 * the user-defined tag of a PasteData object. 214 * @since 7 215 */ 216 tag: string; 217 /** 218 * a timestamp, which indicates when data is written to the system pasteboard. 219 * @since 7 220 */ 221 readonly timestamp: number; 222 /** 223 * Checks whether PasteData is set for local access only. 224 * @since 7 225 */ 226 localOnly: boolean; 227 /** 228 * Indicates the scope of clipboard data which can be pasted. 229 * If it is not set or is incorrectly set, The default value is CrossDevice. 230 * @type { ShareOption } 231 * @syscap SystemCapability.MiscServices.Pasteboard 232 * @since 9 233 */ 234 shareOption: ShareOption; 235 } 236 237 interface PasteDataRecord { 238 /** 239 * HTML text in a record. 240 * @since 7 241 */ 242 htmlText: string; 243 /** 244 * an want in a record. 245 * @since 7 246 */ 247 want: Want; 248 /** 249 * MIME types of a record. 250 * @since 7 251 */ 252 mimeType: string; 253 /** 254 * plain text in a record. 255 * @since 7 256 */ 257 plainText: string; 258 /** 259 * an URI in a record. 260 * @since 7 261 */ 262 uri: string; 263 /** 264 * PixelMap in a record. 265 * @type { image.PixelMap } 266 * @syscap SystemCapability.MiscServices.Pasteboard 267 * @since 9 268 */ 269 pixelMap: image.PixelMap; 270 /** 271 * Custom data in a record, mimeType indicates the MIME type of custom data, ArrayBuffer indicates the value of custom data. 272 * @type { object } 273 * @syscap SystemCapability.MiscServices.Pasteboard 274 * @since 9 275 */ 276 data: { 277 [mimeType: string]: ArrayBuffer; 278 }; 279 280 /** 281 * Converts data in PasteData to text format. 282 * @returns callback Type string callback function 283 * @since 7 284 * @deprecated since 9 285 * @useinstead ohos.pasteboard.pasteboard#convertToTextV9 286 */ 287 convertToText(callback: AsyncCallback<string>): void; 288 convertToText(): Promise<string>; 289 290 /** 291 * Converts data in PasteData to text format. 292 * @returns { string } the string returned by the function. 293 * @syscap SystemCapability.MiscServices.Pasteboard 294 * @since 9 295 */ 296 toPlainText(): string; 297 } 298 299 interface PasteData { 300 /** 301 * Adds a Record for HTML text to a PasteData object, and updates the MIME type to PasteData#MIMETYPE_TEXT_HTML in DataProperty. 302 * @param htmlText To save the Html text content. 303 * @since 7 304 * @deprecated since 9 305 * @useinstead ohos.pasteboard.pasteboard#addRecord 306 */ 307 addHtmlRecord(htmlText: string): void; 308 309 /** 310 * Adds an want Record to a PasteData object, and updates the MIME type to PasteData#MIMETYPE_TEXT_WANT in DataProperty. 311 * @param want To save the want content. 312 * @since 7 313 * @deprecated since 9 314 * @useinstead ohos.pasteboard.pasteboard#addRecord 315 */ 316 addWantRecord(want: Want): void; 317 318 /** 319 * Adds a PasteRecord to a PasteData object and updates MIME types in DataProperty. 320 * @param record The content of a new record. 321 * @since 7 322 */ 323 addRecord(record: PasteDataRecord): void; 324 325 /** 326 * Adds a Record for plain text to a PasteData object, and updates the MIME type to PasteData#MIMETYPE_TEXT_PLAIN in DataProperty. 327 * @param text To save the text of content. 328 * @since 7 329 * @deprecated since 9 330 * @useinstead ohos.pasteboard.pasteboard#addRecord 331 */ 332 addTextRecord(text: string): void; 333 334 /** 335 * Adds a URI Record to a PasteData object, and updates the MIME type to PasteData#MIMETYPE_TEXT_URI in DataProperty. 336 * @param uri To save the uri of content. 337 * @since 7 338 * @deprecated since 9 339 * @useinstead ohos.pasteboard.pasteboard#addRecord 340 */ 341 addUriRecord(uri: string): void; 342 343 /** 344 * Adds a record with mimeType and value to a PasteData object. 345 * @param { string } mimeType - indicates the MIME type of value. 346 * @param { ValueType } value - content to be saved. 347 * @throws { BusinessError } 401 - if type of mimeType is not string, or the value can not match the mimeType correctly. 348 * @throws { BusinessError } 12900002 - The number of record exceeds the maximum limit. 349 * @syscap SystemCapability.MiscServices.Pasteboard 350 * @since 9 351 */ 352 addRecord(mimeType: string, value: ValueType): void; 353 354 /** 355 * MIME types of all content on the pasteboard. 356 * @returns string type of array 357 * @since 7 358 */ 359 getMimeTypes(): Array<string>; 360 361 /** 362 * HTML text of the primary record in a PasteData object. 363 * @returns string type of htmltext 364 * @since 7 365 */ 366 getPrimaryHtml(): string; 367 368 /** 369 * the want of the primary record in a PasteData object. 370 * @returns want type of want 371 * @since 7 372 */ 373 getPrimaryWant(): Want; 374 375 /** 376 * the MIME type of the primary record in a PasteData object. 377 * @returns string type of mimetype 378 * @since 7 379 */ 380 getPrimaryMimeType(): string; 381 382 /** 383 * the plain text of the primary record in a PasteData object. 384 * @returns string type of text 385 * @since 6 386 */ 387 getPrimaryText(): string; 388 389 /** 390 * the URI of the primary record in a PasteData object. 391 * @returns string type of uri 392 * @since 7 393 */ 394 getPrimaryUri(): string; 395 396 /** 397 * Gets the primary PixelMap record in a PasteData object. 398 * @returns {image.PixelMap} pixelMap 399 * @syscap SystemCapability.MiscServices.Pasteboard 400 * @since 9 401 */ 402 getPrimaryPixelMap(): image.PixelMap; 403 404 /** 405 * DataProperty of a PasteData object. 406 * @returns PasteDataProperty type of PasteDataProperty 407 * @since 7 408 */ 409 getProperty(): PasteDataProperty; 410 411 /** 412 * Sets PasteDataProperty to a PasteData object, Modifying shareOption is supported only. 413 * @param { PasteDataProperty } property - save property to PasteData object. 414 * @throws { BusinessError } 401 - if type of property is not PasteDataProperty. 415 * @syscap SystemCapability.MiscServices.Pasteboard 416 * @since 9 417 */ 418 setProperty(property: PasteDataProperty): void; 419 420 /** 421 * a Record based on a specified index. 422 * @param index The index to specify the content item 423 * @returns PasteDataRecord type of PasteDataRecord 424 * @since 7 425 * @deprecated since 9 426 * @useinstead ohos.pasteboard.pasteboard#getRecord 427 */ 428 getRecordAt(index: number): PasteDataRecord; 429 430 /** 431 * Gets record by index in PasteData. 432 * @param { number } index - indicates the record index in PasteData. 433 * @returns { PasteDataRecord } the record in PasteData with index. 434 * @throws { BusinessError } 401 - if type of index is not number. 435 * @throws { BusinessError } 12900001 - The index is out of the record. 436 * @syscap SystemCapability.MiscServices.Pasteboard 437 * @since 9 438 */ 439 getRecord(index: number): PasteDataRecord; 440 441 /** 442 * the number of records in a PasteData object. 443 * @returns The number of the clipboard contents 444 * @since 7 445 */ 446 getRecordCount(): number; 447 448 /** 449 * the user-defined tag of a PasteData object. 450 * @returns string type of tag 451 * @since 7 452 */ 453 getTag(): string; 454 455 /** 456 * Checks whether there is a specified MIME type of data in DataProperty. 457 * @param mimeType To query data types. 458 * @returns if having mimeType in PasteData returns true, else returns false. 459 * @since 7 460 * @deprecated since 9 461 * @useinstead ohos.pasteboard.pasteboard#hasType 462 */ 463 hasMimeType(mimeType: string): boolean; 464 465 /** 466 * Checks whether there is a specified MIME type of data in DataProperty. 467 * @param { string } mimeType - indicates to query data type. 468 * @returns { boolean } if having mimeType in PasteData returns true, else returns false. 469 * @throws { BusinessError } 401 - if type of path is not string. 470 * @syscap SystemCapability.MiscServices.Pasteboard 471 * @since 9 472 */ 473 hasType(mimeType: string): boolean; 474 475 /** 476 * Removes a Record based on a specified index. 477 * @param index The index to specify the content item. 478 * @returns The query returns True on success, or False on failure. 479 * @since 7 480 * @deprecated since 9 481 * @useinstead ohos.pasteboard.pasteboard#removeRecord 482 */ 483 removeRecordAt(index: number): boolean; 484 485 /** 486 * Removes a Record based on a specified index. 487 * @param { number } index - indicates the record index in PasteData. 488 * @throws { BusinessError } 401 - if type of index is not number. 489 * @throws { BusinessError } 12900001 - The index is out of the record. 490 * @syscap SystemCapability.MiscServices.Pasteboard 491 * @since 9 492 */ 493 removeRecord(index: number): void; 494 495 /** 496 * Replaces a specified record with a new one. 497 * @param index The index to specify the content item. record record The content of a new record. 498 * @returns The query returns True on success, or False on failure. 499 * @since 7 500 * @deprecated since 9 501 * @useinstead ohos.pasteboard.pasteboard#replaceRecord 502 */ 503 replaceRecordAt(index: number, record: PasteDataRecord): boolean; 504 505 /** 506 * Replaces a specified record with a new one. 507 * @param { number } index - indicates the record index in PasteData. 508 * @param { PasteDataRecord } record - the content of a new record. 509 * @throws { BusinessError } 401 - if type of index is not number or type of record is not PasteDataRecord. 510 * @throws { BusinessError } 12900001 - The index is out of the record. 511 * @syscap SystemCapability.MiscServices.Pasteboard 512 * @since 9 513 */ 514 replaceRecord(index: number, record: PasteDataRecord): void; 515 } 516 517 interface SystemPasteboard { 518 /** 519 * Callback invoked when pasteboard content changes. 520 * @param { string } type - indicates pasteboard content changed. 521 * @param { () => void } callback - the callback to add. 522 * @throws { BusinessError } 401 - if type is not string or callback is not () => void. 523 * @since 7 524 */ 525 on(type: 'update', callback: () => void): void; 526 /** 527 * Remove a callback invoked when pasteboard content changes. 528 * @param { string } type - indicates pasteboard content changed. 529 * @param { () => void } [callback] - the callback to remove. 530 * @throws { BusinessError } 401 - if type is not string or callback is not () => void. 531 * @since 7 532 */ 533 off(type: 'update', callback?: () => void): void; 534 535 /** 536 * Clears the pasteboard. 537 * @since 7 538 * @deprecated since 9 539 * @useinstead ohos.pasteboard.pasteboard#clearData 540 */ 541 clear(callback: AsyncCallback<void>): void; 542 clear(): Promise<void>; 543 544 /** 545 * Clears the pasteboard. 546 * @param { AsyncCallback<void> } callback - the callback of clearData. 547 * @throws { BusinessError } 401 - if callback is not AsyncCallback<void>. 548 * @syscap SystemCapability.MiscServices.Pasteboard 549 * @since 9 550 */ 551 clearData(callback: AsyncCallback<void>): void; 552 553 /** 554 * Clears the pasteboard. 555 * @returns { Promise<void> } the promise returned by the clearData. 556 * @syscap SystemCapability.MiscServices.Pasteboard 557 * @since 9 558 */ 559 clearData(): Promise<void>; 560 561 /** 562 * data in a PasteData object. 563 * @returns PasteData callback data in a PasteData object. 564 * @since 6 565 * @deprecated since 9 566 * @useinstead ohos.pasteboard.pasteboard#getData 567 */ 568 getPasteData(callback: AsyncCallback<PasteData>): void; 569 getPasteData(): Promise<PasteData>; 570 571 /** 572 * Gets pastedata from the system pasteboard. 573 * @param { AsyncCallback<PasteData> } callback - the callback of getData. 574 * @throws { BusinessError } 401 - if type of callback is not AsyncCallback<PasteData>. 575 * @throws { BusinessError } 12900003 - Another copy or paste is in progress. 576 * @syscap SystemCapability.MiscServices.Pasteboard 577 * @since 9 578 */ 579 getData(callback: AsyncCallback<PasteData>): void; 580 581 /** 582 * Gets pastedata from the system pasteboard. 583 * @returns { Promise<PasteData> } the promise returned by the getData. 584 * @throws { BusinessError } 12900003 - Another copy or paste is in progress. 585 * @syscap SystemCapability.MiscServices.Pasteboard 586 * @since 9 587 */ 588 getData(): Promise<PasteData>; 589 590 /** 591 * Checks whether there is content in the pasteboard. 592 * @returns boolean The callback success to true to false failure 593 * @since 7 594 * @deprecated since 9 595 * @useinstead ohos.pasteboard.pasteboard#hasData 596 */ 597 hasPasteData(callback: AsyncCallback<boolean>): void; 598 hasPasteData(): Promise<boolean>; 599 600 /** 601 * Checks whether there is content in the system pasteboard. 602 * @param { AsyncCallback<boolean> } callback - the callback of hasData. 603 * @throws { BusinessError } 401 - if type of callback is not AsyncCallback<boolean>. 604 * @syscap SystemCapability.MiscServices.Pasteboard 605 * @since 9 606 */ 607 hasData(callback: AsyncCallback<boolean>): void; 608 609 /** 610 * Checks whether there is content in the system pasteboard. 611 * @returns { Promise<boolean> } the promise returned by the function. 612 * @syscap SystemCapability.MiscServices.Pasteboard 613 * @since 9 614 */ 615 hasData(): Promise<boolean>; 616 617 /** 618 * Writes PasteData to the pasteboard. 619 * @param data Containing the contents of the clipboard content object. 620 * @since 6 621 * @deprecated since 9 622 * @useinstead ohos.pasteboard.pasteboard#setData 623 */ 624 setPasteData(data: PasteData, callback: AsyncCallback<void>): void; 625 setPasteData(data: PasteData): Promise<void>; 626 627 /** 628 * Writes PasteData to the system pasteboard. 629 * @param { PasteData } data - PasteData will be written to the clipboard 630 * @param { AsyncCallback<void> } callback - the callback of setData. 631 * @throws { BusinessError } 401 - if type of data is not PasteData or type of callback is not AsyncCallback<void>. 632 * @throws { BusinessError } 12900003 - Another copy or paste is in progress. 633 * @throws { BusinessError } 12900004 - Replication is prohibited. 634 * @syscap SystemCapability.MiscServices.Pasteboard 635 * @since 9 636 */ 637 setData(data: PasteData, callback: AsyncCallback<void>): void; 638 639 /** 640 * Writes PasteData to the system pasteboard. 641 * @param { PasteData } data - PasteData will be written to the clipboard. 642 * @returns { Promise<void> } the promise returned by the function. 643 * @throws { BusinessError } 401 - if type of data is not PasteData. 644 * @throws { BusinessError } 12900003 - Another copy or paste is in progress. 645 * @throws { BusinessError } 12900004 - Replication is prohibited. 646 * @syscap SystemCapability.MiscServices.Pasteboard 647 * @since 9 648 */ 649 setData(data: PasteData): Promise<void>; 650 } 651} 652 653export default pasteboard; 654