From df4929e1b1795f3f8856567bf23c543ea381e00e Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Thu, 16 Jan 2025 15:45:01 +0000 Subject: [PATCH 1/6] Update clipboard API docs to better represent ClipboardItem with string item data --- files/en-us/web/api/clipboard/read/index.md | 4 +- .../en-us/web/api/clipboard/readtext/index.md | 2 +- files/en-us/web/api/clipboard/write/index.md | 22 ++++----- files/en-us/web/api/clipboard_api/index.md | 2 +- .../api/clipboarditem/clipboarditem/index.md | 10 ++-- .../web/api/clipboarditem/gettype/index.md | 3 +- files/en-us/web/api/clipboarditem/index.md | 46 +++++++++++++------ .../clipboarditem/supports_static/index.md | 6 +-- .../web/api/clipboarditem/types/index.md | 5 +- 9 files changed, 57 insertions(+), 43 deletions(-) diff --git a/files/en-us/web/api/clipboard/read/index.md b/files/en-us/web/api/clipboard/read/index.md index fe85ff150ec20f0..e2a687f2a403c1c 100644 --- a/files/en-us/web/api/clipboard/read/index.md +++ b/files/en-us/web/api/clipboard/read/index.md @@ -11,7 +11,7 @@ browser-compat: api.Clipboard.read The **`read()`** method of the {{domxref("Clipboard")}} interface requests a copy of the clipboard's contents, fulfilling the returned {{jsxref("Promise")}} with the data. 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. +Browsers commonly support reading text, HTML, and PNG image data. ## Syntax @@ -136,7 +136,7 @@ The example will fetch the image data from the clipboard and display the image i 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). +This differs from the previous version in that it will display text, image, and other {{domxref("Blob")}}-type {{domxref("ClipboardItem")}} objects (rather than just images). #### HTML diff --git a/files/en-us/web/api/clipboard/readtext/index.md b/files/en-us/web/api/clipboard/readtext/index.md index f3e3106d03b990d..48dda6c9874ae81 100644 --- a/files/en-us/web/api/clipboard/readtext/index.md +++ b/files/en-us/web/api/clipboard/readtext/index.md @@ -8,7 +8,7 @@ browser-compat: api.Clipboard.readText {{APIRef("Clipboard API")}} {{securecontext_header}} -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. +The **`readText()`** method of the {{domxref("Clipboard")}} interface returns a {{jsxref("Promise")}} which fulfills 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. diff --git a/files/en-us/web/api/clipboard/write/index.md b/files/en-us/web/api/clipboard/write/index.md index 7addbf3ac671b59..2179e5ea4e8e36a 100644 --- a/files/en-us/web/api/clipboard/write/index.md +++ b/files/en-us/web/api/clipboard/write/index.md @@ -8,11 +8,11 @@ browser-compat: api.Clipboard.write {{APIRef("Clipboard API")}} {{securecontext_header}} -The **`write()`** method of the {{domxref("Clipboard")}} interface writes arbitrary data to the clipboard, such as images, fulfilling the returned {{jsxref("Promise")}} on completion. +The **`write()`** method of the {{domxref("Clipboard")}} interface writes arbitrary {{domxref("Blob")}}-type data (such as images) and text to the clipboard, fulfilling the returned {{jsxref("Promise")}} on completion. This can be used to implement cut and copy functionality. 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. +Browsers commonly support writing text, HTML, and PNG image data. ## Syntax @@ -55,21 +55,17 @@ button.addEventListener("click", () => setClipboard("")); async function setClipboard(text) { const type = "text/plain"; - const blob = new Blob([text], { type }); - const data = [new ClipboardItem({ [type]: blob })]; - await navigator.clipboard.write(data); + const clipboardItemData = { + [type]: text, + }; + const clipboardItem = new ClipboardItem(clipboardItemData); + await navigator.clipboard.write([clipboardItem]); } ``` -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). +The `setClipboard()` function specifies a text MIME type in the `type` constant, then specifies a `clipboardItemData` object with a single property — its key is the MIME type, and its value is the passed in text that we want to write to the clipboard. We then construct a new {{domxref("ClipboardItem")}} object into which the `clipboardItemData` object is passed. -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 with `await`. -A `try..catch` block could be used to catch any errors writing the data. +Finally, `write()` is called with `await` to write the bdata to the clipboard. ### Write canvas contents to the clipboard diff --git a/files/en-us/web/api/clipboard_api/index.md b/files/en-us/web/api/clipboard_api/index.md index 61ed7bc54f6a0fc..fce8c54298f9447 100644 --- a/files/en-us/web/api/clipboard_api/index.md +++ b/files/en-us/web/api/clipboard_api/index.md @@ -96,7 +96,7 @@ Firefox [Web Extensions](/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with 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. +Since {{domxref("Clipboard.readText", "readText()")}} returns an empty string if the clipboard isn't text, this code is safe. ```js navigator.clipboard diff --git a/files/en-us/web/api/clipboarditem/clipboarditem/index.md b/files/en-us/web/api/clipboarditem/clipboarditem/index.md index 4c2b460e5a44535..c308e7c5e31ada1 100644 --- a/files/en-us/web/api/clipboarditem/clipboarditem/index.md +++ b/files/en-us/web/api/clipboarditem/clipboarditem/index.md @@ -11,7 +11,10 @@ browser-compat: api.ClipboardItem.ClipboardItem 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. +> The `read()` and `write()` methods can be used to work with text strings and arbitrary data items represented by {{domxref("Blob")}}s. However, if you are solely working with text, it is more convenient to use the {{domxref("Clipboard.readText()")}} and {{domxref("Clipboard.writeText()")}} methods. + +> [!NOTE] +> Image format support varies by browser. See the [browser compatibility table](/en-US/docs/Web/API/Clipboard#browser_compatibility) for the `Clipboard` interface. ## Syntax @@ -24,7 +27,7 @@ new ClipboardItem(data, options) - `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. + The data can be represented as a {{domxref("Blob")}}, a string, or a {{jsxref("Promise")}} that resolves to either a `Blob` or string. - `options` {{optional_inline}} - : An object with the following properties: @@ -36,9 +39,6 @@ new ClipboardItem(data, options) `inline` signifies to apps that receive the paste that the `ClipboardItem` should be inserted inline at the point of paste. `attachment` signifies to apps that receive the paste that the `ClipboardItem` should be added as an attachment. `unspecified` doesn't signify any information to apps that receive the paste. -> [!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 {{domxref("Window/fetch", "fetch()")}}, and in turn, the {{domxref("Response.blob()")}} method, to create a new {{domxref("ClipboardItem")}}. diff --git a/files/en-us/web/api/clipboarditem/gettype/index.md b/files/en-us/web/api/clipboarditem/gettype/index.md index bdf857c9a5a4e44..d6c1c44576587f3 100644 --- a/files/en-us/web/api/clipboarditem/gettype/index.md +++ b/files/en-us/web/api/clipboarditem/gettype/index.md @@ -34,8 +34,7 @@ A {{jsxref("Promise")}} that resolves with a {{domxref("Blob")}} object. ## 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 using 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 be7d23db8ec2e7e..e37d3ba7976a45e 100644 --- a/files/en-us/web/api/clipboarditem/index.md +++ b/files/en-us/web/api/clipboarditem/index.md @@ -7,22 +7,20 @@ browser-compat: api.ClipboardItem {{APIRef("Clipboard API")}}{{SecureContext_Header}} -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 **`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. +The benefit of having the **`ClipboardItem`** interface to represent data items 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. +> The `read()` and `write()` methods can be used to work with text strings and arbitrary data items represented by {{domxref("Blob")}}s. However, if you are solely working with text, it is more convenient to use the {{domxref("Clipboard.readText()")}} and {{domxref("Clipboard.writeText()")}} methods. ## Constructor - {{domxref("ClipboardItem.ClipboardItem", "ClipboardItem()")}} - - : Creates a new **`ClipboardItem`** object, with the {{Glossary("MIME type")}} as the key and {{domxref("Blob")}} as the value. + - : Creates a new **`ClipboardItem`** object, with the {{Glossary("MIME type")}} as the key and the data as the value. ## Instance properties -_This interface provides the following properties._ - - {{domxref("ClipboardItem.types", "types")}} {{ReadOnlyInline}} - : Returns an {{jsxref("Array")}} of MIME types available within the **`ClipboardItem`**. - {{domxref("ClipboardItem.presentationStyle", "presentationStyle")}} {{ReadOnlyInline}} @@ -30,24 +28,46 @@ _This interface provides the following properties._ ## Static methods -_This interface defines the following methods._ - - {{domxref("ClipboardItem.supports_static", "ClipboardItem.supports()")}} - - : Checks whether a given {{Glossary("MIME type")}} is supported by the clipboard. This enables a website to detect whether a MIME type is supported by the clipboard before attempting to write data. + - : Checks whether a given {{Glossary("MIME type")}} is supported by the clipboard. This enables a website to detect whether a MIME type is supported before attempting to write data. ## Instance methods -_This interface defines the following methods._ - - {{domxref("ClipboardItem.getType", "getType()")}} - : 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. ## Examples -### Writing to the clipboard +### Writing text to the clipboard + +In this example we first define two constants, which respectively contain references to a {{htmlelement("p")}} element containing some text, and a {{htmlelement("button")}}. + +Next, we define a function called `copyToClipboard()`. This starts off by storing a text MIME type in a constant, then creating an object called `clipboardItemData` that contains one property with a key equal to the MIME type and a value of the text we want to copy to the clipboard (the content of the `

` element, in this case). Because we are working with text, we can pass it in directly rather than having to create a {{domxref("Blob")}}. + +We construct a new `ClipboardItem` object using the {{domxref("ClipboardItem.ClipboardItem", "ClipboardItem()")}} constructor, and pass it in to the {{domxref("Clipboard.write()")}} method to copy the text to the clipboard. + +Finally, we add an event listener to the `