大网数据广告活动
Web 标准与前端开发

ClipboardItem

· 52CE 我爱测

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.

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() and write() 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 ClipboardItem object, with one or more MIME type as keys and their corresponding data as values.

Instance properties

  • ClipboardItem.types
    • : Returns an Array of MIME type, one for each representation of the data in the ClipboardItem.
  • ClipboardItem.presentationStyle
    • : Returns one of the following: "unspecified", "inline" or "attachment".

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

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。