FF122 Clipboard API

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
 

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
 <img id="source" src="butterfly.jpg" alt="A butterfly" />
 <img id="destination" />
+<button id="reload" type="button">Reload</button>
+<p id="log"></p>
 ```
 
 #### 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
+<img id="source_jpg" src="butterfly.jpg" alt="JPG butterfly image" />
+<div id="destination">Click here to copy clipboard data.</div>
+<button id="reload" type="button">Reload</button>
+<p id="log"></p>
+```
+
+#### 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()")}}

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()")}}