Clipboard API: Kopieren und Einfügen in React

navigator.clipboard.writeText(text) schreibt eine Zeichenkette in die Systemzwischenablage und gibt ein Promise zurück. Die Methode ist der moderne Ersatz für den früheren Ansatz mit execCommand. Warten Sie immer mit await auf das Promise und behandeln Sie eine mögliche Ablehnung, etwa wenn der Benutzer den Zugriff auf die Zwischenablage verweigert.

navigator.clipboard.readText() liest den aktuellen Inhalt der Zwischenablage als Zeichenkette und gibt ebenfalls ein Promise zurück. Zum Lesen ist die Berechtigung clipboard-read erforderlich, deren Erteilung der Browser beim Benutzer anfragt. In der Praxis wird das Lesen der Zwischenablage in typischen React-Anwendungen seltener verwendet als das Schreiben.

Browser erzwingen, dass clipboard.writeText nur innerhalb eines Handlers für eine Benutzeraktion aufgerufen werden kann, etwa bei einem Click- oder Keydown-Event. Wenn Sie die Methode innerhalb eines useEffect oder asynchron nach der Benutzeraktion aufrufen, wird ein Sicherheitsfehler ausgelöst. Lösen Sie den Schreibvorgang immer direkt aus einem onClick-Handler aus.

Das Standardmuster ist: Der Benutzer klickt auf eine Kopieren-Schaltfläche, Ihr Handler ruft navigator.clipboard.writeText(value) auf, bei Erfolg setzen Sie den copied-State auf true, und die Schaltfläche zeigt vorübergehend ein Häkchen oder die Beschriftung „Kopiert!“ an. Nach kurzer Zeit kehrt die Schaltfläche zu ihrem normalen Zustand zurück.

Kapseln Sie die Logik in einem useCopyToClipboard-Hook, der ein Tupel zurückgibt: [copied, copyFn]. Der boolesche Wert copied steuert die UI-Rückmeldung, und copyFn übernimmt den zu kopierenden Text. Der Hook kümmert sich intern um das asynchrone Schreiben und mögliche Fehler, sodass die Komponenten einfach bleiben.

Setzen Sie im Hook nach einem erfolgreichen Kopiervorgang setCopied(true) und planen Sie mit setTimeout(() => setCopied(false), 2000) das Zurücksetzen. Speichern Sie die Timeout-ID und löschen Sie sie in der Bereinigung eines useEffect, um State-Aktualisierungen nach dem Unmounting zu verhindern. Dadurch vermeiden Sie die Warnung „cannot update state on an unmounted component“.

Ältere Browser und Seiten ohne HTTPS unterstützen die Clipboard API nicht. Der Legacy-Fallback erstellt ein vorübergehendes textarea, setzt dessen Wert, hängt es an den Body an, ruft document.execCommand('copy') auf und entfernt das Element wieder. Dieser Ansatz ist synchron und funktioniert überall, ist jedoch veraltet.

Prüfen Sie vor der Verwendung der Clipboard API: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. Wenn sie nicht verfügbar ist, verwenden Sie als Fallback den älteren Ansatz mit execCommand. Diese defensive Prüfung verhindert Laufzeitfehler in Umgebungen, die die API nicht unterstützen.

Zum Lesen der Zwischenablage ist eine Benutzerberechtigung über die Permissions API erforderlich. Sie können den aktuellen Status abfragen: navigator.permissions.query({ name: 'clipboard-read' }) gibt einen PermissionStatus mit einem state von granted, denied oder prompt zurück. Der Browser fragt die Berechtigung automatisch an, wenn Sie readText() aufrufen.

Die Clipboard API ist nur in sicheren Kontexten verfügbar, also unter HTTPS oder auf localhost. Auf HTTP-Seiten ist navigator.clipboard undefined. Diese Einschränkung dient der Sicherheit, da der Inhalt der Zwischenablage vertraulich sein kann. Prüfen Sie stets die Verfügbarkeit der API, bevor Sie auf ihre Methoden zugreifen, um Nullreferenzfehler zu vermeiden.

jsdom (wird von Jest verwendet) implementiert die Clipboard API nicht. Mocken Sie sie in Ihrem Test-Setup: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). So können Sie testen, dass Ihre Komponente writeText mit dem korrekten Argument aufruft, ohne eine echte Browserumgebung zu benötigen.

Wann kann navigator.clipboard.writeText() im Browser sicher aufgerufen werden?

Verwenden Sie navigator.clipboard.writeText() in einem Click-Handler, um Text zu kopieren. Erstellen Sie einen useCopyToClipboard-Hook, der [copied, copyFn] mit einer zeitgesteuerten Zurücksetzung zurückgibt. Prüfen Sie immer, ob die API verfügbar ist, stellen Sie für ältere Browser ein execCommand-Fallback bereit und mocken Sie navigator.clipboard in Jest-Tests.