Interagieren mit der Zwischenablage

Die Arbeit mit der Zwischenablage in Erweiterungen bewegt sich vom Web-API-Ansatz mit document.execCommand (das veraltet ist) hin zum navigator.clipboard-Ansatz.

Hinweis: Das navigator.clipboard API ist eine neuere Ergänzung der Spezifikation und möglicherweise nicht in allen Browsern vollständig implementiert. Dieser Artikel beschreibt einige Einschränkungen, aber stellen Sie sicher, dass Sie die Kompatibilitätstabellen für jede Methode überprüfen, bevor Sie sie verwenden, um sicherzustellen, dass das API Ihre Anforderungen unterstützt.

Der Unterschied zwischen den beiden APIs besteht darin, dass document.execCommand analog zu den Tastaturaktionen zum Kopieren, Ausschneiden und Einfügen ist – es tauscht Daten zwischen einer Webseite und der Zwischenablage aus –, während navigator.clipboard beliebige Daten zur und von der Zwischenablage schreibt und liest.

navigator.clipboard bietet separate Methoden zum Lesen oder Schreiben:

Jedoch funktionieren navigator.clipboard.readText() und navigator.clipboard.writeText() in allen Browsern, während navigator.clipboard.read() und navigator.clipboard.write() dies nicht tun. Zum Beispiel sind zum Zeitpunkt des Schreibens in Firefox navigator.clipboard.read() und navigator.clipboard.write() nicht vollständig implementiert, sodass:

Schreiben in die Zwischenablage

Dieser Abschnitt beschreibt die Optionen zum Schreiben von Daten in die Zwischenablage.

Verwenden des Clipboard API

Das Clipboard API schreibt beliebige Daten von Ihrer Erweiterung in die Zwischenablage. Die Nutzung des API erfordert die Berechtigung "clipboardRead" oder "clipboardWrite" in Ihrer manifest.json-Datei. Da das API nur in sicheren Kontexten verfügbar ist, kann es nicht von einem Inhalts-Skript auf http:-Seiten, sondern nur auf https:-Seiten verwendet werden.

Für Seitenskripte muss die Berechtigung "clipboard-write" mithilfe des Web-APIs navigator.permissions angefordert werden. Sie können diese Berechtigung mit navigator.permissions.query() überprüfen:

js
navigator.permissions.query({ name: "clipboard-write" }).then((result) => {
  if (result.state === "granted" || result.state === "prompt") {
    /* write to the clipboard now */
  }
});

Hinweis: Der Berechtigungsname clipboard-write wird in Firefox nicht unterstützt, nur in Chromium-Browsern.

Diese Funktion nimmt einen String und schreibt ihn in die Zwischenablage:

js
function updateClipboard(newClip) {
  navigator.clipboard.writeText(newClip).then(
    () => {
      /* clipboard successfully set */
    },
    () => {
      /* clipboard write failed */
    },
  );
}

Verwenden von execCommand()

Die Befehle "cut" und "copy" der Methode document.execCommand() werden verwendet, um den Inhalt der Zwischenablage durch das ausgewählte Material zu ersetzen. Diese Befehle können ohne spezielle Berechtigung in kurzlebigen Ereignishandlern für eine Benutzeraktion (zum Beispiel ein Click-Handler) verwendet werden.

Angenommen, Sie haben ein Popup, das den folgenden HTML-Code enthält:

html
<input id="input" type="text" /> <button id="copy">Copy</button>

Um den "copy"-Button den Inhalt des <input>-Elements kopieren zu lassen, können Sie einen Code wie diesen verwenden:

js
function copy() {
  let copyText = document.querySelector("#input");
  copyText.select();
  document.execCommand("copy");
}

document.querySelector("#copy").addEventListener("click", copy);

Da der Aufruf von execCommand() innerhalb eines Klick-Ereignishandlers erfolgt, sind keine besonderen Berechtigungen erforderlich.

Angenommen, Sie lösen das Kopieren stattdessen durch einen Alarm aus:

js
function copy() {
  let copyText = document.querySelector("#input");
  copyText.select();
  document.execCommand("copy");
}

browser.alarms.create({
  delayInMinutes: 0.1,
});

browser.alarms.onAlarm.addListener(copy);

Je nach Browser funktioniert dies möglicherweise nicht. In Firefox wird dies nicht funktionieren, und Sie sehen eine Nachricht wie diese in Ihrer Konsole:

document.execCommand('cut'/'copy') wurde abgelehnt, da es nicht aus einem kurz laufenden, benutzergenerierten Ereignishandler heraus aufgerufen wurde.

Um diesen Anwendungsfall zu ermöglichen, müssen Sie die Berechtigung "clipboardWrite" anfordern. So ermöglicht "clipboardWrite" Ihnen, außerhalb eines kurzlebigen Ereignishandlers für eine Benutzeraktion in die Zwischenablage zu schreiben.

Hinweis: document.execCommand() funktioniert nicht bei Eingabefeldern vom Typ type="hidden", mit dem HTML5-Attribut "hidden" oder einer übereinstimmenden CSS-Regel mit "display: none;". Um also einer span, div oder p-Tag einen "In die Zwischenablage kopieren"-Button hinzuzufügen, müssen Sie einen Workaround verwenden, wie zum Beispiel die Position des Eingabefelds auf absolut zu setzen und es aus dem Viewport zu bewegen.

Browser-spezifische Überlegungen

Die Zwischenablage- und andere hiermit verbundene APIs entwickeln sich schnell weiter, sodass es Unterschiede zwischen den Browsern gibt, wie sie funktionieren.

In Chrome:

  • Sie benötigen "clipboardWrite" nicht, selbst wenn Sie außerhalb eines benutzergenerierten Ereignishandlers in die Zwischenablage schreiben.

In Firefox:

Sehen Sie sich die Browser-Kompatibilitätstabellen für weitere Informationen an.

Lesen aus der Zwischenablage

Dieser Abschnitt beschreibt die Optionen zum Lesen oder Einfügen von Daten aus der Zwischenablage.

Verwenden des Clipboard API

Die Methoden navigator.clipboard.readText() und navigator.clipboard.read() des Clipboard API ermöglichen es Ihnen, beliebigen Text oder binäre Daten aus der Zwischenablage in sicheren Kontexten zu lesen. Dadurch können Sie auf die Daten in der Zwischenablage zugreifen, ohne sie in ein bearbeitbares Element einzufügen.

Sobald Sie die Berechtigung "clipboard-read" vom Permissions API haben, können Sie leicht von der Zwischenablage lesen. Zum Beispiel holt dieser Codeschnipsel den Text aus der Zwischenablage und ersetzt den Inhalt des Elements mit der ID "outbox" durch diesen Text.

js
navigator.clipboard
  .readText()
  .then((clipText) => (document.getElementById("outbox").innerText = clipText));

Verwenden von execCommand()

Um document.execCommand("paste") zu verwenden, benötigt Ihre Erweiterung die Berechtigung "clipboardRead". Dies gilt selbst dann, wenn Sie den "paste"-Befehl innerhalb eines benutzergenerierten Ereignishandlers verwenden, wie click oder keypress.

Berücksichtigen Sie HTML, das so etwas enthält:

html
<textarea id="output"></textarea> <button id="paste">Paste</button>

Um den Inhalt des <textarea>-Elements mit der ID "output" bei einem Klick auf den "paste"-<button>-Button aus der Zwischenablage zu setzen, können Sie einen Code wie diesen verwenden:

js
function paste() {
  let pasteText = document.querySelector("#output");
  pasteText.focus();
  document.execCommand("paste");
  console.log(pasteText.textContent);
}

document.querySelector("#paste").addEventListener("click", paste);

Browser-spezifische Überlegungen

Firefox unterstützt die Berechtigung "clipboardRead" ab Version 54, unterstützt jedoch das Einfügen in Elemente nur im Content Edit Mode, was für Inhalts-Skripte nur mit einem <textarea> funktioniert. Für Hintergrund-Skripte kann jedes Element in den Content Edit Mode gesetzt werden.

Browser-Kompatibilität

api.Clipboard

BCD tables only load in the browser

webextensions.api.clipboard

BCD tables only load in the browser

Siehe auch