Clipboard API
The ClipboardItem interface of the Clipboard API represents a single item of data copied to, or read from, the clipboard, used with Clipboard.write() and Clipboard.read() respectively.
[!NOTE] The
read()andwrite()methods can be used to work with text strings and arbitrary data items represented by Blob instances. However, if you are solely working with text, it is more convenient to use the Clipboard.readText() and Clipboard.writeText() methods.
Constructor
- ClipboardItem.ClipboardItem
- : Creates a new
ClipboardItemobject, with one or more MIME type as keys and their corresponding data as values.
- : Creates a new
Instance properties
- ClipboardItem.types
- : Returns an Array of MIME type, one for each representation of the data in the
ClipboardItem.
- : Returns an Array of MIME type, one for each representation of the data in the
- ClipboardItem.presentationStyle
- : Returns one of the following:
"unspecified","inline"or"attachment".
- : Returns one of the following:
Static methods
- ClipboardItem.supports_static
- : Checks whether a given 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
- ClipboardItem.getType
- : Returns a Promise that resolves with a Blob of the requested MIME type, or an error if the MIME type is not found.
Description
A single ClipboardItem can hold several representations of that data at once, each identified by a different MIME type — for example, some copied rich text might be stored as both text/html and text/plain.
When you construct a ClipboardItem, you provide these representations as MIME-type-keyed properties of a single object; see ClipboardItem.ClipboardItem for details.
When you read a ClipboardItem, you can find its available formats in ClipboardItem.types, and retrieve each one individually with ClipboardItem.getType.
Examples
Writing text to the clipboard
In this example we first define two constants containing references to a p element containing some text and a button element.
Next, we define a function called copyToClipboard(). This starts off by storing a "text/plain" 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 <p> element, in this case). Because we are working with text, we can pass it in directly rather than having to create a Blob.
We construct a new ClipboardItem object using the ClipboardItem.ClipboardItem constructor, and pass it into the Clipboard.write() method to copy the text to the clipboard.
Finally, we add an event listener to the <button> so that it runs the function when pressed.
const textSource = document.querySelector("p");
const copyBtn = document.querySelector("button");
async function copyToClipboard() {
const type = "text/plain";
const clipboardItemData = {
[type]: textSource.textContent,
};
const clipboardItem = new ClipboardItem(clipboardItemData);
await navigator.clipboard.write([clipboardItem]);
}
copyBtn.addEventListener("click", copyToClipboard);
Writing an image to the clipboard
Here we use ClipboardItem.supports_static to check whether the image/svg+xml MIME data type is supported.
If it is, we fetch an SVG image with the Fetch API, and then read it into a Blob, which we can use to create a ClipboardItem that is written to the clipboard.
async function writeClipImg() {
try {
if (ClipboardItem.supports("image/svg+xml")) {
const imgURL = "/my-image.svg";
const data = await fetch(imgURL);
const blob = await data.blob();
await navigator.clipboard.write([
new ClipboardItem({
[blob.type]: blob,
}),
]);
console.log("Fetched image copied.");
} else {
console.log("SVG images are not supported by the clipboard.");
}
} catch (err) {
console.error(err.name, err.message);
}
}
Reading from the clipboard
Here we're returning all items on the clipboard via the clipboard.read() method. We then use the ClipboardItem.types property to set the ClipboardItem.getType parameter and return the corresponding blob object.
Each clipboardItem here may itself list several MIME types in types, since a single clipboard entry can carry multiple format representations at once.
async function getClipboardContents() {
try {
const clipboardItems = await navigator.clipboard.read();
for (const clipboardItem of clipboardItems) {
const formats = {};
for (const type of clipboardItem.types) {
formats[type] = await clipboardItem.getType(type);
}
console.log(formats); // e.g. { "text/html": Blob, "text/plain": Blob }
}
} catch (err) {
console.error(err.name, err.message);
}
}
Specifications
Browser compatibility
See also
- Clipboard.read()
- Clipboard.write()
- ClipboardChangeEvent
- Clipboard API
- Image support for Async Clipboard article
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
