ClipboardEvent.clipboardData — Eigenschaft · JavaScript-Referenz

Signatur

ClipboardEvent.clipboardData

Beschreibung

Die Eigenschaft clipboardData des ClipboardEvent-Interfaces enthält ein DataTransfer-Objekt. Damit lässt sich festlegen, welche Daten bei einem cut- oder copy-Event in die Zwischenablage kommen. Bei einem paste-Event kann man damit die eingefügten Daten auslesen. Die Eigenschaft ist schreibgeschützt, das zurückgegebene Objekt selbst lässt sich aber während der Event-Verarbeitung verändern.

copy / cut: Mit clipboardData.setData(format, daten) legst du eigene Inhalte fest, z. B. text/plain und text/html. Damit diese Daten statt der markierten Auswahl übernommen werden, musst du event.preventDefault() aufrufen.
paste: Mit clipboardData.getData(format) liest du Text oder HTML aus. Über clipboardData.files oder clipboardData.items kommst du an eingefügte Dateien wie Bilder oder Screenshots.

Typische Einsatzfälle: Text beim Einfügen bereinigen (Formatierung entfernen), beim Kopieren eine Quellenangabe anhängen, Bilder per Strg+V hochladen oder Tabellen in einem eigenen Format kopieren.

Der Zugriff ist nur synchron innerhalb des Event-Handlers möglich. Nach dem Handler wird das DataTransfer-Objekt gesperrt. Für asynchronen Zugriff außerhalb von Events gibt es die Async Clipboard API (navigator.clipboard).

Rückgabewert

Typ

DataTransfer | null

Beschreibung

Ein DataTransfer-Objekt mit den Zwischenablage-Daten. Bei selbst erzeugten Events über new ClipboardEvent() ohne die Option clipboardData ist der Wert null.

Beispiele

Eingefügten Text als reinen Text übernehmen

const editor = document.querySelector('#editor'); // contenteditable-Element

editor.addEventListener('paste', (event) => {
  event.preventDefault();
  const text = event.clipboardData.getData('text/plain');
  // Formatierung verwerfen, nur reinen Text an der Cursorposition einfügen
  const selection = window.getSelection();
  if (!selection.rangeCount) return;
  const range = selection.getRangeAt(0);
  range.deleteContents();
  range.insertNode(document.createTextNode(text));
  range.collapse(false);
  console.log('Eingefügt:', text);
});

Eingefügt: Hallo Welt

Beim Kopieren eine Quellenangabe anhängen

document.addEventListener('copy', (event) => {
  const auswahl = document.getSelection().toString();
  if (!auswahl) return;

  const quelle = `\n\nQuelle: ${location.href}`;
  event.clipboardData.setData('text/plain', auswahl + quelle);
  event.clipboardData.setData(
    'text/html',
    `<p>${auswahl}</p><p>Quelle: <a href="${location.href}">${location.href}</a></p>`
  );
  // Ohne preventDefault würde der Browser die Standard-Auswahl kopieren
  event.preventDefault();
});

Bilder per Strg+V einfügen (Screenshot-Upload)

const vorschau = document.querySelector('#vorschau');

document.addEventListener('paste', (event) => {
  const bilder = [...event.clipboardData.files]
    .filter((datei) => datei.type.startsWith('image/'));

  if (bilder.length === 0) return;
  event.preventDefault();

  for (const bild of bilder) {
    const img = document.createElement('img');
    img.src = URL.createObjectURL(bild);
    img.onload = () => URL.revokeObjectURL(img.src);
    vorschau.append(img);
    console.log(`Bild eingefügt: ${bild.name} (${bild.type}, ${bild.size} Bytes)`);
  }
});

Bild eingefügt: image.png (image/png, 48213 Bytes)

Verfügbare Formate beim Einfügen prüfen

document.addEventListener('paste', (event) => {
  const { types } = event.clipboardData;
  console.log('Formate:', [...types]);

  if (types.includes('text/html')) {
    const html = event.clipboardData.getData('text/html');
    console.log('HTML-Länge:', html.length);
  }
});

Formate: ['text/plain', 'text/html'] HTML-Länge: 312

// Wichtig · Fallstricke

Nur synchron nutzbar: getData() und setData() funktionieren nur während der synchronen Event-Verarbeitung. Nach einem await oder in einem setTimeout kommen leere Werte zurück, oder die Änderungen haben keine Wirkung.
preventDefault() nicht vergessen: Bei copy/cut übernimmt der Browser die mit setData() gesetzten Daten nur, wenn die Standardaktion abgebrochen wird. Bei cut musst du die markierte Auswahl danach selbst entfernen.
Sicherheit (XSS): Eingefügtes text/html kommt aus einer unsicheren Quelle. Füge es nie ungeprüft über innerHTML ein, sondern bereinige es vorher (z. B. mit DOMPurify oder der Sanitizer-API) oder verwende textContent.
Selbst erzeugte Events: Ein per dispatchEvent(new ClipboardEvent('paste', …)) ausgelöstes Event greift aus Sicherheitsgründen nicht auf die echte System-Zwischenablage zu.
Formate: Zuverlässig browserübergreifend funktionieren nur text/plain, text/html, text/uri-list und Dateien. Eigene MIME-Typen werden unterschiedlich behandelt.
Kompatibilität: In allen modernen Browsern verfügbar. Im alten Internet Explorer gab es stattdessen das nicht standardisierte window.clipboardData mit anderen Formatnamen ('Text').

Siehe auch

Clipboard KeyboardEvent.charCode KeyboardEvent.code KeyboardEvent.repeat FormDataEvent.formData