Clipboard API

Konzepte und Verwendung

Die Systemzwischenablage ist ein Datenpuffer, der zum Betriebssystem gehört, welches den Browser hostet. Sie wird für die kurzfristige Datenspeicherung und/oder den Datenaustausch zwischen Dokumenten oder Anwendungen verwendet. Sie wird üblicherweise als anonymer, temporärer Datenspeicher implementiert, der manchmal auch als Paste-Puffer bezeichnet wird und der über definierte Programmierschnittstellen von den meisten oder allen Programmen innerhalb der Umgebung zugänglich ist.

Die Clipboard-API ermöglicht es Benutzern, programmgesteuert Text und andere Arten von Daten in sicheren Kontexten von und zur Systemzwischenablage zu lesen und zu schreiben, sofern der Benutzer die in den Sicherheitsüberlegungen dargelegten Kriterien erfüllt hat.

Ereignisse werden als Ergebnis der cut-, copy- und paste-Operationen ausgelöst, die die Zwischenablage ändern. Diese Ereignisse haben eine Standardaktion, zum Beispiel kopiert die copy-Aktion standardmäßig die aktuelle Auswahl in die Systemzwischenablage. Die Standardaktion kann durch den Ereignishandler überschrieben werden – siehe jedes der Ereignisse für weitere Informationen.

Schnittstellen

Clipboard Sicherer Kontext

Bietet eine Schnittstelle zum Lesen und Schreiben von Text und Daten zur oder von der Systemzwischenablage. In der Spezifikation wird dies als 'Async Clipboard API' bezeichnet.

ClipboardEvent

Stellt Ereignisse dar, die Informationen zur Änderung der Zwischenablage bereitstellen, das heißt cut-, copy- und paste-Ereignisse. In der Spezifikation wird dies als 'Clipboard Event API' bezeichnet.

ClipboardItem Sicherer Kontext

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

Erweiterungen anderer 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 immer dann ausgelöst wird, wenn der Benutzer eine Kopieraktion initiiert.

Element cut Ereignis

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

Element paste Ereignis

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

Sicherheitsüberlegungen

Die Clipboard-API ermöglicht es Benutzern, programmgesteuert Text und andere Arten von Daten in sicheren Kontexten von und zur Systemzwischenablage zu lesen und zu schreiben.

Beim Lesen aus der Zwischenablage verlangt die Spezifikation, dass ein Benutzer kürzlich mit der Seite interagiert hat (transient user activation) und dass der Aufruf als Ergebnis der Interaktion des Benutzers mit einem Browser- oder OS-"Paste-Element" erfolgt (wie z.B. die Auswahl "Einfügen" in einem nativen Kontextmenü). In der Praxis erlauben Browser oft Lesevorgänge, die diese Anforderungen nicht erfüllen, während sie andere Anforderungen stellen (wie z.B. eine Berechtigung oder pro-Operation Prompt). Zum Schreiben in die Zwischenablage erwartet die Spezifikation, dass der Seite die clipboard-write-Berechtigung der Permissions-API erteilt wurde, und der Browser kann auch eine transiente Benutzeraktivierung verlangen. Browser können zusätzliche Einschränkungen hinsichtlich der Verwendung der Methoden zum Zugriff auf die Zwischenablage auferlegen.

Browserimplementierungen haben sich von der Spezifikation entfernt. Die Unterschiede sind im Abschnitt Browser-Kompatibilität erfasst und der aktuelle Stand ist unten zusammengefasst:

Chromium-Browser:

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

Firefox & Safari:

• Wenn ein Lesevorgang von der Spezifikation nicht erlaubt ist, aber die transiente Benutzeraktivierung dennoch erfüllt wird, wird ein Benutzer-Prompt in Form eines flüchtigen Kontextmenüs mit einer einzigen "Einfügen"-Option ausgelöst (die nach einer Sekunde aktiviert wird) und erfolgreich, wenn der Benutzer die Option auswählt.
• Schreiben erfordert eine transiente Aktivierung.
• Der Paste-Prompt wird unterdrückt, wenn gleichursprünglicher Zwischenablageinhalt gelesen wird, jedoch nicht bei ursprungsübergreifendem Inhalt.
• Die Berechtigungen clipboard-read und clipboard-write werden von Firefox oder Safari nicht unterstützt (und sind nicht für die Zukunft geplant).

Firefox Web-Erweiterungen:

• Lesen ist für Erweiterungen mit der Web-Erweiterungsberechtigung clipboardRead verfügbar. Mit dieser Berechtigung benötigt die Erweiterung keine transiente Aktivierung oder die Verwendung des Paste-Prompts. Ab Firefox 147 ist Lesen auch ohne die Berechtigung in einem sicheren Kontext, mit transiente Aktivierung und nachdem der Benutzer auf das Paste-Prompt in einem flüchtigen Kontextmenü geklickt hat, verfügbar.
• Schreiben ist in einem sicheren Kontext und mit transiente Aktivierung verfügbar. Allerdings ist bei der Web-Erweiterungsberechtigung clipboardWrite keine transiente Aktivierung erforderlich.

Beispiele

Zugriff auf die Zwischenablage

Die Systemzwischenablage wird über das globale Navigator.clipboard angesprochen.

Dieses Snippet holt den Text aus der Zwischenablage und fügt ihn dem ersten Element hinzu, das mit der Klasse editor gefunden wird. Da readText() einen leeren String 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.ClipboardEvent

api.ClipboardItem

Siehe auch

• Artikel zur Bildunterstützung für Async Clipboard