new ClipboardItem() — Methode · JavaScript-Referenz

Signatur

new ClipboardItem(data, options)

Beschreibung

Der Konstruktor ClipboardItem() erstellt einen Eintrag für die asynchrone Clipboard API. Ein solcher Eintrag kann denselben Inhalt in mehreren Formaten gleichzeitig enthalten, z. B. als text/plain und text/html oder als image/png. Die Zielanwendung wählt dann beim Einfügen das Format, das am besten passt.

Übergeben wird ein Objekt, dessen Schlüssel MIME-Typen sind. Die Werte sind Blob-Objekte, Strings oder Promises, die zu einem Blob oder String aufgelöst werden. Die Promise-Variante ist besonders wichtig für Safari: Dort muss navigator.clipboard.write() synchron innerhalb der Benutzeraktion aufgerufen werden. Die eigentlichen Daten, z. B. ein per fetch() geladenes Bild, dürfen dann später per Promise nachgeliefert werden.

Anschließend wird das erzeugte Objekt in einem Array an navigator.clipboard.write([item]) übergeben. Beim Lesen mit navigator.clipboard.read() bekommt man ebenfalls ClipboardItem-Instanzen zurück. Deren Inhalte liest man über types und getType() aus.

Parameter

Name	Typ	Default	Beschreibung
$data Pflicht	Record<string, Blob \| string \| Promise<Blob \| string>>		Objekt mit MIME-Typen als Schlüsseln (z. B. `"text/plain"`, `"text/html"`, `"image/png"`). Die Werte sind die zugehörigen Daten oder ein Promise darauf.
$options	{ presentationStyle?: "unspecified" \| "inline" \| "attachment" }	{ presentationStyle: "unspecified" }	Optionales Objekt. `presentationStyle` gibt an, ob die Daten beim Einfügen eingebettet (`inline`) oder als Anhang (`attachment`) dargestellt werden sollen. Wird kaum unterstützt.

Rückgabewert

Typ

ClipboardItem

Beschreibung

Ein neues ClipboardItem-Objekt, das an navigator.clipboard.write() übergeben werden kann.

Beispiele

Text gleichzeitig als HTML und reinen Text kopieren

const copyRichText = async () => {
  const html = '<p><strong>Hallo</strong> Welt</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"]

Bild aus fetch() kopieren (Safari-kompatibel per Promise)

document.querySelector('#copy-img').addEventListener('click', async () => {
  // Promise direkt übergeben, damit write() synchron im Klick-Handler startet
  const item = new ClipboardItem({
    'image/png': fetch('/bilder/logo.png').then((res) => res.blob())
  });

  try {
    await navigator.clipboard.write([item]);
    console.log('Bild in Zwischenablage');
  } catch (err) {
    console.error('Kopieren fehlgeschlagen:', err.name);
  }
});

Bild in Zwischenablage

Formatunterstützung prüfen und Inhalte zurücklesen

const demo = async () => {
  if (!('ClipboardItem' in window)) {
    console.log('ClipboardItem nicht verfügbar');
    return;
  }
  if (ClipboardItem.supports?.('image/svg+xml') === false) {
    console.log('SVG wird nicht unterstützt');
  }

  await navigator.clipboard.write([
    new ClipboardItem({ 'text/plain': 'Bestellnummer 4711' })
  ]);

  const [item] = await navigator.clipboard.read();
  const blob = await item.getType('text/plain');
  console.log(await blob.text());
};

document.querySelector('#demo').addEventListener('click', demo);

Bestellnummer 4711

// Wichtig · Fallstricke

Sicherer Kontext nötig: ClipboardItem und navigator.clipboard.write() stehen nur unter HTTPS bzw. localhost zur Verfügung. Das Schreiben erfordert in der Regel eine Benutzeraktion wie einen Klick. Das Lesen erfordert zusätzlich eine Berechtigung.
Unterstützte MIME-Typen: Zuverlässig funktionieren nur text/plain, text/html und image/png. Andere Formate wie image/jpeg werfen meist einen NotAllowedError. Mit ClipboardItem.supports(type) lässt sich das vorab prüfen, allerdings nur in neueren Browsern.
Safari: Der Aufruf von write() muss direkt im Event-Handler erfolgen. Ein await vor dem Aufruf führt zum Verlust der Benutzeraktion. Die Lösung ist, Promises als Werte zu übergeben.
Firefox unterstützt den Konstruktor ohne Flag erst ab Version 127.
Die Browser bereinigen HTML-Inhalte beim Einfügen. Trotzdem sollte man keine nicht vertrauenswürdigen Daten ungeprüft als text/html in die Zwischenablage legen. Sonst besteht XSS-Gefahr in Zielanwendungen, die das HTML nicht bereinigen.
Die Werte in data dürfen Strings sein. Ältere Chromium-Versionen akzeptieren aber nur Blobs oder Promises darauf.

Siehe auch

ClipboardItem Clipboard.write() Clipboard.read() ClipboardItem.getType() ClipboardItem.supports() Clipboard.writeText()