ClipboardEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface ClipboardEvent extends Event

Beschreibung

ClipboardEvent gehört zur Clipboard-API und erbt von Event. Der Browser erzeugt ein solches Ereignis, wenn jemand Inhalte ausschneidet (cut), kopiert (copy) oder einfügt (paste). Das geht per Tastenkürzel wie Strg+C, über das Kontextmenü oder über das Browser-Menü.

Die wichtigste Eigenschaft ist clipboardData, ein DataTransfer-Objekt. Bei paste liest man damit die eingefügten Daten, zum Beispiel mit getData("text/plain") oder über files für Bilder. Bei copy und cut schreibt man eigene Inhalte mit setData() in die Zwischenablage. Damit der Browser seine eigenen Daten nicht zusätzlich hineinschreibt, muss man dann event.preventDefault() aufrufen.

Typische Anwendungen:

eingefügtes HTML auf reinen Text reduzieren
Screenshots aus der Zwischenablage hochladen
beim Kopieren einen Quellenhinweis anhängen
eigene Editoren mit einem angepassten Kopierformat

Den Konstruktor new ClipboardEvent(type, options) gibt es auch. Ein damit erzeugtes und ausgelöstes Ereignis ändert aber nicht die echte Zwischenablage, denn es ist nicht vertrauenswürdig (isTrusted === false). Wer die Zwischenablage per Skript ansprechen will, nimmt dafür die asynchrone navigator.clipboard-API.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, meist `"copy"`, `"cut"` oder `"paste"`.
$options	object	{}	Wie bei `EventInit` (`bubbles`, `cancelable`, `composed`), zusätzlich `clipboardData`: ein `DataTransfer` oder `null` (Standard: `null`).

Rückgabewert

Typ

ClipboardEvent

Beschreibung

Ein neues ClipboardEvent-Objekt. Seine Eigenschaft clipboardData (DataTransfer | null) ist schreibgeschützt.

Beispiele

Einfügen als reiner Text erzwingen

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

editor.addEventListener('paste', (event) => {
  event.preventDefault();
  const text = event.clipboardData.getData('text/plain');
  // Text an der aktuellen 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 einen Quellenhinweis anhängen

document.addEventListener('copy', (event) => {
  const selected = document.getSelection().toString();
  if (!selected) return;
  const hinweis = `\n\nQuelle: ${location.href}`;
  event.clipboardData.setData('text/plain', selected + hinweis);
  event.clipboardData.setData('text/html', `${selected}<br><br>Quelle: <a href="${location.href}">${location.href}</a>`);
  event.preventDefault(); // sonst überschreibt der Browser die Daten
});

Bild aus der Zwischenablage hochladen

document.addEventListener('paste', async (event) => {
  const bilder = [...event.clipboardData.files].filter((f) => f.type.startsWith('image/'));
  if (bilder.length === 0) return;
  event.preventDefault();

  const formData = new FormData();
  bilder.forEach((bild, i) => formData.append('bild' + i, bild));
  const response = await fetch('/upload', { method: 'POST', body: formData });
  console.log('Upload-Status:', response.status);
});

Upload-Status: 200

Ereignis selbst erzeugen (z. B. für Tests)

const data = new DataTransfer();
data.setData('text/plain', 'Testinhalt');

const event = new ClipboardEvent('paste', {
  bubbles: true,
  cancelable: true,
  clipboardData: data
});

const input = document.querySelector('input');
input.addEventListener('paste', (e) => {
  console.log(e.clipboardData.getData('text/plain'), e.isTrusted);
});
input.dispatchEvent(event); // Listener laufen, der Feldinhalt bleibt aber unverändert

Testinhalt false

// Wichtig · Fallstricke

preventDefault() nicht vergessen: Ohne diesen Aufruf ignoriert der Browser bei copy und cut die Daten aus setData(). Bei cut muss man die Auswahl dann selbst aus dem Dokument löschen.
Zugriff nur im Handler: clipboardData lässt sich nur synchron während der Ereignisbehandlung nutzen. Nach einem await oder in einem setTimeout ist das Objekt leer oder gesperrt. Die Daten also zuerst auslesen.
Selbst erzeugte Ereignisse: Mit dispatchEvent() ausgelöste ClipboardEvents lesen oder ändern die echte Zwischenablage nicht und fügen auch nichts in Eingabefelder ein. Für den Zugriff per Skript gibt es navigator.clipboard.readText() und writeText(). Diese brauchen einen sicheren Kontext (HTTPS) und oft eine Berechtigung.
Sicherheit (XSS): Eingefügtes text/html kommt von außen und ist nicht vertrauenswürdig. Nie ungeprüft über innerHTML einfügen, sondern vorher bereinigen (z. B. mit DOMPurify) oder gleich text/plain verwenden. Umgekehrt nicht unbemerkt schädliche Befehle in die Zwischenablage schreiben (Pastejacking).
Kompatibilität: Die Ereignisse copy, cut und paste samt clipboardData werden von allen modernen Browsern unterstützt. Welche MIME-Typen es gibt (z. B. Dateien, text/html), hängt von Browser und Betriebssystem ab. Der alte Internet Explorer kannte nur window.clipboardData.

Siehe auch

Clipboard Navigator.clipboard Event ClipboardItem KeyboardEvent