ClipboardItem

Konstruktor

ClipboardItem()

Erstellt ein neues ClipboardItem-Objekt mit einem oder mehreren MIME-Typen als Schlüsseln und den zugehörigen Daten als Werten.

Instanzeigenschaften

types Schreibgeschützt

Gibt ein Array von MIME-Typen zurück, einen für jede Darstellung der Daten im ClipboardItem.

presentationStyle Schreibgeschützt

Gibt einen der folgenden Werte zurück: "unspecified", "inline" oder "attachment".

Statische Methoden

ClipboardItem.supports()

Prüft, ob ein bestimmter MIME-Typ von der Zwischenablage unterstützt wird. So kann eine Website feststellen, ob ein MIME-Typ unterstützt wird, bevor sie versucht, Daten zu schreiben.

Instanzmethoden

getType()

Gibt ein Promise zurück, das mit einem Blob des angeforderten MIME-Typs erfüllt wird, oder einen Fehler, wenn der MIME-Typ nicht gefunden wird.

Beschreibung

Ein einzelnes ClipboardItem kann mehrere Darstellungen derselben Daten enthalten, die jeweils durch einen anderen MIME-Typ gekennzeichnet sind. Beispielsweise kann kopierter formatierter Text sowohl als text/html als auch als text/plain gespeichert sein.

Beim Erstellen eines ClipboardItem übergeben Sie diese Darstellungen als Eigenschaften eines einzelnen Objekts, deren Schlüssel MIME-Typen sind. Einzelheiten finden Sie unter ClipboardItem().

Wenn Sie ein ClipboardItem lesen, finden Sie die verfügbaren Formate unter types und können jede Darstellung einzeln mit getType() abrufen.

Beispiele

Text in die Zwischenablage schreiben

In diesem Beispiel definieren wir zunächst zwei Konstanten mit Referenzen auf ein <p>-Element, das Text enthält, und ein <button>-Element.

Anschließend definieren wir eine Funktion namens copyToClipboard(). Sie speichert zuerst den MIME-Typ "text/plain" in einer Konstanten und erstellt dann ein Objekt namens clipboardItemData. Dieses enthält eine Eigenschaft, deren Schlüssel dem MIME-Typ entspricht und deren Wert der Text ist, den wir in die Zwischenablage kopieren möchten – in diesem Fall der Inhalt des <p>-Elements. Da wir mit Text arbeiten, können wir ihn direkt übergeben, statt einen Blob erstellen zu müssen.

Wir erstellen mit dem Konstruktor ClipboardItem() ein neues ClipboardItem-Objekt und übergeben es an die Methode Clipboard.write(), um den Text in die Zwischenablage zu kopieren.

Zum Schluss fügen wir dem <button> einen Event-Listener hinzu, der die Funktion ausführt, wenn die Schaltfläche gedrückt wird.

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);

Ein Bild in die Zwischenablage schreiben

Hier prüfen wir mit supports(), ob der MIME-Datentyp image/svg+xml unterstützt wird. Falls ja, rufen wir mit der Fetch API ein SVG-Bild ab und lesen es anschließend als Blob ein. Damit können wir ein ClipboardItem erstellen, das in die Zwischenablage geschrieben wird.

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);
  }
}

Aus der Zwischenablage lesen

Hier rufen wir mit der Methode clipboard.read() alle Elemente aus der Zwischenablage ab. Anschließend verwenden wir die Eigenschaft ClipboardItem.types, um den Parameter für getType() festzulegen und das entsprechende Blob-Objekt zurückzugeben.

Jedes clipboardItem kann unter types selbst mehrere MIME-Typen auflisten, da ein einzelner Eintrag in der Zwischenablage mehrere Formatdarstellungen zugleich enthalten kann.

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);
  }
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Clipboard.read()
• Clipboard.write()
• ClipboardChangeEvent
• Clipboard API
• Artikel zur Bildunterstützung für die Async Clipboard API