ClipboardItem.types — Eigenschaft · JavaScript-Referenz

Signatur

ClipboardItem.types

Beschreibung

Die Eigenschaft types eines ClipboardItem gibt ein Array von Zeichenketten zurück. Jeder Eintrag ist ein MIME-Typ wie text/plain, text/html oder image/png, in dem der Eintrag Daten bereitstellt. Ein einzelner Zwischenablage-Eintrag kann denselben Inhalt in mehreren Formaten enthalten, zum Beispiel formatierten HTML-Text und zusätzlich eine reine Textfassung.

Gebraucht wird types vor allem beim Lesen der Zwischenablage mit navigator.clipboard.read(). Bevor man mit ClipboardItem.prototype.getType(type) einen Blob anfordert, prüft man über types, welche Formate überhaupt vorhanden sind. So lässt sich das am besten passende Format auswählen, etwa ein Bild vor Text oder HTML vor reinem Text.

Bei selbst erzeugten Einträgen (new ClipboardItem({...})) entspricht types den Schlüsseln des übergebenen Objekts. Mit der Eigenschaft kann man also auch vor dem Schreiben prüfen, was ein Eintrag enthält.

Rückgabewert

Typ

ReadonlyArray<string>

Beschreibung

Ein eingefrorenes Array mit den MIME-Typen, die über getType() abgerufen werden können. Die Reihenfolge ist nicht als Rangfolge garantiert.

Beispiele

Verfügbare Formate aus der Zwischenablage auflisten

const listClipboardTypes = async () => {
  try {
    const items = await navigator.clipboard.read();
    for (const item of items) {
      console.log('Formate:', item.types);
    }
  } catch (err) {
    console.error('Lesen nicht erlaubt:', err.name);
  }
};

// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#paste').addEventListener('click', listClipboardTypes);

Formate: ['text/plain', 'text/html']

Bestes Format wählen: Bild vor HTML vor Text

const pasteBest = async () => {
  const [item] = await navigator.clipboard.read();
  const imageType = item.types.find((t) => t.startsWith('image/'));

  if (imageType) {
    const blob = await item.getType(imageType);
    const img = document.createElement('img');
    img.src = URL.createObjectURL(blob);
    document.body.append(img);
  } else if (item.types.includes('text/html')) {
    const html = await (await item.getType('text/html')).text();
    console.log('HTML-Länge:', html.length);
  } else if (item.types.includes('text/plain')) {
    const text = await (await item.getType('text/plain')).text();
    console.log('Text:', text);
  }
};

document.querySelector('#paste').addEventListener('click', pasteBest);

Text: Hallo Welt

types eines selbst erzeugten ClipboardItem

const item = new ClipboardItem({
  'text/plain': new Blob(['Hallo'], { type: 'text/plain' }),
  'text/html': new Blob(['<b>Hallo</b>'], { type: 'text/html' })
});

console.log(item.types);
console.log(Object.isFrozen(item.types));

await navigator.clipboard.write([item]);

['text/plain', 'text/html'] true

// Wichtig · Fallstricke

Nur lesbar: Das Array ist eingefroren. Zuweisungen oder push() haben keine Wirkung bzw. werfen im Strict Mode einen TypeError.
Sicherer Kontext und Berechtigung: navigator.clipboard.read() funktioniert nur über HTTPS, braucht meist eine Nutzeraktion und je nach Browser die Berechtigung clipboard-read oder eine Bestätigung über ein Einfügen-Menü (Safari, Firefox). Sonst wird ein NotAllowedError ausgelöst.
Eingeschränkte Formate: Browser geben in der Regel nur text/plain, text/html und image/png weiter. Andere Formate sind nur als Web-Custom-Formats mit dem Präfix web verfügbar (derzeit Chromium).
Ist ein Typ in types gelistet, kann getType() trotzdem fehlschlagen, etwa wenn sich die Zwischenablage inzwischen geändert hat. Fehler also immer abfangen.
Firefox unterstützt ClipboardItem standardmäßig erst ab Version 127.

Siehe auch

ClipboardItem ClipboardItem.prototype.getType() Clipboard.prototype.read() Clipboard.prototype.write() ClipboardItem.supports() ClipboardChangeEvent.types ClipboardItem.presentationStyle