new ClipboardChangeEvent() — Methode · JavaScript-Referenz

Signatur

new ClipboardChangeEvent(type, options)

Beschreibung

Der Konstruktor ClipboardChangeEvent() erzeugt ein Ereignisobjekt vom Typ ClipboardChangeEvent. Normalerweise erzeugt der Browser solche Objekte selbst. Er löst das Ereignis clipboardchange auf navigator.clipboard aus, wenn sich der Inhalt der System-Zwischenablage ändert, zum Beispiel weil der Nutzer in einer anderen Anwendung Text kopiert.

Das Ereignis enthält nicht den Inhalt der Zwischenablage. Es liefert nur Metadaten:

types: ein Array der MIME-Typen, die jetzt verfügbar sind (z. B. "text/plain" oder "image/png").
changeId: eine eindeutige Kennung der Änderung. Damit lassen sich doppelte Meldungen erkennen, etwa aus mehreren Tabs.

Den Konstruktor ruft man selbst vor allem in Tests, in Polyfills oder für das manuelle Auslösen mit dispatchEvent() auf. So lässt sich eigene Logik prüfen, die auf Änderungen der Zwischenablage reagiert (z. B. eine Schaltfläche „Einfügen“ ein- oder ausblenden), ohne dass wirklich etwas kopiert werden muss.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, normalerweise `"clipboardchange"`. Groß- und Kleinschreibung werden unterschieden.
$options	object	{}	Optionales Objekt. Es kann alle Felder von `EventInit` enthalten (`bubbles`, `cancelable`, `composed`) und zusätzlich diese beiden:
$options.types	string[]	[]	Array der MIME-Typen, die in der Zwischenablage verfügbar sind, z. B. `["text/plain", "text/html"]`.
$options.changeId	bigint	0n	Eindeutige Kennung der Änderung der Zwischenablage. Laut aktuellem Spezifikationsentwurf ist das ein `BigInt` (`unsigned long long`).

Rückgabewert

Typ

ClipboardChangeEvent

Beschreibung

Ein neues ClipboardChangeEvent-Objekt mit den übergebenen Werten für types und changeId.

Beispiele

Ereignisobjekt erzeugen und untersuchen

// Vorher prüfen, ob der Browser die API kennt
if ('ClipboardChangeEvent' in window) {
  const event = new ClipboardChangeEvent('clipboardchange', {
    types: ['text/plain', 'text/html'],
    changeId: 42n
  });

  console.log(event.type);
  console.log(event.types);
  console.log(event.changeId);
} else {
  console.log('ClipboardChangeEvent wird nicht unterstützt');
}

clipboardchange ["text/plain", "text/html"] 42n

Auf echte Änderungen der Zwischenablage reagieren

const pasteButton = document.querySelector('#paste-image');

const onClipboardChange = (event) => {
  // Schaltfläche nur zeigen, wenn ein Bild in der Zwischenablage liegt
  const hasImage = event.types.some((t) => t.startsWith('image/'));
  pasteButton.hidden = !hasImage;
  console.log(`Änderung ${event.changeId}:`, event.types);
};

if ('onclipboardchange' in navigator.clipboard) {
  navigator.clipboard.addEventListener('clipboardchange', onClipboardChange);
}

// Später wieder entfernen:
// navigator.clipboard.removeEventListener('clipboardchange', onClipboardChange);

Änderung 7: ["image/png"]

Handler im Test mit einem selbst erzeugten Ereignis prüfen

// Eigenes Ziel verwenden, damit keine Berechtigung nötig ist
const target = new EventTarget();
const seen = new Set();

target.addEventListener('clipboardchange', (event) => {
  // Doppelte Meldungen anhand der changeId ignorieren
  if (seen.has(event.changeId)) return;
  seen.add(event.changeId);
  console.log('Neu:', event.types.join(', '));
});

const fire = (id, types) =>
  target.dispatchEvent(new ClipboardChangeEvent('clipboardchange', { changeId: id, types }));

fire(1n, ['text/plain']);
fire(1n, ['text/plain']); // wird ignoriert
fire(2n, ['image/png']);

Neu: text/plain Neu: image/png

// Wichtig · Fallstricke

Experimentell: Das Ereignis clipboardchange und ClipboardChangeEvent sind bisher nur in neueren Chromium-Browsern verfügbar. Firefox und Safari unterstützen sie derzeit nicht. Die Unterstützung vor der Nutzung prüfen, z. B. mit 'ClipboardChangeEvent' in window.
Kein Inhalt im Ereignis: Das Ereignis liefert nur MIME-Typen und die Kennung der Änderung. Den eigentlichen Inhalt holt man mit navigator.clipboard.read() oder readText(). Dafür sind eine Berechtigung und oft auch eine Nutzeraktion nötig.
Datenschutz: Browser lösen das Ereignis in der Regel nur aus, wenn das Dokument den Fokus hat und die Seite Leserechte für die Zwischenablage hat oder der Nutzer vorher mit der Seite interagiert hat. Änderungen im Hintergrund werden eventuell erst gemeldet, wenn die Seite den Fokus zurückbekommt.
Selbst erzeugte Ereignisse haben isTrusted === false. Sie ändern die echte Zwischenablage nicht und geben keinen Zugriff auf ihren Inhalt.
changeId ist laut aktuellem Entwurf ein BigInt. Beim Vergleich mit Zahlen gilt 42n === 42 als false. Die Spezifikation kann sich noch ändern.

Siehe auch

Clipboard Clipboard.prototype.read() new BufferedChangeEvent() new ClipboardEvent() new CookieChangeEvent()