Clipboard: clipboardchange — Ereignis · JavaScript-Referenz

Signatur

navigator.clipboard.addEventListener("clipboardchange", handler)

Beschreibung

Das Ereignis clipboardchange wird am Clipboard-Objekt ausgelöst, das über navigator.clipboard erreichbar ist. Es meldet jede Änderung der System-Zwischenablage: Kopieren mit Strg+C in einer anderen Anwendung, ein Aufruf von navigator.clipboard.writeText() oder write(), ein Screenshot-Werkzeug usw. Bisher musste man die Zwischenablage dafür per setInterval abfragen. Das Ereignis ersetzt dieses Polling durch eine effiziente und datenschutzfreundlichere Benachrichtigung.

Der Handler bekommt ein ClipboardChangeEvent. Die Eigenschaft types enthält die MIME-Typen, die jetzt in der Zwischenablage liegen (z. B. "text/plain", "image/png"), und changeId ist eine eindeutige Kennung für diese Änderung. Der eigentliche Inhalt ist nicht enthalten. Den müssen Sie bei Bedarf selbst mit navigator.clipboard.read() oder readText() auslesen, und dafür gelten die üblichen Berechtigungsregeln.

Typische Einsatzfälle sind: in Editoren „Einfügen“-Schaltflächen je nach verfügbarem Datentyp aktivieren oder deaktivieren, die Zwischenablage zwischen einer Remote-Desktop- oder Web-VM-Sitzung und dem lokalen System abgleichen und Vorschauen von kopierten Inhalten anzeigen.

Registrieren können Sie den Handler mit navigator.clipboard.addEventListener("clipboardchange", handler) oder über die Eigenschaft navigator.clipboard.onclipboardchange. Das Ereignis steigt nicht auf (bubbelt nicht) und lässt sich nicht abbrechen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"clipboardchange"`.
$handler Pflicht	(event: ClipboardChangeEvent) => void		Callback, der bei jeder Änderung aufgerufen wird. `event.types` (`string[]`) enthält die verfügbaren MIME-Typen, `event.changeId` eine eindeutige Kennung der Änderung.
$options	boolean\|AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (zum Abmelden per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein ClipboardChangeEvent.

Beispiele

Auf Änderungen reagieren und Datentypen prüfen

if ('onclipboardchange' in navigator.clipboard) {
  navigator.clipboard.addEventListener('clipboardchange', (event) => {
    console.log('Zwischenablage geändert, Typen:', event.types);
  });
} else {
  console.warn('clipboardchange wird nicht unterstützt');
}

Zwischenablage geändert, Typen: ["text/plain", "text/html"]

Einfügen-Button abhängig vom Inhalt aktivieren (on-Property)

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

navigator.clipboard.onclipboardchange = (event) => {
  // Nur freischalten, wenn ein Bild in der Zwischenablage liegt
  pasteImageBtn.disabled = !event.types.some((t) => t.startsWith('image/'));
};

pasteImageBtn.addEventListener('click', async () => {
  const items = await navigator.clipboard.read();
  for (const item of items) {
    const type = item.types.find((t) => t.startsWith('image/'));
    if (type) {
      const blob = await item.getType(type);
      document.querySelector('img#preview').src = URL.createObjectURL(blob);
    }
  }
});

Zwischenablage mit Remote-Sitzung abgleichen und wieder abmelden

const controller = new AbortController();
let lastChangeId = null;

const syncClipboard = async (event) => {
  if (event.changeId === lastChangeId) return; // Doppelte Meldungen ignorieren
  lastChangeId = event.changeId;
  if (event.types.includes('text/plain')) {
    const text = await navigator.clipboard.readText();
    await fetch('/api/remote-clipboard', { method: 'POST', body: text });
    console.log('An Remote-Sitzung gesendet:', text.length, 'Zeichen');
  }
};

navigator.clipboard.addEventListener('clipboardchange', syncClipboard, {
  signal: controller.signal,
});

// Später, z. B. beim Trennen der Sitzung:
// controller.abort();
// oder: navigator.clipboard.removeEventListener('clipboardchange', syncClipboard);

An Remote-Sitzung gesendet: 42 Zeichen

// Wichtig · Fallstricke

Browser-Unterstützung: Das Ereignis gibt es bisher nur in Chromium-Browsern (ab Chrome/Edge 140). Firefox und Safari unterstützen es noch nicht. Prüfen Sie die Unterstützung mit 'onclipboardchange' in navigator.clipboard und sehen Sie als Ausweichlösung zum Beispiel eine Prüfung beim focus-Ereignis vor.
Nur mit Fokus und Berechtigung: Aus Datenschutzgründen wird das Ereignis nur zugestellt, wenn das Dokument den Fokus hat. Änderungen, die im Hintergrund passieren, werden erst gemeldet, wenn der Fokus zurückkommt, und dann zusammengefasst als ein einziges Ereignis. Außerdem verlangt Chromium eine Berechtigung (clipboard-read) oder eine vorausgegangene Nutzerinteraktion (Sticky Activation).
Kein Inhalt im Event: event.types verrät nur die Datentypen. Zum Lesen brauchen Sie weiterhin read()/readText(), was eine Berechtigungsabfrage auslösen kann.
Sicherer Kontext: navigator.clipboard gibt es nur unter HTTPS bzw. localhost. In iframes kann eine Permissions Policy (clipboard-read) nötig sein.
Eigene Schreibvorgänge: Auch Ihre eigenen writeText()-Aufrufe lösen das Ereignis aus. Achten Sie beim Synchronisieren darauf, keine Endlosschleifen zu bauen, zum Beispiel indem Sie sich die changeId merken oder ein Flag setzen.
Sensible Daten: In der Zwischenablage liegen oft Passwörter oder Tokens. Lesen und übertragen Sie Inhalte nur, wenn es wirklich nötig ist.

Siehe auch

Clipboard Clipboard.read() MIDIPort: statechange Window: languagechange VideoTrackList: change