This is a test.
+ + + + + + +``` + +#### CSS + +```css +body { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 5px; +} + +textarea { + grid-column: 1 / span 3; +} +``` + +#### JavaScript + +```js +const copyButton = document.getElementById("copy"); +const pasteButton = document.getElementById("paste_normal"); +const pasteUnsanitizedButton = document.getElementById("paste_unsanitized"); +const sourceTextarea = document.getElementById("source"); +const destinationTextarea = document.getElementById("destination"); + +copyButton.addEventListener("click", async () => { + const text = sourceTextarea.value; + const type = "text/html"; + const blob = new Blob([text], { type }); + const data = [new ClipboardItem({ [type]: blob })]; + + try { + await navigator.clipboard.write(data); + } catch (error) { + destinationTextarea.value = `Clipboard write failed: ${error}`; + } +}); + +async function getHTMLFromClipboardContents(clipboardContents) { + for (const item of clipboardContents) { + if (item.types.includes("text/html")) { + const blob = await item.getType("text/html"); + const blobText = await blob.text(); + return blobText; + } + } + + return null; +} + +pasteButton.addEventListener("click", async () => { + try { + const clipboardContents = await navigator.clipboard.read(); + const html = await getHTMLFromClipboardContents(clipboardContents); + destinationTextarea.value = + html || "Could not find HTML data in the clipboard."; + } catch (error) { + destinationTextarea.value = `Clipboard read failed: ${error}`; + } +}); + +pasteUnsanitizedButton.addEventListener("click", async () => { + try { + const clipboardContents = await navigator.clipboard.read({ + unsanitized: ["text/html"], + }); + const html = await getHTMLFromClipboardContents(clipboardContents); + destinationTextarea.value = + html || "Could not find HTML data in the clipboard."; + } catch (error) { + destinationTextarea.value = `Clipboard read failed: ${error}`; + } +}); +``` + +#### Result + +First click the "Copy HTML" button to write the HTML code from the first textarea to the clipboard. Then either click the "Paste HTML" button or the "Paste unsanitized HTML" button to paste the sanitized or unsanitized HTML code into the second textarea. + +{{EmbedLiveSample("Reading unsanitized HTML from the clipboard", "100%", "220")}} ## Specifications @@ -118,5 +358,8 @@ async function pasteImage() { ## See also - [Clipboard API](/en-US/docs/Web/API/Clipboard_API) -- [Async Clipboard API demo on Glitch](https://async-clipboard-api.glitch.me/) -- [Image support for Async Clipboard article](https://web.dev/articles/async-clipboard) +- [Unblocking clipboard access](https://web.dev/articles/async-clipboard) on web.dev +- [Unsanitized HTML in the Async Clipboard API](https://developer.chrome.com/docs/web-platform/unsanitized-html-async-clipboard) on developer.chrome.com +- {{domxref("Clipboard.readText()")}} +- {{domxref("Clipboard.writeText()")}} +- {{domxref("Clipboard.write()")}} diff --git a/files/en-us/web/api/clipboard/readtext/index.md b/files/en-us/web/api/clipboard/readtext/index.md index 63ebc49055e1621..14a981fac4051ea 100644 --- a/files/en-us/web/api/clipboard/readtext/index.md +++ b/files/en-us/web/api/clipboard/readtext/index.md @@ -6,11 +6,12 @@ page-type: web-api-instance-method browser-compat: api.Clipboard.readText --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} -The **{{domxref("Clipboard")}}** interface's -**`readText()`** method returns a {{jsxref("Promise")}} which -resolves with a copy of the textual contents of the system clipboard. +The **`readText()`** method of the {{domxref("Clipboard")}} interface returns a {{jsxref("Promise")}} which fulfils with a copy of the textual contents of the system clipboard. + +> **Note:** To read non-text contents from the clipboard, use the {{domxref("Clipboard.read", "read()")}} method instead. +> You can write text to the clipboard using {{domxref("Clipboard.writeText", "writeText()")}}. ## Syntax @@ -24,30 +25,34 @@ None. ### Return value -A {{jsxref("Promise")}} that resolves with a string containing the -textual contents of the clipboard. Returns an empty string if the clipboard is empty, -does not contain text, or does not include a textual representation among the -{{domxref("DataTransfer")}} objects representing the clipboard's contents. +A {{jsxref("Promise")}} that resolves with a string containing the textual contents of the clipboard. + +Returns an empty string if the clipboard is empty, does not contain text, or does not include a textual representation among the objects representing the clipboard's contents. + +### Exceptions -To read non-text contents from the clipboard, use the {{domxref("Clipboard.read", - "read()")}} method instead. You can write text to the clipboard using -{{domxref("Clipboard.writeText", "writeText()")}}. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if the access to read the clipboard is not allowed. +- `NotFoundError` {{domxref("DOMException")}} + - : Thrown if the clipboard indicates that it contains data that can be represented as a text but is unable to provide a textual representation. -## Security +## Security considerations -[Transient user activation](/en-US/docs/Web/Security/User_activation) is required. The user has to interact with the page or a UI element in order for this feature to work. +Reading from the clipboard can only be done in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -The `"clipboard-read"` permission of the [Permissions API](/en-US/docs/Web/API/Permissions_API) must be granted before you can read data from the clipboard. +Additional security requirements are covered in the [Security consideration](/en-US/docs/Web/API/Clipboard_API#security_considerations) section of the API overview topic. ## Examples -This example retrieves the textual contents of the clipboard and inserts the returned -text into an element's contents. +This example retrieves the textual contents of the clipboard and inserts the returned text into a selected element's contents. ```js -navigator.clipboard - .readText() - .then((clipText) => (document.getElementById("outbox").innerText = clipText)); +const destination = document.getElementById("outbox"); +destinationImage.addEventListener("click", () => { + navigator.clipboard + .readText() + .then((clipText) => (destination.innerText = clipText)); +}); ``` ## Specifications @@ -61,7 +66,7 @@ navigator.clipboard ## See also - [Clipboard API](/en-US/docs/Web/API/Clipboard_API) -- [Async Clipboard API demo on Glitch](https://async-clipboard-api.glitch.me/) - [Image support for Async Clipboard article](https://web.dev/articles/async-clipboard) +- {{domxref("Clipboard.read()")}} - {{domxref("Clipboard.writeText()")}} - {{domxref("Clipboard.write()")}} diff --git a/files/en-us/web/api/clipboard/write/index.md b/files/en-us/web/api/clipboard/write/index.md index 743ef1789618308..c2613a1edd400b1 100644 --- a/files/en-us/web/api/clipboard/write/index.md +++ b/files/en-us/web/api/clipboard/write/index.md @@ -6,21 +6,13 @@ page-type: web-api-instance-method browser-compat: api.Clipboard.write --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} -The {{domxref("Clipboard")}} method -**`write()`** writes arbitrary data, such as images, to the -clipboard. This can be used to implement cut and copy functionality. +The **`write()`** method of the {{domxref("Clipboard")}} interface writes arbitrary data to the clipboard, such as images, fulfilling the returned {{jsxref("Promise")}} on completion. +This can be used to implement cut and copy functionality. -The `"clipboard-write"` permission of the [Permissions API](/en-US/docs/Web/API/Permissions_API), is granted -automatically to pages when they are in the active tab. - -> **Note:** Browser support for the asynchronous clipboard APIs is still -> in the process of being implemented. Be sure to check the [compatibility table](#browser_compatibility) as well as -> [Clipboard availability](/en-US/docs/Web/API/Clipboard#clipboard_availability) for more -> information. - -> **Note:** For parity with Google Chrome, Firefox only allows this function to work with text, HTML, and PNG data. +The method can in theory write arbitrary data (unlike {{domxref("Clipboard.writeText", "writeText()")}}, which can only write text). +Browsers commonly support writing text, HTML, and PNG image data — see [browser compatibility](#browser_compatibility) for more information. ## Syntax @@ -31,67 +23,73 @@ write(data) ### Parameters - `data` - - : An array of {{domxref("ClipboardItem")}} objects containing data to be written to - the clipboard. + - : An array of {{domxref("ClipboardItem")}} objects containing data to be written to the clipboard. ### Return value -A {{jsxref("Promise")}} which is resolved when the data has been written to the -clipboard. The promise is rejected if the clipboard is unable to complete the clipboard -access. +A {{jsxref("Promise")}} which is resolved when the data has been written to the clipboard. +Note that if the underlying OS does not support multiple native clipboard items on the system clipboard, then only the first {{domxref("ClipboardItem")}} in the array is written. + +The promise is rejected if the clipboard is unable to write to the clipboard. + +### Exceptions + +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if writing to the clipboard is not allowed. + +## Security considerations + +Writing to the clipboard can only be done in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). + +Additional security requirements are covered in the [Security consideration](/en-US/docs/Web/API/Clipboard_API#security_considerations) section of the API overview topic. ## Examples -This example function replaces the current contents of the clipboard with a specified -string. +### Write text to the clipboard + +This example function replaces the current contents of the clipboard with a specified string when a button is pressed. +Note that for this particular case, you could just as readily use `Clipboard.writeText()`. ```js -function setClipboard(text) { +button.addEventListener("click", setClipboard("