diff --git a/en/application-dev/reference/apis/js-apis-pasteboard.md b/en/application-dev/reference/apis/js-apis-pasteboard.md index ee53667d0158343624ab086abe598a8baa9608c0..7a5adcd1f86a0fa6473d0642eacbdab29f9a3603 100644 --- a/en/application-dev/reference/apis/js-apis-pasteboard.md +++ b/en/application-dev/reference/apis/js-apis-pasteboard.md @@ -1,9 +1,9 @@ -# Pasteboard +# @ohos.pasteboard (Pasteboard) The **pasteboard** module provides the copy and paste support for the system pasteboard. You can use the APIs of this module to operate pasteboard content of the plain text, HTML, URI, Want, pixel map, and other types. > **NOTE** -> +> > The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -63,7 +63,7 @@ Creates a **PasteData** object of a custom type. ```js let dataXml = new ArrayBuffer(256); - let pasteData = pasteboard.createData('app/xml', dataXml); +let pasteData = pasteboard.createData('app/xml', dataXml); ``` ## pasteboard.createRecord9+ @@ -90,8 +90,8 @@ Creates a **PasteDataRecord** object of the custom type. **Example** ```js - let dataXml = new ArrayBuffer(256); - let pasteDataRecord = pasteboard.createRecord('app/xml', dataXml); +let dataXml = new ArrayBuffer(256); +let pasteDataRecord = pasteboard.createRecord('app/xml', dataXml); ``` ## pasteboard.getSystemPasteboard @@ -120,11 +120,11 @@ 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.| +| Name | Value| Description | +|-------------|---|-------------------| +| INAPP | 0 | Only intra-application pasting is allowed. | +| LOCALDEVICE | 1 | Paste is allowed in any application on the local device.| +| CROSSDEVICE | 2 | Paste is allowed in any application across devices. | ## pasteboard.createHtmlData(deprecated) @@ -374,14 +374,14 @@ Defines the properties of all data records on the pasteboard, including the time **System capability**: SystemCapability.MiscServices.Pasteboard -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| additions7+ | {[key:string]:object} | Yes| Yes| Additional data.| -| mimeTypes7+ | Array<string> | Yes| No| Non-repeating data types of the data records on the pasteboard.| -| tag7+ | string | Yes| Yes| Custom tag.| -| timestamp7+ | number | Yes| No| Timestamp when data is written to the pasteboard (unit: ms).| +| Name| Type| Readable| Writable| Description | +| -------- | -------- | -------- | -------- |--------------------------------------------------------------------------------------------| +| additions7+ | {[key:string]:object} | Yes| Yes| Additional data. | +| mimeTypes7+ | Array<string> | Yes| No| Non-repeating data types of the data records on the pasteboard. | +| tag7+ | string | Yes| Yes| Custom tag. | +| timestamp7+ | number | Yes| No| Timestamp when data is written to the pasteboard (unit: ms). | | 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.| +| 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+ @@ -401,38 +401,11 @@ Provides **PasteDataRecord** APIs. A **PasteDataRecord** is an abstract definiti | pixelMap9+ | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes| No| Pixel map.| | data9+ | {[mimeType: string]: ArrayBuffer} | Yes| No| Content of custom data.| -### convertToTextV99+ - -convertToTextV9(callback: AsyncCallback<string>): void - -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** +### toPlainText9+ -```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+ +toPlainText(): string -convertToTextV9(): Promise<string> - -Forcibly converts the content in a **PasteData** object to text. This API uses a promise to return the result. +Forcibly converts the content in a **PasteData** object to text. **System capability**: SystemCapability.MiscServices.Pasteboard @@ -440,17 +413,14 @@ Forcibly converts the content in a **PasteData** object to text. This API uses a | Type| Description| | -------- | -------- | -| Promise<string> | Promise used to return the text obtained from the conversion.| +| string | Plain text.| **Example** ```js -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: ${err.message}`); -}); +let record = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); +let data = record.toPlainText(); +console.info(`Succeeded in converting to text. Data: ${data}`); ``` ### convertToText(deprecated) @@ -460,7 +430,7 @@ 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). +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [toPlainText](#toplaintext9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -474,11 +444,11 @@ Forcibly converts the content in a **PasteData** object to text. This API uses a ```js let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); -record.convertToText((err, data) => { - if (err) { +record.convertToText((err, data) => { + if (err) { console.error(`Failed to convert to text. Cause: ${err.message}`); - return; - } + return; + } console.info(`Succeeded in converting to text. Data: ${data}`); }); ``` @@ -490,7 +460,7 @@ 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). +> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [toPlainText](#toplaintext9). **System capability**: SystemCapability.MiscServices.Pasteboard @@ -536,7 +506,7 @@ Obtains the plain text of the primary record. **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let plainText = pasteData.getPrimaryText(); ``` @@ -558,7 +528,7 @@ Obtains the HTML content of the primary record. ```js let html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; -let pasteData = pasteboard.createHtmlData(html); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, html); let htmlText = pasteData.getPrimaryHtml(); ``` @@ -583,7 +553,7 @@ let object = { bundleName: "com.example.aafwk.test", abilityName: "com.example.aafwk.test.TwoAbility" }; -let pasteData = pasteboard.createWantData(object); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_WANT, object); let want = pasteData.getPrimaryWant(); ``` @@ -604,7 +574,7 @@ Obtains the URI of the primary record. **Example** ```js -let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); let uri = pasteData.getPrimaryUri(); ``` @@ -636,7 +606,7 @@ let opt = { scaleMode: 1 }; image.createPixelMap(buffer, opt).then((pixelMap) => { - let pasteData = pasteboard.createData('app/xml',pixelMap); + let pasteData = pasteboard.createData(MIMETYPE_PIXELMAP, pixelMap); let PixelMap = pasteData.getPrimaryPixelMap(); }); ``` @@ -660,10 +630,10 @@ The pasteboard supports a maximum number of 512 data records. **Example** ```js -let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); -let textRecord = pasteboard.createPlainTextRecord('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); +let textRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let html = "\n" + "\n" + "\n" + "\n" + "HTML-PASTEBOARD_HTML\n" + "\n" + "\n" + "

HEAD

\n" + "

\n" + "\n" + ""; -let htmlRecord = pasteboard.createHtmlTextRecord(html); +let htmlRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_HTML, html); pasteData.addRecord(textRecord); pasteData.addRecord(htmlRecord); ``` @@ -695,9 +665,9 @@ For details about the error codes, see [Pasteboard Error Codes](../errorcodes/er **Example** ```js - let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); - let dataXml = new ArrayBuffer(256); - pasteData.addRecord('app/xml', dataXml); + let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); +let dataXml = new ArrayBuffer(256); +pasteData.addRecord('app/xml', dataXml); ``` ### getMimeTypes7+ @@ -717,7 +687,7 @@ Obtains a list of **mimeTypes** objects in [PasteDataProperty](#pastedatapropert **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let types = pasteData.getMimeTypes(); ``` @@ -738,7 +708,7 @@ Obtains the data type of the primary record in this pasteboard. **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let type = pasteData.getPrimaryMimeType(); ``` @@ -759,7 +729,7 @@ Obtains the property of the pasteboard data. **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let property = pasteData.getProperty(); ``` @@ -780,9 +750,9 @@ Sets the property (attributes) for the pasteboard data. Currently, only the **sh **Example** ```js -let pasteData = pasteboard.createHtmlData('application/xml'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, 'application/xml'); let prop = pasteData.getProperty(); -prop.shareOption = pasteboard.ShareOption.InApp; +prop.shareOption = pasteboard.ShareOption.INAPP; pasteData.setProperty(prop); ``` @@ -817,7 +787,7 @@ For details about the error codes, see [Pasteboard Error Codes](../errorcodes/er **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let record = pasteData.getRecord(0); ``` @@ -838,7 +808,7 @@ Obtains the number of records in the pasteboard. **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let count = pasteData.getRecordCount(); ``` @@ -859,7 +829,7 @@ Obtains the custom tag from the pasteboard. If no custom tag is set, null is ret **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let tag = pasteData.getTag(); ``` @@ -886,7 +856,7 @@ Checks whether the pasteboard contains data of the specified type. **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); let hasType = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN); ``` @@ -915,7 +885,7 @@ For details about the error codes, see [Pasteboard Error Codes](../errorcodes/er **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); pasteData.removeRecord(0); ``` @@ -945,8 +915,8 @@ For details about the error codes, see [Pasteboard Error Codes](../errorcodes/er **Example** ```js -let pasteData = pasteboard.createPlainTextData('hello'); -let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); +let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); +let record = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); pasteData.replaceRecord(0, record); ``` ### addHtmlRecord(deprecated) @@ -999,8 +969,8 @@ The pasteboard supports a maximum number of 512 data records. ```js let pasteData = pasteboard.createPlainTextData('hello'); -let object = { - bundleName: "com.example.aafwk.test", +let object = { + bundleName: "com.example.aafwk.test", abilityName: "com.example.aafwk.test.TwoAbility" }; pasteData.addWantRecord(object); @@ -1255,7 +1225,7 @@ Clears the system pasteboard. This API uses an asynchronous callback to return t ```js let systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.clearData((err, data) => { +systemPasteboard.clearData((err, data) => { if (err) { console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); return; @@ -1282,7 +1252,7 @@ Clears the system pasteboard. This API uses a promise to return the result. ```js let systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.clearData().then((data) => { +systemPasteboard.clearData().then((data) => { console.info('Succeeded in clearing the pasteboard.'); }).catch((err) => { console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); @@ -1318,7 +1288,7 @@ For details about the error codes, see [Pasteboard Error Codes](../errorcodes/er ```js let pasteData = pasteboard.createPlainTextData('content'); let systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.setData(pasteData, (err, data) => { +systemPasteboard.setData(pasteData, (err, data) => { if (err) { console.error('Failed to set PasteData. Cause: ' + err.message); return; @@ -1394,7 +1364,7 @@ For details about the error codes, see [Pasteboard Error Codes](../errorcodes/er ```js let systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.getData((err, pasteData) => { +systemPasteboard.getData((err, pasteData) => { if (err) { console.error('Failed to get PasteData. Cause: ' + err.message); return; @@ -1429,7 +1399,7 @@ For details about the error codes, see [Pasteboard Error Codes](../errorcodes/er ```js let systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.getData().then((pasteData) => { +systemPasteboard.getData().then((pasteData) => { let text = pasteData.getPrimaryText(); }).catch((err) => { console.error('Failed to get PasteData. Cause: ' + err.message); @@ -1481,7 +1451,7 @@ Checks whether the system pasteboard contains data. This API uses a promise to r ```js let systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.hasData().then((data) => { +systemPasteboard.hasData().then((data) => { console.info(`Succeeded in checking the PasteData. Data: ${data}`); }).catch((err) => { console.error(`Failed to check the PasteData. Cause: ${err.message}`); @@ -1508,8 +1478,8 @@ Clears the system pasteboard. This API uses an asynchronous callback to return t **Example** ```js -systemPasteboard.clear((err, data) => { - if (err) { +systemPasteboard.clear((err, data) => { + if (err) { console.error(`Failed to clear the PasteData. Cause: ${err.message}`); return; } @@ -1537,9 +1507,9 @@ Clears the system pasteboard. This API uses a promise to return the result. **Example** ```js -systemPasteboard.clear().then((data) => { +systemPasteboard.clear().then((data) => { console.info('Succeeded in clearing the PasteData.'); -}).catch((err) => { +}).catch((err) => { console.error(`Failed to clear the PasteData. Cause: ${err.message}`); }); ``` @@ -1595,7 +1565,7 @@ Obtains a **PasteData** object from the pasteboard. This API uses a promise to r ```js let systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.getPasteData().then((pasteData) => { +systemPasteboard.getPasteData().then((pasteData) => { let text = pasteData.getPrimaryText(); }).catch((err) => { console.error('Failed to get PasteData. Cause: ' + err.message); @@ -1651,7 +1621,7 @@ Checks whether the system pasteboard contains data. This API uses a promise to r **Example** ```js -systemPasteboard.hasPasteData().then((data) => { +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}`); @@ -1681,7 +1651,7 @@ Writes a **PasteData** object to the pasteboard. This API uses an asynchronous c ```js let pasteData = pasteboard.createPlainTextData('content'); let systemPasteboard = pasteboard.getSystemPasteboard(); -systemPasteboard.setPasteData(pasteData, (err, data) => { +systemPasteboard.setPasteData(pasteData, (err, data) => { if (err) { console.error('Failed to set PasteData. Cause: ' + err.message); return; diff --git a/en/release-notes/changelogs/OpenHarmony_4.0.2.3/changelogs-pasteboard.md b/en/release-notes/changelogs/OpenHarmony_4.0.2.3/changelogs-pasteboard.md new file mode 100644 index 0000000000000000000000000000000000000000..8d8b439cc3a7461162c51abc2f84d09f00412e3d --- /dev/null +++ b/en/release-notes/changelogs/OpenHarmony_4.0.2.3/changelogs-pasteboard.md @@ -0,0 +1,66 @@ +# Pasteboard Subsystem Changelog + +OpenHarmony 4.0.3.2 has the following changes in the APIs of the pasteboard subsystem: + +## cl.pasteboard.1 convertToTextV9 API Change + +Renamed **convertToTextV9** **toPlainText()** and changed the API from asynchronous to synchronous. + +**Change Impact** + +Applications developed using the **convertToTextV9** API in versions earlier than OpenHarmony 4.0.3.3 cannot be used in OpenHarmony 4.0.3.3 and later versions. + +**Key API/Component Changes** + +- Involved APIs: + + function convertToTextV9 + +- Before change: + + ```ts + convertToTextV9(callback: AsyncCallback): void; + convertToTextV9(): Promise; + ``` + +- After change: + + ```ts + toPlainText(): string; + ``` + + +**Adaptation Guide** + +Replace **convertToTextV9**, an asynchronous API, with **toPlainText**, a synchronous API. + +## cl.pasteboard.2 ShareOption Enum Name Change + +Changed the enum names of **ShareOption** from UpperCamelCase to all caps. + +**Change Impact** + +Applications developed using the **InApp/LocalDevice/CrossDevice** attributes in versions earlier than OpenHarmony 4.0.3.3 cannot be used in OpenHarmony 4.0.3.3 and later versions. + +**Key API/Component Changes** + +ShareOption9+ + +Before change: +| Name| Value| Description | +| ---- |---|-------------------| +| InApp | 0 | Only intra-application pasting is allowed. | +| LocalDevice | 1 | Paste is allowed in any application on the local device.| +| CrossDevice | 2 | Paste is allowed in any application across devices. | + + +After change: +| Name| Value| Description | +| ---- |---|-------------------| +| INAPP | 0 | Only intra-application pasting is allowed. | +| LOCALDEVICE | 1 | Paste is allowed in any application on the local device.| +| CROSSDEVICE | 2 | Paste is allowed in any application across devices. | + +**Adaptation Guide** + +Perform adaptation based on the new semantics.