ClipboardChangeEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface ClipboardChangeEvent extends Event

Beschreibung

ClipboardChangeEvent ist das Ereignisobjekt des clipboardchange-Events der Clipboard API. Das Event wird am Clipboard-Objekt (navigator.clipboard) ausgelöst, sobald sich der Inhalt der Systemzwischenablage ändert. Dabei spielt es keine Rolle, ob die eigene Seite, ein anderer Tab oder eine ganz andere Anwendung die Änderung verursacht hat.

Ohne dieses Event mussten Anwendungen die Zwischenablage regelmäßig mit navigator.clipboard.read() abfragen (Polling). Das kostet Leistung und öffnet unter Umständen wiederholt Berechtigungsabfragen. Typische Einsatzfälle sind Remote-Desktop- und VDI-Clients, die ihre Zwischenablage mit dem entfernten System abgleichen, Editoren, die eine Schaltfläche „Einfügen“ je nach verfügbarem Format ein- oder ausblenden, und Werkzeuge für die Zwischenablage-Historie.

Das Event verrät aus Datenschutzgründen nicht den Inhalt selbst. Es enthält nur:

types – ein eingefrorenes Array mit den MIME-Typen, die gerade in der Zwischenablage liegen (z. B. "text/plain", "image/png").
changeId – eine eindeutige Kennung für genau diesen Stand der Zwischenablage. Damit lassen sich doppelte Benachrichtigungen erkennen, etwa wenn mehrere Tabs dieselbe Änderung melden.

Den eigentlichen Inhalt liest man danach bei Bedarf mit navigator.clipboard.read() oder readText(). Dafür gelten die üblichen Berechtigungsregeln.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events, in der Praxis immer `"clipboardchange"`. Gilt nur für den Konstruktor `new ClipboardChangeEvent(type, options)`.
$options	object	{}	Optionales `ClipboardChangeEventInit`-Objekt. Es erbt die Felder von `EventInit` (`bubbles`, `cancelable`, `composed`).
$options.types	string[]	[]	Liste der MIME-Typen, die über die Eigenschaft `types` gemeldet werden.
$options.changeId	number	0	Kennung des Zwischenablage-Stands, lesbar über die Eigenschaft `changeId`.

Rückgabewert

Typ

ClipboardChangeEvent

Beschreibung

Beim Konstruktor-Aufruf eine neue Event-Instanz. Normalerweise erzeugt aber der Browser das Objekt und übergibt es an den Listener. Die schreibgeschützten Eigenschaften sind types (ReadonlyArray<string>) und changeId (number).

Beispiele

Auf Änderungen der Zwischenablage reagieren

const onClipboardChange = (event) => {
  console.log('Neue Formate:', event.types);
  console.log('Änderungs-ID:', event.changeId);
};

if ('onclipboardchange' in navigator.clipboard) {
  navigator.clipboard.addEventListener('clipboardchange', onClipboardChange);
} else {
  console.warn('clipboardchange wird von diesem Browser nicht unterstützt.');
}

Neue Formate: ['text/plain', 'text/html'] Änderungs-ID: 1739201234

Einfügen-Schaltfläche je nach Format aktivieren

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

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

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

Doppelte Meldungen über changeId herausfiltern und Listener entfernen

let lastChangeId = null;

const syncClipboard = async (event) => {
  if (event.changeId === lastChangeId) return; // schon verarbeitet
  lastChangeId = event.changeId;

  if (event.types.includes('text/plain')) {
    const text = await navigator.clipboard.readText();
    console.log('An Remote-Sitzung senden:', text);
  }
};

navigator.clipboard.addEventListener('clipboardchange', syncClipboard);

// Beim Beenden der Sitzung wieder abmelden
const stopSync = () =>
  navigator.clipboard.removeEventListener('clipboardchange', syncClipboard);

An Remote-Sitzung senden: Hallo Welt

Event manuell erzeugen (z. B. für Tests)

const fake = new ClipboardChangeEvent('clipboardchange', {
  types: ['text/plain'],
  changeId: 42,
});

console.log(fake.types, fake.changeId, fake instanceof Event);

['text/plain'] 42 true

// Wichtig · Fallstricke

Experimentell: Das Event ist bisher nur in Chromium-basierten Browsern verfügbar (ca. ab Version 140). Prüfe die Unterstützung vorher mit 'onclipboardchange' in navigator.clipboard und halte für andere Browser eine Ausweichlösung bereit, etwa das Abfragen beim focus-Event.
Nur mit Fokus: Der Browser löst das Event nur aus, wenn das Dokument den Fokus hat. Ändert sich die Zwischenablage, während der Tab im Hintergrund ist, kommt das Event erst, wenn der Tab wieder den Fokus bekommt. Mehrere Änderungen in dieser Zeit können dabei zu einer einzigen Meldung zusammengefasst werden.
Berechtigungen: Das Event erfordert einen sicheren Kontext (HTTPS). Je nach Implementierung setzt es außerdem eine Nutzerinteraktion oder die Berechtigung clipboard-read voraus. Wenn du danach den Inhalt mit read() oder readText() ausliest, kann der Browser um Zustimmung bitten.
Kein Inhalt im Event: types enthält nur MIME-Typen. Für den eigentlichen Inhalt ist ein separater Lesezugriff nötig.
Nicht verwechseln mit ClipboardEvent. Dessen Events copy, cut und paste betreffen nur Nutzeraktionen auf der eigenen Seite und werden am DOM ausgelöst, nicht an navigator.clipboard.
Datenschutz: Die Zwischenablage kann sensible Daten enthalten, etwa Passwörter aus einem Passwort-Manager. Lies den Inhalt nur, wenn deine Anwendung ihn wirklich braucht, und übertrage ihn nicht unbemerkt.

Siehe auch

Clipboard Clipboard.prototype.read() Clipboard.prototype.readText() ClipboardEvent ClipboardItem Navigator.clipboard Event