Clipboard.readText() — Methode · JavaScript-Referenz

Signatur

Clipboard.prototype.readText()

Beschreibung

Die Methode readText() der Clipboard-Schnittstelle (erreichbar über navigator.clipboard) liest den aktuellen Textinhalt der Systemzwischenablage. Sie arbeitet asynchron und gibt ein Promise zurück, das mit einem String erfüllt wird. Liegt kein Text in der Zwischenablage (etwa weil nur ein Bild kopiert wurde), erhält man einen leeren String.

Typische Anwendungsfälle sind eigene „Einfügen“-Schaltflächen, das Übernehmen kopierter Codes (z. B. Einmalpasswörter oder Gutscheincodes) in Formularfelder oder Editoren, die Inhalte vor dem Einfügen prüfen oder umformatieren wollen.

Da das Lesen der Zwischenablage die Privatsphäre betrifft, ist die Methode stark abgesichert: Sie steht nur in einem sicheren Kontext (HTTPS oder localhost) zur Verfügung, das Dokument muss den Fokus haben, und je nach Browser ist eine Nutzeraktion (transiente Aktivierung, z. B. Klick) und/oder die Berechtigung clipboard-read nötig. Für beliebige Datentypen (Bilder, HTML) nutzt man stattdessen Clipboard.read().

Rückgabewert

Typ

Promise<string>

Beschreibung

Ein Promise, das mit dem Textinhalt der Zwischenablage erfüllt wird (leerer String, wenn kein Text vorhanden ist). Es wird mit einer NotAllowedError-DOMException abgelehnt, wenn der Zugriff verweigert wird oder das Dokument nicht fokussiert ist.

Beispiele

Einfügen-Schaltfläche für ein Eingabefeld

const button = document.querySelector('#paste');
const input = document.querySelector('#code');

button.addEventListener('click', async () => {
  try {
    const text = await navigator.clipboard.readText();
    input.value = text.trim();
    console.log('Eingefügt:', input.value);
  } catch (err) {
    console.error('Zugriff auf die Zwischenablage fehlgeschlagen:', err.name);
  }
});

Eingefügt: ABC-123-XYZ

Feature-Erkennung und Berechtigung prüfen

const readClipboard = async () => {
  if (!navigator.clipboard?.readText) {
    console.warn('Clipboard.readText() wird nicht unterstützt.');
    return null;
  }
  // permissions.query mit 'clipboard-read' kennt nicht jeder Browser
  try {
    const status = await navigator.permissions.query({ name: 'clipboard-read' });
    console.log('Berechtigung:', status.state);
  } catch {
    console.log('Berechtigungsabfrage nicht verfügbar');
  }
  return navigator.clipboard.readText();
};

document.querySelector('#read').addEventListener('click', async () => {
  const text = await readClipboard();
  console.log(text);
});

Berechtigung: prompt Hallo Welt

Kopierten Einmalcode validieren

const otpInput = document.querySelector('#otp');

document.querySelector('#paste-otp').addEventListener('click', async () => {
  const text = (await navigator.clipboard.readText()).replace(/\s/g, '');
  if (/^\d{6}$/.test(text)) {
    otpInput.value = text;
    console.log('Code übernommen');
  } else {
    console.log('Kein gültiger 6-stelliger Code in der Zwischenablage');
  }
});

Code übernommen

// Wichtig · Fallstricke

Nur im sicheren Kontext: Unter HTTP (außer localhost) ist navigator.clipboard undefined.
Nutzeraktion und Fokus: Aufrufe ohne Klick/Tastendruck oder bei nicht fokussiertem Dokument (z. B. aus der DevTools-Konsole) schlagen häufig mit NotAllowedError fehl. Immer mit try/catch absichern.
Browserunterschiede: Chromium fragt einmalig die Berechtigung clipboard-read ab. Firefox (ab 125) und Safari zeigen stattdessen bei jedem Aufruf ein kleines „Einfügen“-Kontextmenü, das der Nutzer bestätigen muss; permissions.query({ name: 'clipboard-read' }) wird dort nicht unterstützt und wirft einen Fehler.
iframes: In eingebetteten Frames muss die Permissions Policy freigegeben sein: <iframe allow="clipboard-read">.
Sicherheit: Inhalte aus der Zwischenablage sind nicht vertrauenswürdig. Niemals ungeprüft per innerHTML einfügen (XSS-Gefahr) – stattdessen textContent oder value verwenden.
In Web Workern ist die Methode nicht verfügbar. Für reine Einfüge-Reaktionen ist oft das paste-Event mit event.clipboardData.getData('text/plain') einfacher und ohne Berechtigungsabfrage nutzbar.

Siehe auch

Clipboard Clipboard.read() Navigator.clipboard Permissions.query() new OfflineAudioContext()