diff --git a/files/en-us/web/api/clipboard/index.md b/files/en-us/web/api/clipboard/index.md index 2e1abe142bfeac6..e61348045dade72 100644 --- a/files/en-us/web/api/clipboard/index.md +++ b/files/en-us/web/api/clipboard/index.md @@ -7,17 +7,18 @@ browser-compat: api.Clipboard {{APIRef("Clipboard API")}}{{SecureContext_Header}} -The **`Clipboard`** interface implements the [Clipboard API](/en-US/docs/Web/API/Clipboard_API), providing—if the user grants permission—both read and write access to the contents of the system clipboard. The Clipboard API can be used to implement cut, copy, and paste features within a web application. +The **`Clipboard`** interface of the [Clipboard API](/en-US/docs/Web/API/Clipboard_API) provides read and write access to the contents of the system clipboard. +This allows a web application to implement cut, copy, and paste features. {{InheritanceDiagram}} The system clipboard is exposed through the global {{domxref("Navigator.clipboard")}} property. -Calls to the methods of the `Clipboard` object will not succeed if the user hasn't granted the needed permissions using the [Permissions API](/en-US/docs/Web/API/Permissions_API) and the `'clipboard-read'` or `'clipboard-write'` permission as appropriate. +All of the Clipboard API methods operate asynchronously; they return a {{jsxref("Promise")}} which is resolved once the clipboard access has been completed. +The promise is rejected if clipboard access is denied. -> **Note:** In reality, at this time browser requirements for access to the clipboard vary significantly. Please see the section [Clipboard availability](#clipboard_availability) for details. - -All of the Clipboard API methods operate asynchronously; they return a {{jsxref("Promise")}} which is resolved once the clipboard access has been completed. The promise is rejected if clipboard access is denied. +All the methods require a [secure context](/en-US/docs/Web/Security/Secure_Contexts). +Additional requirements for using the API are discussed in the [Security consideration](/en-US/docs/Web/API/Clipboard_API#security_considerations) section of the API overview topic. ## Instance methods @@ -26,17 +27,11 @@ _`Clipboard` is based on the {{domxref("EventTarget")}} interface, and includes - {{domxref("Clipboard.read()","read()")}} - : Requests arbitrary data (such as images) from the clipboard, returning a {{jsxref("Promise")}} that resolves with an array of {{domxref("ClipboardItem")}} objects containing the clipboard's contents. - {{domxref("Clipboard.readText()","readText()")}} - - : Requests text from the system clipboard; returns a `Promise` which is resolved with a string containing the clipboard's text once it's available. + - : Requests text from the system clipboard, returning a {{jsxref("Promise")}} that is fulfilled with a string containing the clipboard's text once it's available. - {{domxref("Clipboard.write()","write()")}} - - : Writes arbitrary data to the system clipboard. This asynchronous operation signals that it's finished by resolving the returned `Promise`. + - : Writes arbitrary data to the system clipboard, returning a {{jsxref("Promise")}} that resolves when the operation completes. - {{domxref("Clipboard.writeText()","writeText()")}} - - : Writes text to the system clipboard, returning a `Promise` which is resolved once the text is fully copied into the clipboard. - -## Clipboard availability - -The asynchronous clipboard API is a relatively recent addition, and the process of implementing it in browsers is not yet complete. Due to both potential security concerns and technical complexities, the process of integrating this API is happening gradually in most browsers. See the [browser compatibility](#browser_compatibility) section below for more information. - -In browser extensions, you can access the system clipboard using the WebExtension [`clipboard`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/clipboard) API. + - : Writes text to the system clipboard, returning a {{jsxref("Promise")}} that is resolved once the text is fully copied into the clipboard. ## Specifications diff --git a/files/en-us/web/api/clipboard/read/index.md b/files/en-us/web/api/clipboard/read/index.md index 73d3c1c0e7f79eb..47f1199e1c348d5 100644 --- a/files/en-us/web/api/clipboard/read/index.md +++ b/files/en-us/web/api/clipboard/read/index.md @@ -6,18 +6,12 @@ page-type: web-api-instance-method browser-compat: api.Clipboard.read --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} -The **`read()`** method of the -{{domxref("Clipboard")}} interface requests a copy of the clipboard's contents, -delivering the data to the returned {{jsxref("Promise")}} when the promise is -resolved. Unlike {{domxref("Clipboard.readText", "readText()")}}, the -`read()` method can return arbitrary data, such as images. This method can -also return text. +The **`read()`** method of the {{domxref("Clipboard")}} interface requests a copy of the clipboard's contents, fulfilling the returned {{jsxref("Promise")}} with the data. -> **Note:** The asynchronous Clipboard and [Permissions APIs](/en-US/docs/Web/API/Permissions_API) are still in the -> process of being integrated into most browsers, so they often deviate from the -> official rules for permissions and the like. Be sure to review the [compatibility table](#browser_compatibility) before using these methods. +The method can in theory return arbitrary data (unlike {{domxref("Clipboard.readText", "readText()")}}, which can only return text). +Browsers commonly support reading text, HTML, and PNG image data — see [browser compatibility](#browser_compatibility) for more information. ## Syntax @@ -31,37 +25,32 @@ None. ### Return value -A {{jsxref("Promise")}} that resolves with an array of {{domxref("ClipboardItem")}} objects -containing the clipboard's contents. The promise is rejected if permission to access the -clipboard is not granted. +A {{jsxref("Promise")}} that resolves with an array of {{domxref("ClipboardItem")}} objects containing the clipboard's contents. -## Security +### Exceptions -[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. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if the reading from the clipboard is not allowed. -To read from the clipboard, you must first have the `"clipboard-read"` -permission. +## Security considerations -## Examples - -### Reading image data +Reading from the clipboard can only be done in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -This example uses the `read()` method to read image 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. -Try copying the butterfly image on the left using the "Copy image" context menu item, then click in the empty frame on the right. +## Examples -The example will check or ask for permission to read the clipboard, then fetch the image data and display the image data in the empty frame. +### Reading image data from clipboard -> **Note:** At this time, while Firefox does implement -> `read()`, it does not recognize the `"clipboard-read"` -> permission, so attempting to use the [Permissions API](/en-US/docs/Web/API/Permissions_API) to manage access to -> the API will not work. +This example uses the `read()` method to read image data from the clipboard and paste it into an {{HTMLElement("img")}} element. #### HTML ```html A butterfly + +

``` #### CSS @@ -73,39 +62,183 @@ img { margin: 0 1rem; border: 1px solid black; } +#reload { + display: block; + margin: 0 1rem; +} ``` #### JavaScript +This code provides a mechanism to log any errors to the element with id `log`. + +```js +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `Error: ${text}`; +} +``` + +We also add code to reload and clear the example when the "Reload" button is pressed. + +```js +const reload = document.querySelector("#reload"); + +reload.addEventListener("click", () => { + window.location.reload(true); +}); +``` + +The remaining code reads the clipboard when the destination element is clicked and copies the image data into the `destinationImage` element. +It logs an error if it is unable to use the `read()` method, or if the clipboard does not contain data in PNG format. + ```js const destinationImage = document.querySelector("#destination"); destinationImage.addEventListener("click", pasteImage); async function pasteImage() { try { - const permission = await navigator.permissions.query({ - name: "clipboard-read", - }); - if (permission.state === "denied") { - throw new Error("Not allowed to read clipboard."); - } const clipboardContents = await navigator.clipboard.read(); for (const item of clipboardContents) { if (!item.types.includes("image/png")) { - throw new Error("Clipboard contains non-image data."); + throw new Error("Clipboard does not contain PNG image data."); } const blob = await item.getType("image/png"); destinationImage.src = URL.createObjectURL(blob); } } catch (error) { - console.error(error.message); + log(error.message); + } +} +``` + +#### Result + +Copy the butterfly image on the left by right-clicking the image and selecting "Copy image" from the context menu. +Then click on the empty frame on the right. +The example will fetch the image data from the clipboard and display the image in the empty frame. + +{{EmbedLiveSample("Reading image data from clipboard", "100%", "200")}} + +> **Note:** If prompted, grant permission in order to paste the image. + +### Reading data from the clipboard + +This example uses the `read()` method to read data from the clipboard and log whatever data is stored in the clipboard. + +This differs from the previous version in that it will display text, HTML, and image {{domxref("ClipboardItem")}} objects (rather than just images). + +#### HTML + +```html +JPG butterfly image +
Click here to copy clipboard data.
+ +

+``` + +#### CSS + +```css +img { + height: 100px; + width: 100px; + margin: 0 1rem; + border: 1px solid black; +} + +#destination { + min-height: 300px; + min-width: 90%; + margin: 0 1rem; + border: 1px solid black; +} + +#reload { + display: block; + margin: 0 1rem; +} +``` + +#### JavaScript + +This code provides a mechanism to log any errors to the element with id `log`. + +```js +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `Error: ${text}`; +} +``` + +We also add code to reload and clear the example when the "Reload" button is pressed. + +```js +const reload = document.querySelector("#reload"); + +reload.addEventListener("click", () => { + window.location.reload(true); +}); +``` + +The remaining code reads the clipboard when the destination element is clicked and displays each {{domxref("ClipboardItem")}} element along with its MIME type. +It logs an error it is unable to use the `read()` method, or if the clipboard contains any other MIME type. + +```js +const destinationDiv = document.querySelector("#destination"); +destinationDiv.addEventListener("click", pasteData); + +async function pasteData() { + destinationDiv.innerText = ""; //Clear inner text + try { + const clipboardContents = await navigator.clipboard.read(); + for (const item of clipboardContents) { + for (const mimeType of item.types) { + const mimeTypeElement = document.createElement("p"); + mimeTypeElement.innerText = `MIME type: ${mimeType}`; + destinationDiv.appendChild(mimeTypeElement); + if (mimeType === "image/png") { + const pngImage = new Image(); // Image constructor + pngImage.src = "image1.png"; + pngImage.alt = "PNG image from clipboard"; + const blob = await item.getType("image/png"); + pngImage.src = URL.createObjectURL(blob); + destinationDiv.appendChild(pngImage); + } else if (mimeType === "text/html") { + const blob = await item.getType("text/html"); + const blobText = await blob.text(); + const clipHTML = document.createElement("pre"); + clipHTML.innerText = blobText; + destinationDiv.appendChild(clipHTML); + } else if (mimeType === "text/plain") { + const blob = await item.getType("text/plain"); + const blobText = await blob.text(); + const clipPlain = document.createElement("pre"); + clipPlain.innerText = blobText; + destinationDiv.appendChild(clipPlain); + } else { + throw new Error(`${mimeType} not supported.`); + } + } + } + } catch (error) { + log(error.message); } } ``` #### Result -{{EmbedLiveSample("Reading image data")}} +Copy some text or the butterfly (JPG) image below (to copy images right-click on them and then select "Copy image" from the context menu). +Select the indicated frame below to paste this information from the clipboard into the frame. + +{{EmbedLiveSample("Reading data from the clipboard", "100%", "450")}} + +Notes: + +- Even though the butterfly image is a JPG file, when read from the clipboard it is a PNG. +- If prompted, you will need to grant permission in order to paste the image. +- This may not work on chromium browsers as the sample frame is not granted the [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) `clipboard-read` and `clipboard-write` permissions ([required by Chromium browsers](/en-US/docs/Web/API/Clipboard_API#security_considerations)). ## Specifications @@ -119,3 +252,6 @@ async function pasteImage() { - [Clipboard API](/en-US/docs/Web/API/Clipboard_API) - [Image support for Async Clipboard article](https://web.dev/articles/async-clipboard) +- {{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 eb470164a81dce6..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 @@ -62,5 +67,6 @@ navigator.clipboard - [Clipboard API](/en-US/docs/Web/API/Clipboard_API) - [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 2fc45ec3b4a1c53..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("")); + +async function setClipboard(text) { const type = "text/plain"; const blob = new Blob([text], { type }); const data = [new ClipboardItem({ [type]: blob })]; - - navigator.clipboard.write(data).then( - () => { - /* success */ - }, - () => { - /* failure */ - }, - ); + await navigator.clipboard.write(data); } ``` -The code begins by creating a new a {{domxref("Blob")}} object. This object is -required to construct a {{domxref("ClipboardItem")}} object which is sent to the -clipboard. The {{domxref("Blob")}} constructor takes in the content we want to copy -and its type. This {{domxref("Blob")}} object can be derived from many sources; for example, a [canvas](/en-US/docs/Web/API/HTMLCanvasElement). +The `setClipboard()` method begins by creating a new a {{domxref("Blob")}} object. +This object is required to construct a {{domxref("ClipboardItem")}} object which is sent to the clipboard. +The {{domxref("Blob")}} constructor takes in the content we want to copy and its type. +This {{domxref("Blob")}} object can be derived from many sources; for example, a [canvas](/en-US/docs/Web/API/HTMLCanvasElement). Next, we create a new {{domxref("ClipboardItem")}} object into which the blob will be placed for sending to the clipboard. -The key of the object passed to the {{domxref("ClipboardItem")}} constructor indicates the content type, the value indicates the content. Then `write()` is called, specifying both a fulfillment function -and an error function. +The key of the object passed to the {{domxref("ClipboardItem")}} constructor indicates the content type, the value indicates the content. +Then `write()` is called with `await`. +A `try..catch` block could be used to catch any errors writing the data. + +### Write canvas contents to the clipboard -### Example of copying canvas contents to the clipboard +This example writes the canvas to a blob, using the default MIME type of `image/png`, and then writes the blob to the clipboard. ```js -function copyCanvasContentsToClipboard(canvas, onDone, onError) { - canvas.toBlob((blob) => { - let data = [new ClipboardItem({ [blob.type]: blob })]; - - navigator.clipboard.write(data).then( - () => { - onDone(); - }, - (err) => { - onError(err); - }, - ); - }); +// Get canvas can add an event handler for the click event. +const canvas = document.getElementById("canvas"); +canvas.addEventListener("click", copyCanvasContentsToClipboard()); + +async function copyCanvasContentsToClipboard() { + // Copy canvas to blob + const blob = await canvas.toBlob(); + // Create ClipboardItem with blob and it's type, and add to an array + const data = [new ClipboardItem({ [blob.type]: blob })]; + // Write the data to the clipboard + await navigator.clipboard.write(data); } ``` -> **Note:** You can only pass in one clipboard item at a time. - ## Specifications {{Specifications}} @@ -104,3 +102,6 @@ function copyCanvasContentsToClipboard(canvas, onDone, onError) { - [Clipboard API](/en-US/docs/Web/API/Clipboard_API) - [Image support for Async Clipboard article](https://web.dev/articles/async-clipboard) +- {{domxref("Clipboard.writeText()")}} +- {{domxref("Clipboard.read()")}} +- {{domxref("Clipboard.readText()")}} diff --git a/files/en-us/web/api/clipboard/writetext/index.md b/files/en-us/web/api/clipboard/writetext/index.md index bef7d3a6809e276..4b81cd4f897834a 100644 --- a/files/en-us/web/api/clipboard/writetext/index.md +++ b/files/en-us/web/api/clipboard/writetext/index.md @@ -6,12 +6,9 @@ page-type: web-api-instance-method browser-compat: api.Clipboard.writeText --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} -The {{domxref("Clipboard")}} interface's **`writeText()`** -property writes the specified text string to the system clipboard. Text may be read back -using either {{domxref("Clipboard.read", "read()")}} or {{domxref("Clipboard.readText", - "readText()")}}. +The **`writeText()`** method of the {{domxref("Clipboard")}} interface writes the specified text to the system clipboard, returning a {{jsxref("Promise")}} that is resolved once the system clipboard has been updated. ## Syntax @@ -26,29 +23,33 @@ writeText(newClipText) ### Return value -A {{jsxref("Promise")}} which is resolved once the clipboard's contents have been -updated. The promise is rejected if the caller does not have permission to write to the -clipboard. +A {{jsxref("Promise")}} that is resolved once the clipboard's contents have been updated. -## Security +### Exceptions -[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. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if writing to the clipboard is not allowed. -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. +## 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 sets the clipboard's contents to the string "\". ```js -navigator.clipboard.writeText("").then( - () => { - /* clipboard successfully set */ - }, - () => { - /* clipboard write failed */ - }, -); +button.addEventListener("click", writeClipboardText("")); + +async function writeClipboardText(text) { + try { + await navigator.clipboard.writeText(text); + } catch (error) { + console.error(error.message); + } +} ``` ## Specifications @@ -63,3 +64,6 @@ navigator.clipboard.writeText("").then( - [Clipboard API](/en-US/docs/Web/API/Clipboard_API) - [Image support for Async Clipboard article](https://web.dev/articles/async-clipboard) +- {{domxref("Clipboard.write()")}} +- {{domxref("Clipboard.read()")}} +- {{domxref("Clipboard.readText()")}} diff --git a/files/en-us/web/api/clipboard_api/index.md b/files/en-us/web/api/clipboard_api/index.md index a2801c4dca8975a..da1999c6c2a1b89 100644 --- a/files/en-us/web/api/clipboard_api/index.md +++ b/files/en-us/web/api/clipboard_api/index.md @@ -10,20 +10,91 @@ browser-compat: {{DefaultAPISidebar("Clipboard API")}} -The **Clipboard API** provides the ability to respond to clipboard commands (cut, copy, and paste) as well as to asynchronously read from and write to the system clipboard. +The **Clipboard API** provides the ability to respond to clipboard commands (cut, copy, and paste), as well as to asynchronously read from and write to the system clipboard. + +> **Note:** Use this API in preference to the deprecated {{domxref("document.execCommand()")}} method for accessing the clipboard. > **Note:** This API is _not available_ in [Web Workers](/en-US/docs/Web/API/Web_Workers_API) (not exposed via {{domxref("WorkerNavigator")}}). -This API is designed to supersede accessing the clipboard using {{domxref("document.execCommand()")}}. +## Concepts and usage + +The _system clipboard_ is a data buffer belonging to the operating system hosting the browser, which is used for short-term data storage and/or data transfers between documents or applications. +It is usually implemented as an anonymous, temporary [data buffer](https://en.wikipedia.org/wiki/Data_buffer), sometimes called the _paste buffer_, that can be accessed from most or all programs within the environment via defined programming interfaces. + +The Clipboard API allows users to programmatically read and write text and other kinds of data to and from the system clipboard in [secure contexts](/en-US/docs/Web/Security/Secure_Contexts), provided the user has met the criteria outlined in the [Security considerations](#security_considerations). + +Events are fired as the result of {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and {{domxref("Element/paste_event", "paste")}} operations modifying the clipboard. +The events have a default action, for example the `copy` action copies the current selection to the system clipboard by default. +The default action can be overriden by the event handler — see each of the events for more information. + +## Interfaces + +- {{domxref("Clipboard")}} {{securecontext_inline}} + - : Provides an interface for reading and writing text and data to or from the system clipboard. + The specification refers to this as the 'Async Clipboard API'. +- {{domxref("ClipboardEvent")}} + - : Represents events providing information related to modification of the clipboard, that is {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and {{domxref("Element/paste_event", "paste")}} events. + The specification refers to this as the 'Clipboard Event API'. +- {{domxref("ClipboardItem")}} {{securecontext_inline}} + - : Represents a single item format, used when reading or writing data. + +### Extensions to other interfaces + +The Clipboard API extends the following APIs, adding the listed features. + +- {{domxref("Navigator.clipboard")}} {{readonlyinline}} {{securecontext_inline}} + - : Returns a {{domxref("Clipboard")}} object that provides read and write access to the system clipboard. +- [`Element: copy`](/en-US/docs/Web/API/Element/copy_event) event + - : An event fired whenever the user initiates a copy action. +- [`Element: cut`](/en-US/docs/Web/API/Element/cut_event) event + - : An event fired whenever the user initiates a cut action. +- [`Element: paste`](/en-US/docs/Web/API/Element/cut_event) event + - : An event fired whenever the user initiates a paste action. + + + +## Security considerations + +The Clipboard API allows users to programmatically read and write text and other kinds of data to and from the system clipboard in [secure contexts](/en-US/docs/Web/Security/Secure_Contexts). -> **Note:** The **clipboard** is a data buffer that is used for short-term, data storage and/or data transfers, this can be between documents or applications. -> It is usually implemented as an anonymous, temporary [data buffer](https://en.wikipedia.org/wiki/Data_buffer), sometimes called the paste buffer, that can be accessed from most or all programs within the environment via defined [programming interfaces](https://en.wikipedia.org/wiki/Application_programming_interface). -> -> A typical application accesses clipboard functionality by mapping [user input](https://en.wikipedia.org/wiki/User_input) such as [keybindings](https://en.wikipedia.org/wiki/Keybinding), [menu selections](), etc. to these interfaces. +The specification requires that a user has recently interacted with the page in order to read from the clipboard ([transient user activation](/en-US/docs/Web/Security/User_activation) is required). +If the read operation is caused by user interaction with a browser or OS "paste element" (such as a context menu), the browser is expected to prompt the user for acknowledgement. +For writing to the clipboard the specification expects that the page has been granted the [Permissions API](/en-US/docs/Web/API/Permissions_API) `clipboard-write` permission, and the browser may also require [transient user activation](/en-US/docs/Web/Security/User_activation). +Browsers may place additional restrictions over use of the methods to access the clipboard. -## Accessing the clipboard +Browser implementations have diverged from the specification. +The differences are captured in the [Browser compatibility](#browser_compatibility) section and the current state is summarized below: -Instead of creating a `Clipboard` object through instantiation, you access the system clipboard through the {{domxref("Navigator.clipboard")}} global: +Chromium browsers: + +- Reading requires the [Permissions API](/en-US/docs/Web/API/Permissions_API) `clipboard-read` permission be granted. + Transient activation is not required. +- Writing requires either the `clipboard-read` permission or transient activation. + If the permission is granted, it persists, and further transient activation is not required. +- The HTTP [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) permissions `clipboard-read` and `clipboard-write` must be allowed for {{HTMLElement("iframe")}} elements that access the clipboard. +- No persistent paste-prompt is displayed when a read operation is caused by a browser or OS "paste element". + +Firefox & Safari: + +- Reading and writing require transient activation. +- The paste-prompt is is suppressed if reading same-origin clipboard content, but not cross-origin content. +- The `clipboard-read` and `clipboard-write` permissions are not supported (and not planned to be supported) by Firefox or Safari. + +Firefox [Web Extensions](/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard): + +- Reading text is only available for extensions with the Web Extension [`clipboardRead`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#clipboardread) permission. + With this permission the extension does not require transient activation or a paste prompt. +- Writing text is available in secure context and with transient activation. + With the Web Extension [`clipboardWrite`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#clipboardwrite) permission transient activation is not required. + +## Examples + +### Accessing the clipboard + +The system clipboard is accessed through the {{domxref("Navigator.clipboard")}} global. + +This snippet fetches the text from the clipboard and appends it to the first element found with the class `editor`. +Since {{domxref("Clipboard.readText", "readText()")}} (and {{domxref("Clipboard.read", "read()")}}, for that matter) returns an empty string if the clipboard isn't text, this code is safe. ```js navigator.clipboard @@ -33,17 +104,6 @@ navigator.clipboard ); ``` -This snippet fetches the text from the clipboard and appends it to the first element found with the class `editor`. Since {{domxref("Clipboard.readText", "readText()")}} (and {{domxref("Clipboard.read", "read()")}}, for that matter) returns an empty string if the clipboard isn't text, this code is safe. - -## Interfaces - -- {{domxref("Clipboard")}} {{securecontext_inline}} - - : Provides an interface for reading and writing text and data to or from the system clipboard. The specification refers to this as the 'Async Clipboard API'. -- {{domxref("ClipboardEvent")}} - - : Represents events providing information related to modification of the clipboard, that is {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and {{domxref("Element/paste_event", "paste")}} events. The specification refers to this as the 'Clipboard Event API'. -- {{domxref("ClipboardItem")}} {{securecontext_inline}} - - : Represents a single item format, used when reading or writing data. - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/clipboardevent/clipboarddata/index.md b/files/en-us/web/api/clipboardevent/clipboarddata/index.md index 68bfe307bf0607a..fd2fb95269df3a3 100644 --- a/files/en-us/web/api/clipboardevent/clipboarddata/index.md +++ b/files/en-us/web/api/clipboardevent/clipboarddata/index.md @@ -8,16 +8,12 @@ browser-compat: api.ClipboardEvent.clipboardData {{APIRef("Clipboard API")}} -The **`ClipboardEvent.clipboardData`** property holds a {{domxref("DataTransfer")}} object, which can be used: +The **`clipboardData`** property of the {{domxref("ClipboardEvent")}} interface holds a {{domxref("DataTransfer")}} object, which can be used to: -- to specify what data should be put into the clipboard from the {{domxref("Element/cut_event", "cut")}} and - {{domxref("Element/copy_event", "copy")}} event handlers, typically with a {{domxref("DataTransfer.setData", - "setData(format, data)")}} call; -- to obtain the data to be pasted from the {{domxref("Element/paste_event", "paste")}} event handler, typically - with a {{domxref("DataTransfer.getData", "getData(format)")}} call. +- specify what data should be put into the clipboard from the {{domxref("Element/cut_event", "cut")}} and {{domxref("Element/copy_event", "copy")}} event handlers, typically with a {{domxref("DataTransfer.setData", "setData(format, data)")}} call; +- obtain the data to be pasted from the {{domxref("Element/paste_event", "paste")}} event handler, typically with a {{domxref("DataTransfer.getData", "getData(format)")}} call. -See the {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and {{domxref("Element/paste_event", "paste")}} events -documentation for more information. +See the {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and {{domxref("Element/paste_event", "paste")}} events documentation for more information. ## Value diff --git a/files/en-us/web/api/clipboardevent/clipboardevent/index.md b/files/en-us/web/api/clipboardevent/clipboardevent/index.md index bd83f7c3d7f5476..a082297e8220313 100644 --- a/files/en-us/web/api/clipboardevent/clipboardevent/index.md +++ b/files/en-us/web/api/clipboardevent/clipboardevent/index.md @@ -8,10 +8,7 @@ browser-compat: api.ClipboardEvent.ClipboardEvent {{APIRef("Clipboard API")}} -The **`ClipboardEvent()`** constructor returns a new {{domxref("ClipboardEvent")}}, -representing an event providing information related to modification of the clipboard, -that is {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and -{{domxref("Element/paste_event", "paste")}} events. +The **`ClipboardEvent()`** constructor returns a new {{domxref("ClipboardEvent")}}, representing an event providing information related to modification of the clipboard, that is {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and {{domxref("Element/paste_event", "paste")}} events. ## Syntax diff --git a/files/en-us/web/api/clipboardevent/index.md b/files/en-us/web/api/clipboardevent/index.md index 5ffcc20d670a37d..a3ece80eadd2e63 100644 --- a/files/en-us/web/api/clipboardevent/index.md +++ b/files/en-us/web/api/clipboardevent/index.md @@ -7,7 +7,7 @@ browser-compat: api.ClipboardEvent {{APIRef("Clipboard API")}} -The **`ClipboardEvent`** interface represents events providing information related to modification of the clipboard, that is {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and {{domxref("Element/paste_event", "paste")}} events. +The **`ClipboardEvent`** interface of the [Clipboard API](/en-US/docs/Web/API/Clipboard_API) represents events providing information related to modification of the clipboard, that is {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}}, and {{domxref("Element/paste_event", "paste")}} events. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/clipboarditem/clipboarditem/index.md b/files/en-us/web/api/clipboarditem/clipboarditem/index.md index 3b7ec7be543637d..23e03b2ec95339e 100644 --- a/files/en-us/web/api/clipboarditem/clipboarditem/index.md +++ b/files/en-us/web/api/clipboarditem/clipboarditem/index.md @@ -6,9 +6,9 @@ page-type: web-api-constructor browser-compat: api.ClipboardItem.ClipboardItem --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} -The **`ClipboardItem()`** constructor of the {{domxref("Clipboard API")}} creates a new {{domxref("ClipboardItem")}} object which represents data to be stored or retrieved via the {{domxref("Clipboard API")}}, that is {{domxref("clipboard.write()")}} and {{domxref("clipboard.read()")}} respectively. +The **`ClipboardItem()`** constructor creates a new {{domxref("ClipboardItem")}} object, which represents data to be stored or retrieved via the [Clipboard API](/en-US/docs/Web/API/Clipboard_API) {{domxref("clipboard.write()")}} and {{domxref("clipboard.read()")}} methods, respectively. > **Note:** Image format support varies by browser. See the browser compatibility table for the {{domxref("Clipboard")}} interface. @@ -22,18 +22,20 @@ new ClipboardItem(data, options) ### Parameters - `data` - - : An {{jsxref("Object")}} with the {{Glossary("MIME type")}} as the key and data as the value. The data can be represented as a {{domxref("Blob")}}, a {{jsxref("String")}} or a {{jsxref("Promise")}} which resolves to either a blob or string. + - : An {{jsxref("Object")}} with the {{Glossary("MIME type")}} as the key and data as the value. + The data can be represented as a {{domxref("Blob")}}, a {{jsxref("String")}} or a {{jsxref("Promise")}} which resolves to either a blob or string. - `options` {{optional_inline}} - : An object with the following properties: - `presentationStyle` {{optional_inline}} - - : One of the three strings: `unspecified`, `inline` or `attachment`. The default is `unspecified`. + - : One of the three strings: `unspecified`, `inline` or `attachment`. + The default is `unspecified`. -> **Note:** You can also work with text via the {{domxref("Clipboard.readText()")}} and {{domxref("Clipboard.writeText()")}} methods of the {{domxref("Clipboard")}} -> interface. +> **Note:** You can also work with text via the {{domxref("Clipboard.readText()")}} and {{domxref("Clipboard.writeText()")}} methods of the {{domxref("Clipboard")}} interface. ## Examples -The below example requests a png image using the {{domxref("Fetch API")}}, and in turn, the {{domxref("Response.blob()", "responses' blob()")}} method, to create a new {{domxref("ClipboardItem")}}. This item is then written to the clipboard, using the {{domxref("Clipboard.write()")}} method. +The below example requests a PNG image using the {{domxref("Fetch API")}}, and in turn, the {{domxref("Response.blob()", "responses' blob()")}} method, to create a new {{domxref("ClipboardItem")}}. +This item is then written to the clipboard, using the {{domxref("Clipboard.write()")}} method. > **Note:** You can only pass in one clipboard item at a time. diff --git a/files/en-us/web/api/clipboarditem/gettype/index.md b/files/en-us/web/api/clipboarditem/gettype/index.md index 70bd915f9846175..bdf857c9a5a4e44 100644 --- a/files/en-us/web/api/clipboarditem/gettype/index.md +++ b/files/en-us/web/api/clipboarditem/gettype/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.ClipboardItem.getType --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} The **`getType()`** method of the {{domxref("ClipboardItem")}} interface returns a {{jsxref("Promise")}} that resolves with a {{domxref("Blob")}} of the requested {{Glossary("MIME type")}} or an error if the MIME type is not found. @@ -30,15 +30,12 @@ A {{jsxref("Promise")}} that resolves with a {{domxref("Blob")}} object. - `NotFoundError` {{domxref("DOMException")}} - : The `type` does not match a known {{Glossary("MIME type")}}. - {{jsxref("TypeError")}} - - : No parameter is specified or the `type` is not that of the - {{domxref("ClipboardItem")}}. + - : No parameter is specified or the `type` is not that of the {{domxref("ClipboardItem")}}. ## Examples -In the following example, we're returning all items on the clipboard via the -{{domxref("clipboard.read()")}} method. Then utilizing the -{{domxref("ClipboardItem.types")}} property to set the `getType()` argument -and return the corresponding blob object. +In the following example, we're returning all items on the clipboard via the {{domxref("clipboard.read()")}} method. +Then utilizing the {{domxref("ClipboardItem.types")}} property to set the `getType()` argument and return the corresponding blob object. ```js async function getClipboardContents() { diff --git a/files/en-us/web/api/clipboarditem/index.md b/files/en-us/web/api/clipboarditem/index.md index f5c803d92138272..87a5aec9f08c697 100644 --- a/files/en-us/web/api/clipboarditem/index.md +++ b/files/en-us/web/api/clipboarditem/index.md @@ -7,16 +7,12 @@ browser-compat: api.ClipboardItem {{APIRef("Clipboard API")}}{{SecureContext_Header}} -The **`ClipboardItem`** interface of the {{domxref('Clipboard API')}} represents a single item format, used when reading or writing data via the {{domxref('Clipboard API')}}. That is {{domxref("clipboard.read()")}} and {{domxref("clipboard.write()")}} respectively. +The **`ClipboardItem`** interface of the [Clipboard API](/en-US/docs/Web/API/Clipboard_API) represents a single item format, used when reading or writing clipboard data using {{domxref("clipboard.read()")}} and {{domxref("clipboard.write()")}} respectively. -The benefit of having the **`ClipboardItem`** interface to represent data, is that it enables developers to cope with the varying scope of file types and data easily. - -Access to the contents of the clipboard is gated behind the [Permissions API](/en-US/docs/Web/API/Permissions_API): The `clipboard-write` permission is granted automatically to pages when they are in the active tab. The `clipboard-read` permission must be requested, which you can do by trying to read data from the clipboard. +The benefit of having the **`ClipboardItem`** interface to represent data, is that it enables developers to cope with the varying scope of file types and data. > **Note:** To work with text see the {{domxref("Clipboard.readText()")}} and {{domxref("Clipboard.writeText()")}} methods of the {{domxref("Clipboard")}} interface. -> **Note:** You can only pass in one clipboard item at a time. - ## Constructor - {{domxref("ClipboardItem.ClipboardItem", "ClipboardItem()")}} @@ -40,9 +36,9 @@ _This interface defines the following methods._ ## Examples -### Writing To Clipboard +### Writing to the clipboard -Here we're writing a new {{domxref("ClipboardItem.ClipboardItem", "ClipboardItem()")}} to the {{domxref("Clipboard API", "clipboard")}} by requesting a png image using the {{domxref("Fetch API")}}, and in turn, the {{domxref("Response.blob()", "responses' blob()")}} method, to create the new {{domxref("ClipboardItem")}}. +Here we're writing a new {{domxref("ClipboardItem.ClipboardItem", "ClipboardItem()")}} to the system clipboard by requesting a PNG image using the {{domxref("Fetch API")}}, and in turn, the {{domxref("Response.blob()", "responses' blob()")}} method, to create the new `ClipboardItem`. ```js async function writeClipImg() { @@ -63,9 +59,10 @@ async function writeClipImg() { } ``` -### Reading From The Clipboard +### Reading from the clipboard -Here we're returning all items on the clipboard via the {{domxref("clipboard.read()")}} method. Then utilizing the {{domxref("ClipboardItem.types")}} property to set the {{domxref("ClipboardItem.getType", "getType()")}} argument and return the corresponding blob object. +Here we're returning all items on the clipboard via the {{domxref("clipboard.read()")}} method. +Then utilizing the {{domxref("ClipboardItem.types")}} property to set the {{domxref("ClipboardItem.getType", "getType()")}} argument and return the corresponding blob object. ```js async function getClipboardContents() { diff --git a/files/en-us/web/api/clipboarditem/presentationstyle/index.md b/files/en-us/web/api/clipboarditem/presentationstyle/index.md index dd69cfc5635af6f..3304cdd1b2f73c9 100644 --- a/files/en-us/web/api/clipboarditem/presentationstyle/index.md +++ b/files/en-us/web/api/clipboarditem/presentationstyle/index.md @@ -6,11 +6,11 @@ page-type: web-api-instance-property browser-compat: api.ClipboardItem.presentationStyle --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} -The read-only -**`presentationStyle`** property of the {{domxref("ClipboardItem")}} -interface returns a string indicating how an item should be presented. +The read-only **`presentationStyle`** property of the {{domxref("ClipboardItem")}} interface returns a string indicating how an item should be presented. + +For example, in some contexts an image might be displayed inline, while in others it might be represented as an attachment. ## Value diff --git a/files/en-us/web/api/clipboarditem/types/index.md b/files/en-us/web/api/clipboarditem/types/index.md index 4d18b6c0e84cf26..4b823e3a8ec5ab5 100644 --- a/files/en-us/web/api/clipboarditem/types/index.md +++ b/files/en-us/web/api/clipboarditem/types/index.md @@ -6,12 +6,9 @@ page-type: web-api-instance-property browser-compat: api.ClipboardItem.types --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} -The read-only -**`types`** property of the {{domxref("ClipboardItem")}} -interface returns an {{jsxref("Array")}} of {{Glossary("MIME type", 'MIME types')}} -available within the {{domxref("ClipboardItem")}} +The read-only **`types`** property of the {{domxref("ClipboardItem")}} interface returns an {{jsxref("Array")}} of {{Glossary("MIME type", 'MIME types')}} available within the {{domxref("ClipboardItem")}} ## Value @@ -19,11 +16,8 @@ An {{jsxref("Array")}} of available {{Glossary("MIME type", 'MIME types')}}. ## Examples -In the below example, we're returning all items on the clipboard via the -{{domxref("clipboard.read()")}} method. Then checking the `types` property -for available types before utilizing the {{domxref("ClipboardItem.getType()")}} method -to return the {{domxref("Blob")}} object. If no clipboards contents is found for the -specified type, an error is returned. +In the below example, we're returning all items on the clipboard via the {{domxref("Clipboard.read()")}} method. +Then checking the `types` property for available types before utilizing the {{domxref("ClipboardItem.getType()")}} method to return the {{domxref("Blob")}} object. If no clipboards contents is found for the specified type, an error is returned. ```js async function getClipboardContents() { diff --git a/files/en-us/web/api/element/copy_event/index.md b/files/en-us/web/api/element/copy_event/index.md index c1d54ce6f82160c..3074f4dbbaca4b3 100644 --- a/files/en-us/web/api/element/copy_event/index.md +++ b/files/en-us/web/api/element/copy_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.copy_event {{APIRef}} -The **`copy`** event fires when the user initiates a copy action through the browser's user interface. +The **`copy`** event of the [Clipboard API](/en-US/docs/Web/API/Clipboard_API) fires when the user initiates a copy action through the browser's user interface. The event's default action is to copy the selection (if any) to the clipboard. @@ -18,6 +18,8 @@ However, the handler cannot _read_ the clipboard data. It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `copy` event, but this will not affect the system clipboard. +This event [bubbles](/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling_and_capture), is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/cut_event/index.md b/files/en-us/web/api/element/cut_event/index.md index 57ab26497d7f10c..95a848a42dca2a7 100644 --- a/files/en-us/web/api/element/cut_event/index.md +++ b/files/en-us/web/api/element/cut_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.cut_event {{APIRef}} -The **`cut`** event is fired when the user has initiated a "cut" action through the browser's user interface. +The **`cut`** event of the [Clipboard API](/en-US/docs/Web/API/Clipboard_API) is fired when the user has initiated a "cut" action through the browser's user interface. If the user attempts a cut action on uneditable content, the `cut` event still fires but the event object contains no data. @@ -22,6 +22,8 @@ The handler cannot _read_ the clipboard data. It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `cut` event, but this will not affect the system clipboard or the document's contents. +This event [bubbles](/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling_and_capture), is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/paste_event/index.md b/files/en-us/web/api/element/paste_event/index.md index 01ee8294c4dde6f..18a3edf74afb43f 100644 --- a/files/en-us/web/api/element/paste_event/index.md +++ b/files/en-us/web/api/element/paste_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.paste_event {{APIRef}} -The **`paste`** event is fired when the user has initiated a "paste" action through the browser's user interface. +The **`paste`** event of the [Clipboard API](/en-US/docs/Web/API/Clipboard_API) is fired when the user has initiated a "paste" action through the browser's user interface. If the cursor is in an editable context (for example, in a {{HTMLElement("textarea")}} or an element with [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set to `true`) then the default action is to insert the contents of the clipboard into the document at the cursor position. @@ -18,6 +18,8 @@ To override the default behavior (for example to insert some different data or a It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `paste` event, but this will not affect the document's contents. +This event [bubbles](/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling_and_capture), is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/navigator/clipboard/index.md b/files/en-us/web/api/navigator/clipboard/index.md index 5c2b0e9d230e56a..cdebf2521a7d264 100644 --- a/files/en-us/web/api/navigator/clipboard/index.md +++ b/files/en-us/web/api/navigator/clipboard/index.md @@ -6,20 +6,11 @@ page-type: web-api-instance-property browser-compat: api.Navigator.clipboard --- -{{APIRef("Clipboard API")}} +{{APIRef("Clipboard API")}} {{securecontext_header}} -The [Clipboard API](/en-US/docs/Web/API/Clipboard_API) adds to the **{{domxref("Navigator")}}** interface the -read-only **`clipboard`** property, which returns the -{{domxref("Clipboard")}} object used to read and write the clipboard's -contents. +The **`clipboard`** read-only property of the {{domxref("Navigator")}} interface returns a {{domxref("Clipboard")}} object used to read and write the clipboard's contents. -The Clipboard API can be used to implement cut, copy, and paste -features within a web application. - -Use of the asynchronous clipboard read and write methods requires that the user grant -the website or app permission to access the clipboard. This permission must be obtained -from the [Permissions API](/en-US/docs/Web/API/Permissions_API) using the -`"clipboard-read"` and/or `"clipboard-write"` permissions. +This is the entry point to the [Clipboard API](/en-US/docs/Web/API/Clipboard_API), which can be used to implement cut, copy, and paste features within a web application. ## Value @@ -27,8 +18,7 @@ The {{domxref("Clipboard")}} object used to access the system clipboard. ## Examples -The following code uses `navigator.clipboard` to access the system clipboard -in order to read the contents of the clipboard. +The following code uses `navigator.clipboard` to access the system clipboard in order to read text contents from the clipboard. ```js navigator.clipboard @@ -38,15 +28,11 @@ navigator.clipboard ); ``` -This snippet replaces the contents of the element whose class is -`"cliptext"` with the text contents of the clipboard. Perhaps this code is -being used in a browser extension that displays the current clipboard contents, -automatically updating periodically or when specific events fire. +This snippet replaces the contents of the element whose class is `"cliptext"` with the text contents of the clipboard. +Perhaps this code is being used in a browser extension that displays the current clipboard contents, automatically updating periodically or when specific events fire. -If the clipboard is empty or doesn't contain text, the `"cliptext"` -element's contents are cleared. This happens because {{domxref("Clipboard.readText", - "readText()")}} returns an empty string if the clipboard is empty or doesn't contain -text. +If the clipboard is empty or doesn't contain text, the `"cliptext"` element's contents are cleared. +This happens because {{domxref("Clipboard.readText", "readText()")}} returns an empty string if the clipboard is empty or doesn't contain text. ## Specifications diff --git a/files/en-us/web/api/navigator/index.md b/files/en-us/web/api/navigator/index.md index 2e5d24379df6e6d..05c0af0a7090c54 100644 --- a/files/en-us/web/api/navigator/index.md +++ b/files/en-us/web/api/navigator/index.md @@ -19,7 +19,7 @@ _Doesn't inherit any properties._ - {{domxref("Navigator.bluetooth")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("Bluetooth")}} object for the current document, providing access to [Web Bluetooth API](/en-US/docs/Web/API/Web_Bluetooth_API) functionality. -- {{domxref("Navigator.clipboard")}} {{ReadOnlyInline}} +- {{domxref("Navigator.clipboard")}} {{ReadOnlyInline}} {{securecontext_inline}} - : Returns a {{domxref("Clipboard")}} object that provides read and write access to the system clipboard. - {{domxref("Navigator.connection")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("NetworkInformation")}} object containing information about the network connection of a device. diff --git a/files/en-us/web/api/permissions_api/index.md b/files/en-us/web/api/permissions_api/index.md index d381b1c44a6c4d2..43ded618e43e548 100644 --- a/files/en-us/web/api/permissions_api/index.md +++ b/files/en-us/web/api/permissions_api/index.md @@ -33,7 +33,6 @@ Not all APIs' permission statuses can be queried using the Permissions API. A non-exhaustive list of permission-aware APIs includes: - [Background Synchronization API](/en-US/docs/Web/API/Background_Synchronization_API): `background-sync` (should always be granted) -- [Clipboard API](/en-US/docs/Web/API/Clipboard_API): `clipboard-read`, `clipboard-write` - [Geolocation API](/en-US/docs/Web/API/Geolocation_API): `geolocation` - [Local Font Access API](/en-US/docs/Web/API/Local_Font_Access_API): `local-fonts` - [Media Capture and Streams API](/en-US/docs/Web/API/Media_Capture_and_Streams_API): `microphone`, `camera` diff --git a/files/en-us/web/security/user_activation/index.md b/files/en-us/web/security/user_activation/index.md index fd60a1a89c66372..4170be0ad79dbaf 100644 --- a/files/en-us/web/security/user_activation/index.md +++ b/files/en-us/web/security/user_activation/index.md @@ -32,6 +32,7 @@ APIs that require transient activation (list is not exhaustive): - {{domxref("Clients.openWindow()")}} - {{domxref("Clipboard.read()")}} - {{domxref("Clipboard.readText()")}} +- {{domxref("Clipboard.write()")}} - {{domxref("Clipboard.writeText()")}} - {{domxref("ContactsManager.select()")}} - {{domxref("Document.requestStorageAccess()")}} diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index ff5006def2f9c6b..e0145f3f9736c98 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -142,18 +142,10 @@ }, "Clipboard API": { "overview": ["Clipboard API"], - "guides": [ - "/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard" - ], "interfaces": ["Clipboard", "ClipboardEvent", "ClipboardItem"], "methods": [], "properties": ["Navigator.clipboard"], - "events": [ - "Window: clipboardchange", - "Element: copy", - "Element: cut", - "Element: paste" - ] + "events": ["Element: copy", "Element: cut", "Element: paste"] }, "Compression Streams API": { "overview": ["Compression Streams API"],