ClipboardItem — Schnittstelle · JavaScript-Referenz

Signatur

interface ClipboardItem

Beschreibung

ClipboardItem ist der Datencontainer der asynchronen Clipboard API. Ein Objekt steht für einen Eintrag der Zwischenablage, also für das, was der Nutzer mit Strg+C kopiert. Dieser eine Eintrag kann aber in mehreren Darstellungen vorliegen, etwa als text/plain und zusätzlich als text/html. Die Zielanwendung sucht sich beim Einfügen das passende Format aus.

Zum Schreiben erzeugen Sie ein Objekt mit new ClipboardItem({ "mime/typ": daten }) und übergeben es in einem Array an navigator.clipboard.write(). Als Werte sind Blob, string oder ein Promise erlaubt, das zu einem davon aufgelöst wird. Beim Lesen liefert navigator.clipboard.read() ein Array von ClipboardItem-Objekten. Über types sehen Sie, welche Formate vorhanden sind, und mit getType(type) holen Sie die Daten als Blob.

Wichtige Mitglieder:

ClipboardItem.prototype.types: schreibgeschütztes Array mit den verfügbaren MIME-Typen.
ClipboardItem.prototype.presentationStyle: "unspecified", "inline" oder "attachment".
ClipboardItem.prototype.getType(type): liefert ein Promise<Blob> für den angefragten Typ.
ClipboardItem.supports(type) (statisch): prüft, ob der Browser einen MIME-Typ beim Schreiben unterstützt.

Für reinen Text reicht meist navigator.clipboard.writeText(). ClipboardItem brauchen Sie bei Bildern, Rich Text (HTML) oder wenn Sie mehrere Formate gleichzeitig anbieten wollen.

Parameter

Name	Typ	Default	Beschreibung
$data Pflicht	Record<string, Blob \| string \| Promise<Blob \| string>>		Objekt, dessen Schlüssel MIME-Typen sind (z. B. `"text/plain"`, `"text/html"`, `"image/png"`) und dessen Werte die zugehörigen Daten sind. Chromium erlaubt zusätzlich eigene Formate mit dem Präfix `"web "`.
$options	{ presentationStyle?: "unspecified" \| "inline" \| "attachment" }	{ presentationStyle: "unspecified" }	Optionaler Hinweis, ob der Inhalt beim Einfügen eingebettet (`inline`) oder als Anhang (`attachment`) dargestellt werden soll.

Rückgabewert

Typ

ClipboardItem

Beschreibung

Ein neues ClipboardItem-Objekt. Übergeben Sie es in einem Array an navigator.clipboard.write().

Beispiele

Text als Klartext und HTML gleichzeitig kopieren

const copyRichText = async () => {
  const html = '<p>Hallo <strong>Welt</strong></p>';
  const text = 'Hallo Welt';

  const item = new ClipboardItem({
    'text/html': new Blob([html], { type: 'text/html' }),
    'text/plain': new Blob([text], { type: 'text/plain' })
  });

  await navigator.clipboard.write([item]);
  console.log('Kopiert:', item.types);
};

document.querySelector('#copy').addEventListener('click', copyRichText);

Kopiert: ['text/html', 'text/plain']

Canvas-Bild als PNG kopieren (auch in Safari)

const copyCanvas = async (canvas) => {
  // Das Promise wird direkt übergeben, damit der Aufruf in Safari
  // noch zur Nutzer-Geste zählt.
  const pngPromise = new Promise((resolve) =>
    canvas.toBlob(resolve, 'image/png')
  );

  await navigator.clipboard.write([
    new ClipboardItem({ 'image/png': pngPromise })
  ]);
  console.log('Bild in der Zwischenablage');
};

document.querySelector('#copy-img').addEventListener('click', () =>
  copyCanvas(document.querySelector('canvas'))
);

Bild in der Zwischenablage

Zwischenablage lesen und nach Format auswerten

const pasteFromClipboard = async () => {
  try {
    const items = await navigator.clipboard.read();
    for (const item of items) {
      if (item.types.includes('image/png')) {
        const blob = await item.getType('image/png');
        const img = document.createElement('img');
        img.src = URL.createObjectURL(blob);
        document.body.append(img);
      } else if (item.types.includes('text/plain')) {
        const blob = await item.getType('text/plain');
        console.log('Text:', await blob.text());
      }
    }
  } catch (err) {
    console.error('Lesen nicht erlaubt:', err.name);
  }
};

document.querySelector('#paste').addEventListener('click', pasteFromClipboard);

Text: Hallo Welt

Unterstützung eines Formats vorab prüfen

const canWriteSvg = 'supports' in ClipboardItem
  ? ClipboardItem.supports('image/svg+xml')
  : false;

console.log('SVG schreibbar:', canWriteSvg);
console.log('PNG schreibbar:', ClipboardItem.supports?.('image/png') ?? true);

SVG schreibbar: true PNG schreibbar: true

// Wichtig · Fallstricke

Nur in sicheren Kontexten (HTTPS oder localhost) verfügbar. Ohne sicheren Kontext ist ClipboardItem nicht definiert. Prüfen Sie deshalb vorher mit 'ClipboardItem' in window.
Nutzer-Geste nötig: write() und read() funktionieren nur als Reaktion auf eine Nutzeraktion (z. B. einen Klick). Beim Lesen fragt der Browser meist um Erlaubnis. In Chromium läuft das über die Berechtigungen clipboard-read und clipboard-write, Safari und Firefox zeigen stattdessen ein Einfüge-Menü.
Safari: Wenn Sie vor write() ein await ausführen (z. B. fetch), geht die Nutzer-Geste verloren und es kommt zu einem NotAllowedError. Übergeben Sie deshalb das Promise direkt als Wert an den Konstruktor.
Formate: Verlässlich unterstützt werden nur text/plain, text/html und image/png. JPEG, GIF und andere Formate führen oft zu einem NotAllowedError oder DataError. Wandeln Sie solche Bilder vorher über ein Canvas in PNG um.
HTML aus der Zwischenablage wird vom Browser bereinigt. Behandeln Sie es trotzdem als nicht vertrauenswürdig und setzen Sie es nicht ungeprüft per innerHTML ein (XSS-Gefahr).
ClipboardItem.supports() ist neu. Rufen Sie es nur auf, wenn es vorhanden ist (z. B. mit optionaler Verkettung), sonst entsteht in älteren Browsern ein Fehler.
Firefox unterstützt ClipboardItem standardmäßig erst ab Version 127.

Siehe auch

Clipboard Clipboard.prototype.write() Clipboard.prototype.read() Clipboard.prototype.writeText() ClipboardItem.prototype.getType() ClipboardItem.prototype.types Blob Navigator.clipboard