Clipboard API

Konzepte und Verwendung

Die Systemzwischenablage ist ein Datenpuffer, der zum Betriebssystem gehört, auf dem der Browser ausgeführt wird, und wird zur kurzfristigen Datenspeicherung und/oder für Datentransfers zwischen Dokumenten oder Anwendungen verwendet. Sie wird üblicherweise als anonymer, temporärer Datenpuffer implementiert, manchmal auch Paste-Puffer genannt, der von den meisten oder allen Programmen innerhalb der Umgebung über definierte Programmierschnittstellen zugänglich ist.

Die Clipboard API ermöglicht es Benutzern, programmatisch Text und andere Arten von Daten in die und aus der Systemzwischenablage zu lesen und zu schreiben, vorausgesetzt, der Benutzer hat die im Abschnitt Sicherheitsüberlegungen beschriebenen Kriterien erfüllt, in sicheren Kontexten. Ereignisse werden ausgelöst infolge von cut-, copy- und paste-Operationen, die die Zwischenablage ändern. Die Ereignisse haben eine Standardaktion, zum Beispiel kopiert die copy-Aktion die aktuelle Auswahl standardmäßig in die Systemzwischenablage. Die Standardaktion kann vom Ereignishandler überschrieben werden – sehen Sie sich die einzelnen Ereignisse für weitere Informationen an.

Es gibt auch ein clipboardchange-Ereignis, das direkt auf dem Clipboard-Objekt ausgelöst wird, wann immer sich der Inhalt der Systemzwischenablage ändert. Dies ist nützlich, um Apps über eine Änderung der Systemzwischenablage zu informieren, beispielsweise wenn sie eine eigene Zwischenablage haben, die synchron gehalten werden muss.

Schnittstellen

Clipboard Sicherer Kontext

Bietet eine Schnittstelle zum Lesen und Schreiben von Text und Daten in oder aus der Systemzwischenablage. Die Spezifikation bezeichnet dies als die 'Async Clipboard API'.

ClipboardChangeEvent

Repräsentiert Ereignisse, die ausgelöst werden, wenn sich der Inhalt der Systemzwischenablage ändert.

ClipboardEvent

Repräsentiert Ereignisse, die Informationen im Zusammenhang mit der Änderung der Zwischenablage bereitstellen, das heißt cut-, copy- und paste-Ereignisse. Die Spezifikation bezeichnet dies als die 'Clipboard Event API'.

ClipboardItem Sicherer Kontext

Stellt ein einzelnes Elementformat dar, das beim Lesen oder Schreiben von Daten verwendet wird.

Erweiterungen für andere Schnittstellen

Die Clipboard API erweitert die folgenden APIs und fügt die aufgelisteten Funktionen hinzu.

Navigator.clipboard Schreibgeschützt Sicherer Kontext

Gibt ein Clipboard-Objekt zurück, das Lese- und Schreibzugriff auf die Systemzwischenablage bietet.

Element copy-Ereignis

Ein Ereignis, das ausgelöst wird, wann immer der Benutzer eine Kopieraktion initiiert.

Element cut-Ereignis

Ein Ereignis, das ausgelöst wird, wann immer der Benutzer eine Ausschneideaktion initiiert.

Element paste-Ereignis

Ein Ereignis, das ausgelöst wird, wann immer der Benutzer eine Einfügeaktion initiiert.

Sicherheitsüberlegungen

Die Clipboard API ermöglicht es Benutzern, programmatisch Text und andere Arten von Daten in die und aus der Systemzwischenablage zu lesen und zu schreiben in sicheren Kontexten.

Beim Lesen aus der Zwischenablage erfordert die Spezifikation, dass der Benutzer kürzlich mit der Seite interagiert hat (transiente Benutzeraktivierung) und dass der Aufruf als Ergebnis der Benutzerinteraktion mit einem Browser- oder OS-"Paste-Element" erfolgt (wie das Wählen von "Einfügen" in einem nativen Kontextmenü). In der Praxis erlauben Browser oft Leseoperationen, die diese Anforderungen nicht erfüllen, während sie andere Anforderungen statt dessen stellen (wie eine Berechtigung oder eine Eingabeaufforderung pro Operation). Für das Schreiben in die Zwischenablage erwartet die Spezifikation, dass der Seite die Berechtigung clipboard-write der Permissions API erteilt wurde, und der Browser kann auch transiente Benutzeraktivierung erfordern. Browser können zusätzliche Einschränkungen für die Verwendung der Methoden zum Zugriff auf die Zwischenablage platzieren.

Das clipboardchange-Ereignis wird nur mit sticky activation oder nach Erteilung der Berechtigung clipboard-read ausgelöst.

Browser-Implementierungen haben sich von der Spezifikation entfernt. Die Unterschiede sind im Abschnitt Browser-Kompatibilität festgehalten und der aktuelle Stand wird im Folgenden zusammengefasst:

Chromium-Browser:

• Wenn ein Lesen nicht durch die Spezifikation erlaubt ist und das Dokument den Fokus hat, löst es eine Anforderung zur Verwendung der Berechtigung clipboard-read aus und ist erfolgreich, wenn die Berechtigung erteilt wird (entweder weil der Benutzer die Eingabeaufforderung akzeptiert hat oder weil die Berechtigung bereits erteilt wurde).
• Schreiben erfordert entweder die Berechtigung clipboard-write oder transiente Aktivierung. Wenn die Berechtigung erteilt ist, bleibt sie bestehen, und weitere transiente Aktivierungen sind nicht erforderlich.
• Die HTTP Permissions-Policy-Berechtigungen clipboard-read und clipboard-write müssen für <iframe>-Elemente erlaubt sein, die auf die Zwischenablage zugreifen.

Firefox & Safari:

• Wenn ein Lesen nicht durch die Spezifikation erlaubt ist, aber dennoch eine transiente Benutzeraktivierung vorliegt, löst es eine Benutzeraufforderung in Form eines temporären Kontextmenüs mit einer einzigen "Einfügen"-Option aus (die nach 1 Sekunde aktiviert wird) und ist erfolgreich, wenn der Benutzer die Option wählt.
• Schreiben erfordert transiente Aktivierung.
• Die Einfügeaufforderung wird unterdrückt, wenn der Inhalt der Zwischenablage desselben Ursprungs gelesen wird, nicht jedoch bei inhaltsübergreifendem Lesen.
• Die Berechtigungen clipboard-read und clipboard-write werden von Firefox oder Safari nicht unterstützt (und es ist auch nicht geplant, sie zu unterstützen).

Firefox Web-Erweiterungen:

• Lesen ist für Erweiterungen mit der Web-Erweiterungs-Berechtigung clipboardRead verfügbar. Mit dieser Berechtigung benötigt die Erweiterung keine transiente Aktivierung oder die Einfügeaufforderung. Ab Firefox 147 ist das Lesen auch ohne die Berechtigung in einem sicheren Kontext mit transiente Aktivierung und nachdem der Benutzer die Einfügeaufforderung in einem temporären Kontextmenü bestätigt hat, möglich.
• Schreiben ist in einem sicheren Kontext und mit transiente Aktivierung verfügbar. Allerdings ist mit der Web-Erweiterungs-Berechtigung clipboardWrite keine transiente Aktivierung erforderlich.

Beispiele

Zugriff auf die Zwischenablage

Auf die Systemzwischenablage wird über das globale Navigator.clipboard zugegriffen.

Dieses Snippet ruft den Text aus der Zwischenablage ab und hängt ihn an das erste Element mit der Klasse editor an. Da readText() eine leere Zeichenkette zurückgibt, wenn die Zwischenablage kein Text ist, ist dieser Code sicher.

navigator.clipboard
  .readText()
  .then(
    (clipText) => (document.querySelector(".editor").innerText += clipText),
  );

Spezifikationen

Browser-Kompatibilität

api.Clipboard

api.ClipboardChangeEvent

api.ClipboardEvent

api.ClipboardItem