From 9b7908a916cbce78e3a66b40ff45e515d255c9d6 Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Wed, 14 Dec 2022 10:57:55 +0800 Subject: [PATCH] Add and update docs (11932) Signed-off-by: ester.zhou --- .../reference/apis/js-apis-pasteboard.md | 1372 +++++++++++------ .../errorcodes/errorcode-pasteboard.md | 75 + 2 files changed, 940 insertions(+), 507 deletions(-) create mode 100644 en/application-dev/reference/errorcodes/errorcode-pasteboard.md diff --git a/en/application-dev/reference/apis/js-apis-pasteboard.md b/en/application-dev/reference/apis/js-apis-pasteboard.md index be28e4b759..ee53667d01 100644 --- a/en/application-dev/reference/apis/js-apis-pasteboard.md +++ b/en/application-dev/reference/apis/js-apis-pasteboard.md @@ -12,25 +12,37 @@ The **pasteboard** module provides the copy and paste support for the system pas import pasteboard from '@ohos.pasteboard'; ``` -## Attributes +## Constants **System capability**: SystemCapability.MiscServices.Pasteboard -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| MAX_RECORD_NUM7+ | number | Yes| No| Maximum number of records in a **PasteData** object.| -| MIMETYPE_TEXT_HTML7+ | string | Yes| No| MIME type of the HTML content.| -| MIMETYPE_TEXT_WANT7+ | string | Yes| No| MIME type of the Want content.| -| MIMETYPE_TEXT_PLAIN7+ | string | Yes| No| MIME type of the plain text content.| -| MIMETYPE_TEXT_URI7+ | string | Yes| No| MIME type of the URI content.| -| MIMETYPE_PIXELMAP9+ | string | Yes| No| MIME type of the pixel map.| +| Name| Type| Value| Description| +| -------- | -------- | -------- | -------- | +| MAX_RECORD_NUM7+ | number | 512 | Maximum number of records in a **PasteData** object.| +| MIMETYPE_TEXT_HTML7+ | string | 'text/html' | MIME type of the HTML content.| +| MIMETYPE_TEXT_WANT7+ | string | 'text/want' | MIME type of the Want content.| +| MIMETYPE_TEXT_PLAIN7+ | string | 'text/plain' | MIME type of the plain text content.| +| MIMETYPE_TEXT_URI7+ | string | 'text/uri' | MIME type of the URI content.| +| MIMETYPE_PIXELMAP9+ | string | 'pixelMap' | MIME type of the pixel map.| +## ValueType9+ -## pasteboard.createPlainTextData +Enumerates the value types. -createPlainTextData(text: string): PasteData +**System capability**: SystemCapability.MiscServices.Pasteboard -Creates a **PasteData** object of the plain text type. +| Type| Description| +| -------- | -------- | +| string | The value is a string.| +| image.PixelMap | The value is of the [image.PixelMap](js-apis-image.md#pixelmap7) type.| +| Want | The value is of the [Want](js-apis-app-ability-want.md) type.| +| ArrayBuffer | The value is of the **ArrayBuffer** type.| + +## pasteboard.createData9+ + +createData(mimeType: string, value: ValueType): PasteData + +Creates a **PasteData** object of a custom type. **System capability**: SystemCapability.MiscServices.Pasteboard @@ -38,26 +50,27 @@ Creates a **PasteData** object of the plain text type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| text | string | Yes| Plain text.| +| mimeType | string | Yes| MIME type of custom data.| +| value | [ValueType](#valuetype9) | Yes| Content of custom data.| **Return value** | Type| Description| | -------- | -------- | -| [PasteData](#pastedata) | **PasteData** object.| +| [PasteData](#pastedata) | **PasteData** object.| **Example** -```js -var pasteData = pasteboard.createPlainTextData("content"); -``` - + ```js + let dataXml = new ArrayBuffer(256); + let pasteData = pasteboard.createData('app/xml', dataXml); + ``` -## pasteboard.createHtmlData7+ +## pasteboard.createRecord9+ -createHtmlData(htmlText: string): PasteData +createRecord(mimeType: string, value: ValueType):PasteDataRecord; -Creates a **PasteData** object of the HTML type. +Creates a **PasteDataRecord** object of the custom type. **System capability**: SystemCapability.MiscServices.Pasteboard @@ -65,58 +78,62 @@ Creates a **PasteData** object of the HTML type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| htmlText | string | Yes| HTML content.| +| mimeType | string | Yes| MIME type of custom data.| +| value | [ValueType](#valuetype9) | Yes| Content of custom data.| **Return value** | Type| Description| | -------- | -------- | -| [PasteData](#pastedata) | **PasteData** object.| +| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the custom type.| **Example** -```js -var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; -var pasteData = pasteboard.createHtmlData(html); -``` - + ```js + let dataXml = new ArrayBuffer(256); + let pasteDataRecord = pasteboard.createRecord('app/xml', dataXml); + ``` -## pasteboard.createWantData7+ +## pasteboard.getSystemPasteboard -createWantData(want: Want): PasteData +getSystemPasteboard(): SystemPasteboard -Creates a **PasteData** object of the Want type. +Obtains this **SystemPasteboard** object. **System capability**: SystemCapability.MiscServices.Pasteboard -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want content.| - **Return value** | Type| Description| | -------- | -------- | -| [PasteData](#pastedata) | **PasteData** object.| +| [SystemPasteboard](#systempasteboard) | **SystemPasteboard** object.| **Example** ```js -var object = { - bundleName: "com.example.aafwk.test", - abilityName: "com.example.aafwk.test.TwoAbility" -}; -var pasteData = pasteboard.createWantData(object); +let systemPasteboard = pasteboard.getSystemPasteboard(); ``` +## ShareOption9+ -## pasteboard.createUriData7+ +Enumerates the paste options of data. -createUriData(uri: string): PasteData +**System capability**: SystemCapability.MiscServices.Pasteboard -Creates a **PasteData** object of the URI type. +| Name | Description | +| ----- | ----------------------- | +| InApp |Only intra-application pasting is allowed.| +| LocalDevice |Paste is allowed in any application on the local device.| +| CrossDevice |Paste is allowed in any application across devices.| + +## pasteboard.createHtmlData(deprecated) + +createHtmlData(htmlText: string): PasteData + +Creates a **PasteData** object of the HTML type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -124,7 +141,7 @@ Creates a **PasteData** object of the URI type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| uri | string | Yes| URI content.| +| htmlText | string | Yes| HTML content.| **Return value** @@ -135,15 +152,18 @@ Creates a **PasteData** object of the URI type. **Example** ```js -var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt"); +let html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +let pasteData = pasteboard.createHtmlData(html); ``` +## pasteboard.createWantData(deprecated) -## pasteboard.createPixelMapData9+ - -createPixelMapData(pixelMap: image.PixelMap): PasteData +createWantData(want: Want): PasteData -Creates a **PasteData** object of the pixel map type. +Creates a **PasteData** object of the Want type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -151,7 +171,7 @@ Creates a **PasteData** object of the pixel map type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| pixelMap | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| Pixel map.| +| want | [Want](js-apis-app-ability-want.md) | Yes| Want content.| **Return value** @@ -162,26 +182,21 @@ Creates a **PasteData** object of the pixel map type. **Example** ```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); -}) +let object = { + bundleName: "com.example.aafwk.test", + abilityName: "com.example.aafwk.test.TwoAbility" +}; +let pasteData = pasteboard.createWantData(object); ``` -## pasteboard.createData9+ +## pasteboard.createPlainTextData(deprecated) -createData(mimeType: string, value: ArrayBuffer): PasteData; +createPlainTextData(text: string): PasteData -Creates a **PasteData** object of a custom type. +Creates a **PasteData** object of the plain text type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -189,28 +204,28 @@ Creates a **PasteData** object of a custom type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| mimeType | string | Yes| MIME type of custom data.| -| value | ArrayBuffer | Yes| Content of custom data.| +| text | string | Yes| Plain text.| **Return value** | Type| Description| | -------- | -------- | -| [PasteData](#pastedata) | **PasteData** object.| +| [PasteData](#pastedata) | **PasteData** object.| **Example** - ```js - var dataXml = new ArrayBuffer(256) - var pasteData = pasteboard.createData('app/xml', dataXml) - ``` - +```js +let pasteData = pasteboard.createPlainTextData('content'); +``` -## pasteboard.createPlainTextRecord7+ +## pasteboard.createUriData(deprecated) -createPlainTextRecord(text: string): PasteDataRecord +createUriData(uri: string): PasteData -Creates a **PasteDataRecord** object of the plain text type. +Creates a **PasteData** object of the URI type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -218,26 +233,27 @@ Creates a **PasteDataRecord** object of the plain text type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| text | string | Yes| Plain text.| +| uri | string | Yes| URI content.| **Return value** | Type| Description| | -------- | -------- | -| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the plain text type.| +| [PasteData](#pastedata) | **PasteData** object.| **Example** ```js -var record = pasteboard.createPlainTextRecord("hello"); +let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); ``` - - -## pasteboard.createHtmlTextRecord7+ +## pasteboard.createHtmlTextRecord(deprecated) createHtmlTextRecord(htmlText: string): PasteDataRecord Creates a **PasteDataRecord** object of the HTML text type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -256,16 +272,18 @@ Creates a **PasteDataRecord** object of the HTML text type. **Example** ```js -var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; -var record = pasteboard.createHtmlTextRecord(html); +let html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +let record = pasteboard.createHtmlTextRecord(html); ``` - -## pasteboard.createWantRecord7+ +## pasteboard.createWantRecord(deprecated) createWantRecord(want: Want): PasteDataRecord Creates a **PasteDataRecord** object of the Want type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -273,7 +291,7 @@ Creates a **PasteDataRecord** object of the Want type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want content.| +| want | [Want](js-apis-app-ability-want.md) | Yes| Want content.| **Return value** @@ -284,46 +302,21 @@ Creates a **PasteDataRecord** object of the Want type. **Example** ```js -var object = { +let object = { bundleName: "com.example.aafwk.test", abilityName: "com.example.aafwk.test.TwoAbility" }; -var record = pasteboard.createWantRecord(object); -``` - - -## pasteboard.createUriRecord7+ - -createUriRecord(uri: string): PasteDataRecord - -Creates a **PasteDataRecord** object of the URI type. - -**System capability**: SystemCapability.MiscServices.Pasteboard - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| uri | string | Yes| URI content.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the URI type.| - -**Example** - -```js -var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); +let record = pasteboard.createWantRecord(object); ``` +## pasteboard.createPlainTextRecord(deprecated) -## pasteboard.createPixelMapRecord9+ - -createPixelMapRecord(pixelMap: image.PixelMap): PasteDataRecord +createPlainTextRecord(text: string): PasteDataRecord -Creates a **PasteDataRecord** object of the pixel map type. +Creates a **PasteDataRecord** object of the plain text type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -331,37 +324,28 @@ Creates a **PasteDataRecord** object of the pixel map type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| pixelMap | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| Pixel map.| +| text | string | Yes| Plain text.| **Return value** | Type| Description| | -------- | -------- | -| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the pixel map type.| +| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the plain text type.| **Example** ```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 record = pasteboard.createPixelMapRecord(pixelMap); -}) +let record = pasteboard.createPlainTextRecord('hello'); ``` -## pasteboard.createRecord9+ +## pasteboard.createUriRecord(deprecated) -createRecord(mimeType: string, value: ArrayBuffer):PasteDataRecord; +createUriRecord(uri: string): PasteDataRecord -Creates a **PasteDataRecord** object of the custom type. +Creates a **PasteDataRecord** object of the URI type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -369,55 +353,20 @@ Creates a **PasteDataRecord** object of the custom type. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| mimeType | string | Yes| MIME type of custom data.| -| value | ArrayBuffer | Yes| Content of custom data.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the custom type.| - -**Example** - - ```js - var dataXml = new ArrayBuffer(256) - var pasteDataRecord = pasteboard.createRecord('app/xml', dataXml); - ``` - - -## pasteboard.getSystemPasteboard - -getSystemPasteboard(): SystemPasteboard - -Obtains this **SystemPasteboard** object. - -**System capability**: SystemCapability.MiscServices.Pasteboard +| uri | string | Yes| URI content.| **Return value** | Type| Description| | -------- | -------- | -| [SystemPasteboard](#systempasteboard) | **SystemPasteboard** object.| +| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the URI type.| **Example** ```js -var systemPasteboard = pasteboard.getSystemPasteboard(); +let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); ``` -## ShareOption9+ - -Enumerates the paste options of data. - -**System capability**: SystemCapability.MiscServices.Pasteboard - -| Name | Description | -| ----- | ----------------------- | -| InApp |Only intra-application pasting is allowed. | -| LocalDevice |Paste is allowed in any application on the local device. | -| CrossDevice |Paste is allowed in any application across devices. | - ## PasteDataProperty7+ @@ -434,12 +383,10 @@ Defines the properties of all data records on the pasteboard, including the time | localOnly7+ | boolean | Yes| Yes| Whether the pasteboard content is set for local access only. The default value is **true**.
- **true**: The pasteboard content is set for local access only.
- **false**: The pasteboard content can be shared between devices.| | shareOption9+ | [ShareOption](#shareoption9) | Yes| Yes| Where the pasteboard content can be pasted. If this attribute is set incorrectly or not set, the default value **CrossDevice** is used.| - ## PasteDataRecord7+ Provides **PasteDataRecord** APIs. A **PasteDataRecord** is an abstract definition of the content on the pasteboard. The pasteboard content consists of one or more plain text, HTML, URI, or Want records. - ### Attributes **System capability**: SystemCapability.MiscServices.Pasteboard @@ -447,17 +394,43 @@ Provides **PasteDataRecord** APIs. A **PasteDataRecord** is an abstract definiti | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | | htmlText7+ | string | Yes| No| HTML content.| -| want7+ | [Want](js-apis-application-Want.md) | Yes| No| Want content.| +| want7+ | [Want](js-apis-app-ability-want.md) | Yes| No| Want content.| | mimeType7+ | string | Yes| No| Data type.| | plainText7+ | string | Yes| No| Plain text.| | uri7+ | string | Yes| No| URI content.| | pixelMap9+ | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| No| Pixel map.| -| data9+ | {[mimeType: string]: ArrayBuffer} | Yes| No| Content of custom data.| +| data9+ | {[mimeType: string]: ArrayBuffer} | Yes| No| Content of custom data.| +### convertToTextV99+ -### convertToText7+ +convertToTextV9(callback: AsyncCallback<string>): void -convertToText(): Promise<string> +Forcibly converts the content in a **PasteData** object to text. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the text obtained from the conversion. Otherwise, **err** is error information.| + +**Example** + +```js +let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); +record.convertToTextV9((err, data) => { + if (err) { + console.error(`Failed to convert to text. Cause: ${err.message}`); + return; + } + console.info(`Succeeded in converting to text. Data: ${data}`); +}); +``` + +### convertToTextV99+ + +convertToTextV9(): Promise<string> Forcibly converts the content in a **PasteData** object to text. This API uses a promise to return the result. @@ -472,20 +445,22 @@ Forcibly converts the content in a **PasteData** object to text. This API uses a **Example** ```js -var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); -record.convertToText().then((data) => { - console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data)); +let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); +record.convertToTextV9().then((data) => { + console.info(`Succeeded in converting to text. Data: ${data}`); }).catch((err) => { - console.error('Failed to convert to text. Cause: ' + JSON.stringify(err)); + console.error(`Failed to convert to text. Cause: ${err.message}`); }); ``` - -### convertToText7+ +### convertToText(deprecated) convertToText(callback: AsyncCallback<string>): void Forcibly converts the content in a **PasteData** object to text. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [convertToTextV9](#converttotextv99). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -498,16 +473,43 @@ Forcibly converts the content in a **PasteData** object to text. This API uses a **Example** ```js -var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); +let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); record.convertToText((err, data) => { if (err) { - console.error('Failed to convert to text. Cause: ' + JSON.stringify(err)); + console.error(`Failed to convert to text. Cause: ${err.message}`); return; } - console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data)); + console.info(`Succeeded in converting to text. Data: ${data}`); }); ``` +### convertToText(deprecated) + +convertToText(): Promise<string> + +Forcibly converts the content in a **PasteData** object to text. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [convertToTextV9](#converttotextv99-1). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<string> | Promise used to return the text obtained from the conversion.| + +**Example** + +```js +let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); +record.convertToText().then((data) => { + console.info(`Succeeded in converting to text. Data: ${data}`); +}).catch((err) => { + console.error(`Failed to convert to text. Cause: ${err.message}`); +}); +``` ## PasteData @@ -517,18 +519,14 @@ Before calling any **PasteData** API, you must obtain a **PasteData** object. **System capability**: SystemCapability.MiscServices.Pasteboard - ### getPrimaryText - getPrimaryText(): string - Obtains the plain text of the primary record. **System capability**: SystemCapability.MiscServices.Pasteboard - **Return value** | Type| Description| @@ -538,11 +536,10 @@ Obtains the plain text of the primary record. **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var plainText = pasteData.getPrimaryText(); +let pasteData = pasteboard.createPlainTextData('hello'); +let plainText = pasteData.getPrimaryText(); ``` - ### getPrimaryHtml7+ getPrimaryHtml(): string @@ -560,12 +557,11 @@ Obtains the HTML content of the primary record. **Example** ```js -var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; -var pasteData = pasteboard.createHtmlData(html); -var htmlText = pasteData.getPrimaryHtml(); +let html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +let pasteData = pasteboard.createHtmlData(html); +let htmlText = pasteData.getPrimaryHtml(); ``` - ### getPrimaryWant7+ getPrimaryWant(): Want @@ -578,20 +574,19 @@ Obtains the Want object of the primary record. | Type| Description| | -------- | -------- | -| [Want](js-apis-application-Want.md) | Want object.| +| [Want](js-apis-app-ability-want.md) | Want object.| **Example** ```js -var object = { - bundleName: "com.example.aafwk.test", +let object = { + bundleName: "com.example.aafwk.test", abilityName: "com.example.aafwk.test.TwoAbility" }; -var pasteData = pasteboard.createWantData(object); -var want = pasteData.getPrimaryWant(); +let pasteData = pasteboard.createWantData(object); +let want = pasteData.getPrimaryWant(); ``` - ### getPrimaryUri7+ getPrimaryUri(): string @@ -609,11 +604,10 @@ Obtains the URI of the primary record. **Example** ```js -var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt"); -var uri = pasteData.getPrimaryUri(); +let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); +let uri = pasteData.getPrimaryUri(); ``` - ### getPrimaryPixelMap9+ getPrimaryPixelMap(): image.PixelMap @@ -633,26 +627,25 @@ Obtains the pixel map of the primary record. ```js import image from '@ohos.multimedia.image'; -var buffer = new ArrayBuffer(128) -var opt = { +let buffer = new ArrayBuffer(128); +let 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(); -}) + let pasteData = pasteboard.createData('app/xml',pixelMap); + let PixelMap = pasteData.getPrimaryPixelMap(); +}); ``` +### addRecord7+ -### addTextRecord7+ - -addTextRecord(text: string): void +addRecord(record: PasteDataRecord): void -Adds a plain text record to this pasteboard, and adds **MIME_TEXT_PLAIN** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. +Adds a data record to this pasteboard, and adds its type to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. The pasteboard supports a maximum number of 512 data records. @@ -662,130 +655,21 @@ The pasteboard supports a maximum number of 512 data records. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| text | string | Yes| Plain text.| +| record | [PasteDataRecord](#pastedatarecord7) | Yes| Record to add.| **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -pasteData.addTextRecord("good"); -``` - - -### addHtmlRecord7+ - -addHtmlRecord(htmlText: string): void - -Adds an HTML record to this pasteboard, and adds **MIMETYPE_TEXT_HTML** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. - -The pasteboard supports a maximum number of 512 data records. - -**System capability**: SystemCapability.MiscServices.Pasteboard - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| htmlText | string | Yes| HTML content.| - -**Example** - -```js -var pasteData = pasteboard.createPlainTextData("hello"); -var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; -pasteData.addHtmlRecord(html); -``` - - -### addWantRecord7+ - -addWantRecord(want: Want): void - -Adds a Want record to this pasteboard, and adds **MIMETYPE_TEXT_WANT** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. - -The pasteboard supports a maximum number of 512 data records. - -**System capability**: SystemCapability.MiscServices.Pasteboard - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want object.| - -**Example** - -```js -var pasteData = pasteboard.createPlainTextData("hello"); -var object = { - bundleName: "com.example.aafwk.test", - abilityName: "com.example.aafwk.test.TwoAbility" -}; -pasteData.addWantRecord(object); -``` - - -### addUriRecord7+ - -addUriRecord(uri: string): void - -Adds a URI record to this pasteboard, and adds **MIMETYPE_TEXT_URI** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. - -The pasteboard supports a maximum number of 512 data records. - -**System capability**: SystemCapability.MiscServices.Pasteboard - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| uri | string | Yes| URI content.| - -**Example** - -```js -var pasteData = pasteboard.createPlainTextData("hello"); -pasteData.addUriRecord("dataability:///com.example.myapplication1/user.txt"); -``` - -### addPixelMapRecord9+ - -addPixelMapRecord(pixelMap: image.PixelMap): void - -Adds a pixel map record to this pasteboard, and adds **MIMETYPE_PIXELMAP** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. - -The pasteboard supports a maximum number of 512 data records. - -**System capability**: SystemCapability.MiscServices.Pasteboard - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| pixelMap | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| Pixel map.| - -**Example** - -```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 record = pasteboard.createPlainTextData("hello").addPixelMapRecord(pixelMap); -}) +let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); +let textRecord = pasteboard.createPlainTextRecord('hello'); +let html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +let htmlRecord = pasteboard.createHtmlTextRecord(html); +pasteData.addRecord(textRecord); +pasteData.addRecord(htmlRecord); ``` - - ### addRecord9+ -addRecord(mimeType: string, value: ArrayBuffer): void +addRecord(mimeType: string, value: ValueType): void Adds a custom-type record to this pasteboard, and adds the custom type to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. @@ -798,44 +682,23 @@ The pasteboard supports a maximum number of 512 data records. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | mimeType | string | Yes| MIME type of custom data.| -| value | ArrayBuffer | Yes| Content of custom data.| +| value | [ValueType](#valuetype9) | Yes| Content of custom data.| -**Example** - - ```js - var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt"); - var dataXml = new ArrayBuffer(256) - pasteData.addRecord('app/xml', dataXml); - ``` - - -### addRecord7+ - -addRecord(record: PasteDataRecord): void - -Adds a data record to this pasteboard, and adds its type to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. - -The pasteboard supports a maximum number of 512 data records. - -**System capability**: SystemCapability.MiscServices.Pasteboard +**Error codes** -**Parameters** +For details about the error codes, see [Pasteboard Error Codes](../errorcodes/errorcode-pasteboard.md). -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| record | [PasteDataRecord](#pastedatarecord7) | Yes| Record to add.| +| Error Code ID| Error Message| +| -------- | -------- | +| 12900002 | The number of record exceeds the maximum limit. | **Example** -```js -var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt"); -var textRecord = pasteboard.createPlainTextRecord("hello"); -var html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; -var htmlRecord = pasteboard.createHtmlTextRecord(html); -pasteData.addRecord(textRecord); -pasteData.addRecord(htmlRecord); -``` - + ```js + let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); + let dataXml = new ArrayBuffer(256); + pasteData.addRecord('app/xml', dataXml); + ``` ### getMimeTypes7+ @@ -854,11 +717,10 @@ Obtains a list of **mimeTypes** objects in [PasteDataProperty](#pastedatapropert **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var types = pasteData.getMimeTypes(); +let pasteData = pasteboard.createPlainTextData('hello'); +let types = pasteData.getMimeTypes(); ``` - ### getPrimaryMimeType7+ getPrimaryMimeType(): string @@ -876,11 +738,10 @@ Obtains the data type of the primary record in this pasteboard. **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var type = pasteData.getPrimaryMimeType(); +let pasteData = pasteboard.createPlainTextData('hello'); +let type = pasteData.getPrimaryMimeType(); ``` - ### getProperty7+ getProperty(): PasteDataProperty @@ -898,11 +759,10 @@ Obtains the property of the pasteboard data. **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var property = pasteData.getProperty(); +let pasteData = pasteboard.createPlainTextData('hello'); +let property = pasteData.getProperty(); ``` - ### setProperty9+ setProperty(property: PasteDataProperty): void @@ -920,16 +780,15 @@ Sets the property (attributes) for the pasteboard data. Currently, only the **sh **Example** ```js -var pasteData = pasteboard.createHtmlData('application/xml'); +let pasteData = pasteboard.createHtmlData('application/xml'); let prop = pasteData.getProperty(); prop.shareOption = pasteboard.ShareOption.InApp; pasteData.setProperty(prop); ``` +### getRecord9+ -### getRecordAt7+ - -getRecordAt(index: number): PasteDataRecord +getRecord(index: number): PasteDataRecord Obtains the specified record in the pasteboard. @@ -947,14 +806,21 @@ Obtains the specified record in the pasteboard. | -------- | -------- | | [PasteDataRecord](#pastedatarecord7) | Record with the specified index.| +**Error codes** + +For details about the error codes, see [Pasteboard Error Codes](../errorcodes/errorcode-pasteboard.md). + +| Error Code ID| Error Message| +| -------- | -------- | +| 12900001 | The index is out of range. | + **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var record = pasteData.getRecordAt(0); +let pasteData = pasteboard.createPlainTextData('hello'); +let record = pasteData.getRecord(0); ``` - ### getRecordCount7+ getRecordCount(): number @@ -972,11 +838,10 @@ Obtains the number of records in the pasteboard. **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var count = pasteData.getRecordCount(); +let pasteData = pasteboard.createPlainTextData('hello'); +let count = pasteData.getRecordCount(); ``` - ### getTag7+ getTag(): string @@ -994,14 +859,13 @@ Obtains the custom tag from the pasteboard. If no custom tag is set, null is ret **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var tag = pasteData.getTag(); +let pasteData = pasteboard.createPlainTextData('hello'); +let tag = pasteData.getTag(); ``` +### hasType9+ -### hasMimeType7+ - -hasMimeType(mimeType: string): boolean +hasType(mimeType: string): boolean Checks whether the pasteboard contains data of the specified type. @@ -1022,14 +886,13 @@ Checks whether the pasteboard contains data of the specified type. **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); +let pasteData = pasteboard.createPlainTextData('hello'); +let hasType = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN); ``` +### removeRecord9+ -### removeRecordAt7+ - -removeRecordAt(index: number): boolean +removeRecord(index: number): void Removes the record with the specified index from the pasteboard. @@ -1041,23 +904,24 @@ Removes the record with the specified index from the pasteboard. | -------- | -------- | -------- | -------- | | index | number | Yes| Specified index.| -**Return value** +**Error codes** -| Type| Description| +For details about the error codes, see [Pasteboard Error Codes](../errorcodes/errorcode-pasteboard.md). + +| Error Code ID| Error Message| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| +| 12900001 | The index is out of range. | **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var isRemove = pasteData.removeRecordAt(0); +let pasteData = pasteboard.createPlainTextData('hello'); +pasteData.removeRecord(0); ``` +### replaceRecord9+ -### replaceRecordAt7+ - -replaceRecordAt(index: number, record: PasteDataRecord): boolean +replaceRecord(index: number, record: PasteDataRecord): void Replaces the record with the specified index in the pasteboard with a new record. @@ -1070,36 +934,58 @@ Replaces the record with the specified index in the pasteboard with a new record | index | number | Yes| Specified index.| | record | [PasteDataRecord](#pastedatarecord7) | Yes| New record.| -**Return value** +**Error codes** -| Type| Description| +For details about the error codes, see [Pasteboard Error Codes](../errorcodes/errorcode-pasteboard.md). + +| Error Code ID| Error Message| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| +| 12900001 | The index is out of range. | **Example** ```js -var pasteData = pasteboard.createPlainTextData("hello"); -var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); -var isReplace = pasteData.replaceRecordAt(0, record); +let pasteData = pasteboard.createPlainTextData('hello'); +let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); +pasteData.replaceRecord(0, record); ``` +### addHtmlRecord(deprecated) -## SystemPasteboard +addHtmlRecord(htmlText: string): void -Provides **SystemPasteboard** APIs. +Adds an HTML record to this pasteboard, and adds **MIMETYPE_TEXT_HTML** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. -Before calling any **SystemPasteboard** API, you must obtain a **SystemPasteboard** object using [getSystemPasteboard](#pasteboardgetsystempasteboard). +The pasteboard supports a maximum number of 512 data records. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| htmlText | string | Yes| HTML content.| + +**Example** ```js -var systemPasteboard = pasteboard.getSystemPasteboard(); +let pasteData = pasteboard.createPlainTextData('hello'); +let html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; +pasteData.addHtmlRecord(html); ``` +### addWantRecord(deprecated) -### setPasteData +addWantRecord(want: Want): void -setPasteData(data: PasteData, callback: AsyncCallback<void>): void +Adds a Want record to this pasteboard, and adds **MIMETYPE_TEXT_WANT** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. -Writes a **PasteData** object to the pasteboard. This API uses an asynchronous callback to return the result. +The pasteboard supports a maximum number of 512 data records. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -1107,62 +993,55 @@ Writes a **PasteData** object to the pasteboard. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| data | [PasteData](#pastedata) | Yes| **PasteData** object.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| +| want | [Want](js-apis-app-ability-want.md) | Yes| Want object.| **Example** ```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.'); -}); +let pasteData = pasteboard.createPlainTextData('hello'); +let object = { + bundleName: "com.example.aafwk.test", + abilityName: "com.example.aafwk.test.TwoAbility" +}; +pasteData.addWantRecord(object); ``` +### addTextRecord(deprecated) -### setPasteData +addTextRecord(text: string): void -setPasteData(data: PasteData): Promise<void> +Adds a plain text record to this pasteboard, and adds **MIME_TEXT_PLAIN** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. -Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. +The pasteboard supports a maximum number of 512 data records. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). **System capability**: SystemCapability.MiscServices.Pasteboard **Parameters** -| Name| Type| Description| -| -------- | -------- | -------- | -| data | [PasteData](#pastedata) | **PasteData** object.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| Promise<void> | Promise that returns no value.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| text | string | Yes| Plain text.| **Example** ```js -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); -}); +let pasteData = pasteboard.createPlainTextData('hello'); +pasteData.addTextRecord('good'); ``` +### addUriRecord(deprecated) -### getPasteData +addUriRecord(uri: string): void -getPasteData( callback: AsyncCallback<PasteData>): void +Adds a URI record to this pasteboard, and adds **MIMETYPE_TEXT_URI** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. -Obtains a **PasteData** object from the pasteboard. This API uses an asynchronous callback to return the result. +The pasteboard supports a maximum number of 512 data records. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -1170,53 +1049,52 @@ Obtains a **PasteData** object from the pasteboard. This API uses an asynchronou | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[PasteData](#pastedata)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the system pasteboard data. Otherwise, **err** is an error object.| +| uri | string | Yes| URI content.| **Example** ```js -var systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.getPasteData((err, pasteData) => { - if (err) { - console.error('Failed to get PasteData. Cause: ' + err.message); - return; - } - var text = pasteData.getPrimaryText(); -}); +let pasteData = pasteboard.createPlainTextData('hello'); +pasteData.addUriRecord('dataability:///com.example.myapplication1/user.txt'); ``` +### getRecordAt(deprecated) +getRecordAt(index: number): PasteDataRecord -### getPasteData +Obtains the specified record in the pasteboard. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRecord](#getrecord9). -getPasteData(): Promise<PasteData> +**System capability**: SystemCapability.MiscServices.Pasteboard -Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. +**Parameters** -**System capability**: SystemCapability.MiscServices.Pasteboard +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| index | number | Yes| Index of the target record.| **Return value** | Type| Description| | -------- | -------- | -| Promise<[PasteData](#pastedata)> | Promise used to return the system pasteboard data.| +| [PasteDataRecord](#pastedatarecord7) | Record with the specified index.| **Example** ```js -var systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.getPasteData().then((pasteData) => { - var text = pasteData.getPrimaryText(); -}).catch((err) => { - console.error('Failed to get PasteData. Cause: ' + err.message); -}) +let pasteData = pasteboard.createPlainTextData('hello'); +let record = pasteData.getRecordAt(0); ``` +### hasMimeType(deprecated) -### on('update')7+ - -on(type: 'update', callback: () =>void ): void +hasMimeType(mimeType: string): boolean -Subscribes to the content change event of the system pasteboard. +Checks whether the pasteboard contains data of the specified type. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasType](#hastype9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -1224,19 +1102,115 @@ Subscribes to the content change event of the system pasteboard. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value **'update'** indicates changes in the pasteboard content.| -| callback | function | Yes| Callback invoked when the pasteboard content changes.| +| mimeType | string | Yes| Type of the data to query.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the specified data type exists; returns **false** otherwise.| **Example** ```js -var systemPasteboard = pasteboard.getSystemPasteboard(); -var listener = () => { - console.info('The system pasteboard has changed.'); -}; -systemPasteboard.on('update', listener); +let pasteData = pasteboard.createPlainTextData('hello'); +let hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); ``` +### removeRecordAt(deprecated) +removeRecordAt(index: number): boolean + +Removes the record with the specified index from the pasteboard. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [removeRecord](#removerecord9). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| index | number | Yes| Specified index.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```js +let pasteData = pasteboard.createPlainTextData('hello'); +let isRemove = pasteData.removeRecordAt(0); +``` +### replaceRecordAt(deprecated) + +replaceRecordAt(index: number, record: PasteDataRecord): boolean + +Replaces the record with the specified index in the pasteboard with a new record. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [replaceRecord](#replacerecord9). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| index | number | Yes| Specified index.| +| record | [PasteDataRecord](#pastedatarecord7) | Yes| New record.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```js +let pasteData = pasteboard.createPlainTextData('hello'); +let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); +let isReplace = pasteData.replaceRecordAt(0, record); +``` + +## SystemPasteboard + +Provides **SystemPasteboard** APIs. + +Before calling any **SystemPasteboard** API, you must obtain a **SystemPasteboard** object using [getSystemPasteboard](#pasteboardgetsystempasteboard). + +```js +let systemPasteboard = pasteboard.getSystemPasteboard(); +``` + +### on('update')7+ + +on(type: 'update', callback: () =>void ): void + +Subscribes to the content change event of the system pasteboard. + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type. The value **'update'** indicates changes in the pasteboard content.| +| callback | function | Yes| Callback invoked when the pasteboard content changes.| + +**Example** + +```js +let systemPasteboard = pasteboard.getSystemPasteboard(); +let listener = () => { + console.info('The system pasteboard has changed.'); +}; +systemPasteboard.on('update', listener); +``` ### off('update')7+ @@ -1256,16 +1230,215 @@ Unsubscribes from the system pasteboard content change event. **Example** ```js +let systemPasteboard = pasteboard.getSystemPasteboard(); let listener = () => { console.info('The system pasteboard has changed.'); -}; +}; systemPasteboard.off('update', listener); ``` +### clearData9+ -### hasPasteData7+ +clearData(callback: AsyncCallback<void>): void -hasPasteData(callback: AsyncCallback<boolean>): void +Clears the system pasteboard. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| + +**Example** + +```js +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.clearData((err, data) => { + if (err) { + console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); + return; + } + console.info('Succeeded in clearing the pasteboard.'); +}); +``` + +### clearData9+ + +clearData(): Promise<void> + +Clears the system pasteboard. This API uses a promise to return the result. + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```js +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.clearData().then((data) => { + console.info('Succeeded in clearing the pasteboard.'); +}).catch((err) => { + console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); +}); +``` + +### setData9+ + +setData(data: PasteData, callback: AsyncCallback<void>): void + +Writes a **PasteData** object to the pasteboard. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| data | [PasteData](#pastedata) | Yes| **PasteData** object.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| + +**Error codes** + +For details about the error codes, see [Pasteboard Error Codes](../errorcodes/errorcode-pasteboard.md). + +| Error Code ID| Error Message| +| -------- | -------- | +| 12900003 | Another copy or paste is in progress. | +| 12900004 | Replication is prohibited. | + +**Example** + +```js +let pasteData = pasteboard.createPlainTextData('content'); +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.setData(pasteData, (err, data) => { + if (err) { + console.error('Failed to set PasteData. Cause: ' + err.message); + return; + } + console.info('Succeeded in setting PasteData.'); +}); +``` + +### setData9+ + +setData(data: PasteData): Promise<void> + +Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| data | [PasteData](#pastedata) | Yes| **PasteData** object.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Pasteboard Error Codes](../errorcodes/errorcode-pasteboard.md). + +| Error Code ID| Error Message| +| -------- | -------- | +| 12900003 | Another copy or paste is in progress. | +| 12900004 | Replication is prohibited. | + +**Example** + +```js +let pasteData = pasteboard.createPlainTextData('content'); +let 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); +}); +``` + +### getData9+ + +getData( callback: AsyncCallback<PasteData>): void + +Obtains a **PasteData** object from the pasteboard. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<[PasteData](#pastedata)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the system pasteboard data. Otherwise, **err** is an error object.| + +**Error codes** + +For details about the error codes, see [Pasteboard Error Codes](../errorcodes/errorcode-pasteboard.md). + +| Error Code ID| Error Message| +| -------- | -------- | +| 12900003 | Another copy or paste is in progress. | + +**Example** + +```js +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.getData((err, pasteData) => { + if (err) { + console.error('Failed to get PasteData. Cause: ' + err.message); + return; + } + let text = pasteData.getPrimaryText(); +}); +``` + +### getData9+ + +getData(): Promise<PasteData> + +Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[PasteData](#pastedata)> | Promise used to return the system pasteboard data.| + +**Error codes** + +For details about the error codes, see [Pasteboard Error Codes](../errorcodes/errorcode-pasteboard.md). + +| Error Code ID| Error Message| +| -------- | -------- | +| 12900003 | Another copy or paste is in progress. | + +**Example** + +```js +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.getData().then((pasteData) => { + let text = pasteData.getPrimaryText(); +}).catch((err) => { + console.error('Failed to get PasteData. Cause: ' + err.message); +}) +``` + +### hasData9+ + +hasData(callback: AsyncCallback<boolean>): void Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result. @@ -1280,19 +1453,19 @@ Checks whether the system pasteboard contains data. This API uses an asynchronou **Example** ```js -systemPasteboard.hasPasteData((err, data) => { +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.hasData((err, data) => { if (err) { - console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err)); + console.error(`Failed to check the PasteData. Cause: ${err.message}`); return; } - console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data)); + console.info(`Succeeded in checking the PasteData. Data: ${data}`); }); ``` +### hasData9+ -### hasPasteData7+ - -hasPasteData(): Promise<boolean> +hasData(): Promise<boolean> Checks whether the system pasteboard contains data. This API uses a promise to return the result. @@ -1307,19 +1480,22 @@ Checks whether the system pasteboard contains data. This API uses a promise to r **Example** ```js -systemPasteboard.hasPasteData().then((data) => { - console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data)); +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.hasData().then((data) => { + console.info(`Succeeded in checking the PasteData. Data: ${data}`); }).catch((err) => { - console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err)); + console.error(`Failed to check the PasteData. Cause: ${err.message}`); }); ``` - -### clear7+ +### clear(deprecated) clear(callback: AsyncCallback<void>): void Clears the system pasteboard. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.clearData](#cleardata9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -1334,19 +1510,21 @@ Clears the system pasteboard. This API uses an asynchronous callback to return t ```js systemPasteboard.clear((err, data) => { if (err) { - console.error('Failed to clear the PasteData. Cause: ' + JSON.stringify(err)); - return; + console.error(`Failed to clear the PasteData. Cause: ${err.message}`); + return; } console.info('Succeeded in clearing the PasteData.'); }); ``` - -### clear7+ +### clear(deprecated) clear(): Promise<void> Clears the system pasteboard. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.clearData](#cleardata9-1). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -1362,6 +1540,186 @@ Clears the system pasteboard. This API uses a promise to return the result. systemPasteboard.clear().then((data) => { console.info('Succeeded in clearing the PasteData.'); }).catch((err) => { - console.error('Failed to clear the PasteData. Cause: ' + JSON.stringify(err)); + console.error(`Failed to clear the PasteData. Cause: ${err.message}`); +}); +``` + +### getPasteData(deprecated) + +getPasteData( callback: AsyncCallback<PasteData>): void + +Obtains a **PasteData** object from the pasteboard. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getData](#getdata9). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<[PasteData](#pastedata)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the system pasteboard data. Otherwise, **err** is an error object.| + +**Example** + +```js +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.getPasteData((err, pasteData) => { + if (err) { + console.error('Failed to get PasteData. Cause: ' + err.message); + return; + } + let text = pasteData.getPrimaryText(); +}); +``` + +### getPasteData(deprecated) + +getPasteData(): Promise<PasteData> + +Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getData](#getdata9-1). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[PasteData](#pastedata)> | Promise used to return the system pasteboard data.| + +**Example** + +```js +let systemPasteboard = pasteboard.getSystemPasteboard(); +systemPasteboard.getPasteData().then((pasteData) => { + let text = pasteData.getPrimaryText(); +}).catch((err) => { + console.error('Failed to get PasteData. Cause: ' + err.message); +}) +``` + +### hasPasteData(deprecated) + +hasPasteData(callback: AsyncCallback<boolean>): void + +Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasData](#hasdata9). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| + +**Example** + +```js +systemPasteboard.hasPasteData((err, data) => { + if (err) { + console.error(`Failed to check the PasteData. Cause: ${err.message}`); + return; + } + console.info(`Succeeded in checking the PasteData. Data: ${data}`); +}); +``` + +### hasPasteData(deprecated) + +hasPasteData(): Promise<boolean> + +Checks whether the system pasteboard contains data. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasData](#hasdata9-1). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| + +**Example** + +```js +systemPasteboard.hasPasteData().then((data) => { + console.info(`Succeeded in checking the PasteData. Data: ${data}`); +}).catch((err) => { + console.error(`Failed to check the PasteData. Cause: ${err.message}`); +}); +``` + +### setPasteData(deprecated) + +setPasteData(data: PasteData, callback: AsyncCallback<void>): void + +Writes a **PasteData** object to the pasteboard. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setData](#setdata9). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| data | [PasteData](#pastedata) | Yes| **PasteData** object.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| + +**Example** + +```js +let pasteData = pasteboard.createPlainTextData('content'); +let 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(deprecated) + +setPasteData(data: PasteData): Promise<void> + +Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setData](#setdata9-1). + +**System capability**: SystemCapability.MiscServices.Pasteboard + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| data | [PasteData](#pastedata) | Yes| **PasteData** object.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```js +let pasteData = pasteboard.createPlainTextData('content'); +let 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); }); ``` diff --git a/en/application-dev/reference/errorcodes/errorcode-pasteboard.md b/en/application-dev/reference/errorcodes/errorcode-pasteboard.md new file mode 100644 index 0000000000..05cee20afa --- /dev/null +++ b/en/application-dev/reference/errorcodes/errorcode-pasteboard.md @@ -0,0 +1,75 @@ +# Pasteboard Error Codes + +## 12900001 Index Out of Range + +**Error Message** + +The index is out of range. + +**Description** + +This error code is reported when the index passed in to the called API, such as **getRecord**, is out of range. + +**Possible Causes** + +The index passed in the API is beyond the record index range of the **PasteData** object. For example, the index passed in to **getRecord** exceeds the number of records. + +**Solution** + +Check the index range and call the API again with a valid index. + +## 12900002 Maximum Number of Records Reached + +**Error Message** + +The number of record exceeds the maximum limit. + +**Description** + +This error code is reported when no new **PasteData** record can be added. + +**Possible Causes** + +The number of **PasteData** records has reached the maximum. + +**Solution** + +1. Check whether the number of **PasteData** records has reached the maximum. +2. If the number of **PasteData** records has reached the maximum, delete some records before adding new ones. + +## 12900003 Another Copy or Paste Operation in Progress + +**Error Message** + +Another copy or paste is in progress. + +**Description** + +This error code is reported when a new copy or paste attempt is made before the previous one is completed. + +**Possible Causes** + +The copy and paste APIs are both asynchronous APIs. If the data to be copied or pasted is in large amount, the time required may be long. New copy or paste operations can be performed only after the previous operations have been completed. + +**Solution** + +1. Before copying or pasting data, check the status of the last copy or paste operation. +2. Perform subsequent operations only after the previous copy/paste operation is completed. + +## 12900004 Copy Prohibited + +**Error Message** + +Replication is prohibited. + +**Description** + +This error code is reported when an attempt is made to copy data that cannot be copied. + +**Possible Causes** + +The target data cannot be copied, such as read-only data. + +**Solution** + +Make sure the target data allows the copy action. \ No newline at end of file -- GitLab