ClipboardChangeEvent.types — Eigenschaft · JavaScript-Referenz

Signatur

ClipboardChangeEvent.types

Beschreibung

Die Eigenschaft types gehört zur Schnittstelle ClipboardChangeEvent und ist schreibgeschützt. Sie liefert ein Array von Zeichenketten. Es enthält die obligatorischen MIME-Typen, die in der Systemzwischenablage verfügbar sind, wenn das Ereignis clipboardchange auf navigator.clipboard ausgelöst wird. Obligatorisch sind die Formate, die jeder Browser laut Clipboard-API-Spezifikation unterstützen muss, etwa text/plain, text/html und image/png.

Wofür ist das gut? Eine Anwendung erfährt, welche Art von Inhalt gerade in der Zwischenablage liegt, ohne ihn selbst lesen zu müssen. So kann sie etwa einen Button „Als Bild einfügen“ nur dann aktivieren, wenn image/png verfügbar ist. Oder ein Editor zeigt die Option „Mit Formatierung einfügen“ nur an, wenn text/html vorhanden ist. Bisher musste man dafür die Zwischenablage regelmäßig abfragen (Polling). Das ist teuer, und je nach Browser fragt der Browser jedes Mal nach der Leseberechtigung.

Wichtig: types sagt nur, welche Formate vorhanden sind. Die Daten selbst stehen nicht darin. Den Inhalt liest du weiterhin mit navigator.clipboard.read() oder readText() aus. Dafür gelten die üblichen Berechtigungs- und Fokusregeln.

Rückgabewert

Typ

string[]

Beschreibung

Ein Array mit den MIME-Typen, die beim Auslösen des Ereignisses in der Zwischenablage verfügbar waren, z. B. ["text/plain", "text/html"]. Ist die Zwischenablage leer oder enthält sie nur nicht unterstützte Formate, ist das Array leer.

Beispiele

Verfügbare Formate protokollieren (addEventListener)

// Nur in sicheren Kontexten (HTTPS) und in unterstützenden Browsern
if ('onclipboardchange' in navigator.clipboard) {
  navigator.clipboard.addEventListener('clipboardchange', (event) => {
    console.log('Neue Formate in der Zwischenablage:', event.types);
  });
} else {
  console.log('clipboardchange wird nicht unterstützt');
}

Neue Formate in der Zwischenablage: ["text/plain", "text/html"]

Einfüge-Buttons abhängig vom Inhalt aktivieren

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

const updateButtons = (event) => {
  const { types } = event;
  pasteImageBtn.disabled = !types.includes('image/png');
  pasteRichBtn.disabled = !types.includes('text/html');
};

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

// Beim Klick den eigentlichen Inhalt lesen
pasteImageBtn.addEventListener('click', async () => {
  const items = await navigator.clipboard.read();
  for (const item of items) {
    if (item.types.includes('image/png')) {
      const blob = await item.getType('image/png');
      document.querySelector('img').src = URL.createObjectURL(blob);
    }
  }
});

Listener per on-Eigenschaft setzen und wieder entfernen

const controller = new AbortController();

navigator.clipboard.addEventListener(
  'clipboardchange',
  ({ types }) => {
    const hasText = types.includes('text/plain');
    document.body.dataset.clipboard = hasText ? 'text' : 'andere';
  },
  { signal: controller.signal }
);

// Später, z. B. beim Verlassen der Ansicht:
controller.abort(); // entfernt den Listener

// Alternative über die Handler-Eigenschaft:
navigator.clipboard.onclipboardchange = (e) => console.log(e.types.join(', '));

text/plain, text/html

// Wichtig · Fallstricke

Experimentell: ClipboardChangeEvent gibt es bisher nur in Chromium-Browsern (ab ca. Version 140, Desktop). Firefox und Safari unterstützen es noch nicht. Prüfe deshalb immer vorher, ob die Funktion verfügbar ist, z. B. mit 'onclipboardchange' in navigator.clipboard.
Nur obligatorische Typen: Eigene Formate wie web application/x-custom und andere Betriebssystem-Formate tauchen in types normalerweise nicht auf. Wenn types leer ist, kann die Zwischenablage trotzdem Daten enthalten.
Berechtigung und Fokus: Der Browser löst das Ereignis in der Regel nur aus, wenn das Dokument den Fokus hat. Außerdem braucht es meist die Berechtigung clipboard-read oder eine vorherige Nutzerinteraktion. Änderungen im Hintergrund meldet der Browser eventuell gesammelt oder erst, wenn die Seite den Fokus zurückbekommt.
Keine Inhalte: Mit types lässt sich nicht herausfinden, was genau in der Zwischenablage steht. Zum Lesen brauchst du weiterhin navigator.clipboard.read(). Das schützt die Privatsphäre: Aus der bloßen Formatliste erfährt eine Seite nichts über sensible Inhalte.
Nur in sicheren Kontexten (HTTPS oder localhost) verfügbar.

Siehe auch

Clipboard.prototype.read() Navigator.clipboard ClipboardChangeEvent.changeId ClipboardItem.types CookieChangeEvent.changed