new ClipboardEvent() — Methode · JavaScript-Referenz

Signatur

new ClipboardEvent(type, options)

Beschreibung

Der Konstruktor ClipboardEvent() erzeugt ein synthetisches Ereignis vom Typ ClipboardEvent. Es erbt von Event und stellt über die Eigenschaft clipboardData ein DataTransfer-Objekt bereit, das die betroffenen Daten der Zwischenablage enthält.

Praktisch nutzt man den Konstruktor vor allem in Tests (z. B. Unit-Tests für eigene paste-Handler), um ein Einfügen oder Kopieren zu simulieren, oder um innerhalb einer Anwendung eigene Zwischenablage-Logik über dispatchEvent() auszulösen.

Wichtig: Ein per Konstruktor erzeugtes und mit dispatchEvent() ausgelöstes Ereignis ist nicht vertrauenswürdig (isTrusted === false). Es verändert die echte System-Zwischenablage nicht und löst auch keine Standardaktion des Browsers aus – es ruft lediglich die registrierten Listener auf. Für echten Zugriff auf die Zwischenablage ist die asynchrone navigator.clipboard-API vorgesehen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"copy"`, `"cut"` oder `"paste"` (Groß-/Kleinschreibung beachten).
$options	object	{}	Optionales Objekt mit den Feldern aus `EventInit` (`bubbles`, `cancelable`, `composed`, jeweils Standard `false`) sowie `clipboardData`: ein `DataTransfer`-Objekt oder `null` (Standard).

Rückgabewert

Typ

ClipboardEvent

Beschreibung

Ein neues, nicht vertrauenswürdiges ClipboardEvent-Objekt, das mit dispatchEvent() ausgelöst werden kann.

Beispiele

Einfaches ClipboardEvent erzeugen

const evt = new ClipboardEvent('copy', { bubbles: true, cancelable: true });
console.log(evt.type, evt.bubbles, evt.clipboardData);

copy true null

Paste-Ereignis mit Daten in einem Test simulieren

const input = document.createElement('textarea');
document.body.append(input);

input.addEventListener('paste', (e) => {
  e.preventDefault();
  const text = e.clipboardData.getData('text/plain');
  input.value = text.trim().toUpperCase();
});

const dt = new DataTransfer();
dt.setData('text/plain', '  hallo welt  ');

input.dispatchEvent(new ClipboardEvent('paste', {
  clipboardData: dt,
  bubbles: true,
  cancelable: true
}));

console.log(input.value);

HALLO WELT

Echte vs. synthetische Ereignisse unterscheiden

document.addEventListener('copy', (e) => {
  console.log(e.isTrusted ? 'Vom Nutzer ausgelöst' : 'Synthetisch erzeugt');
});

document.dispatchEvent(new ClipboardEvent('copy'));

Synthetisch erzeugt

// Wichtig · Fallstricke

Keine echte Zwischenablage: Synthetische Ereignisse lesen oder schreiben nie die System-Zwischenablage und lösen keine Standardaktion aus. Nutzen Sie dafür navigator.clipboard.writeText() bzw. readText() (erfordert sicheren Kontext und ggf. Berechtigung).
DataTransfer-Konstruktor: new DataTransfer() wird von allen modernen Browsern unterstützt; ältere Safari-Versionen (vor 14.1) und Firefox vor 62 ignorierten clipboardData im Konstruktor teils bzw. setzten es auf null.
Testumgebungen: jsdom stellt ClipboardEvent und DataTransfer nur eingeschränkt bereit – ggf. ist ein Polyfill oder Mock nötig.
Standardmäßig sind bubbles und cancelable false; für Handler auf übergeordneten Elementen und preventDefault() explizit auf true setzen.
Sicherheit: Daten aus clipboardData in echten paste-Ereignissen sind Benutzereingaben – vor Einfügen per innerHTML unbedingt bereinigen (XSS-Gefahr, v. a. bei text/html).

Siehe auch

ClipboardEvent ClipboardEvent.clipboardData DataTransfer Clipboard EventTarget.dispatchEvent() new ClipboardChangeEvent()