Mit der Zwischenablage interagieren

In die Zwischenablage schreiben

Die Methoden navigator.clipboard.write() und navigator.clipboard.writeText() der Clipboard API schreiben beliebige Inhalte in die Zwischenablage. Die Methoden sind in einem sicheren Kontext verfügbar, funktionieren aber nur, nachdem ein Benutzer der Erweiterung eine transiente Aktivierung ausgelöst hat. Mit der Berechtigung "clipboardWrite" ist keine transiente Aktivierung erforderlich.

Diese Funktion nimmt eine Zeichenfolge entgegen und schreibt sie in die Zwischenablage:

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

execCommand() verwenden

Die Befehle "cut" und "copy" der Methode document.execCommand() ersetzen den Inhalt der Zwischenablage durch den ausgewählten Inhalt. Erweiterungen können diese Befehle ohne besondere Berechtigung in kurzlebigen Event-Handlern verwenden, die durch Benutzeraktionen ausgelöst werden, beispielsweise durch einen Klick.

Angenommen, Sie haben ein Popup mit folgendem HTML:

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

Damit die Schaltfläche "copy" den Inhalt des Elements <input> kopiert, können Sie Code wie diesen verwenden:

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-Event-Handlers erfolgt, benötigt Ihre Erweiterung keine besonderen Berechtigungen.

Betrachten Sie dagegen ein Beispiel, in dem Ihre Erweiterung den Kopiervorgang durch einen Alarm auslöst:

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 funktioniert es nicht, und in der Konsole erscheint eine Meldung wie diese:

document.execCommand('cut'/'copy') was denied because it was not called from inside a short running user-generated event handler.

Für diesen Anwendungsfall muss Ihre Erweiterung die Berechtigung "clipboardWrite" anfordern. Mit "clipboardWrite" kann Ihre Erweiterung auch außerhalb eines kurzlebigen Event-Handlers für eine Benutzeraktion in die Zwischenablage schreiben.

Aus der Zwischenablage lesen

Die Methoden navigator.clipboard.read() und navigator.clipboard.readText() der Clipboard API lesen beliebigen Text oder Binärdaten aus der Zwischenablage. Mit diesen Methoden können Erweiterungen auf Daten in der Zwischenablage zugreifen, ohne sie in ein bearbeitbares Element einzufügen.

Die Methoden sind in einem sicheren Kontext verfügbar, funktionieren aber nur, nachdem ein Benutzer der Erweiterung eine transiente Aktivierung ausgelöst und in einem temporären Kontextmenü auf eine Einfügeaufforderung geklickt hat. Mit der Berechtigung "clipboardRead" kann Ihre Erweiterung ohne Benutzerbestätigung oder transiente Aktivierung aus der Zwischenablage lesen.

Dieser Codeausschnitt liest den Text aus der Zwischenablage und ersetzt damit den Inhalt des Elements mit der ID "outbox".

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

execCommand() verwenden

Um document.execCommand("paste") zu verwenden, benötigt Ihre Erweiterung die Berechtigung "clipboardRead". Dies gilt auch dann, wenn Sie den Befehl "paste" innerhalb eines durch eine Benutzeraktion ausgelösten Event-Handlers verwenden, etwa für click oder keypress.

Betrachten Sie HTML mit folgendem Inhalt:

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

Um den Inhalt des Elements <textarea> mit der ID "output" auf den Inhalt der Zwischenablage zu setzen, wenn der Benutzer auf <button> "paste" klickt, können Sie Code wie diesen verwenden:

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

Browserspezifische Hinweise

In Chrome:

• Ab Chrome 157 können Erweiterungs-Service-Worker mit der Berechtigung "clipboardWrite" über navigator.clipboard in die Zwischenablage schreiben. Das Lesen aus der Zwischenablage in einem Service-Worker wird hingegen nicht unterstützt. Vor Chrome 157 oder wenn Chrome-Erweiterungen im Hintergrund aus der Zwischenablage lesen, müssen sie die veralteten document.execCommand()-APIs in einem Offscreen-Dokument verwenden oder navigator.clipboard in einem anderen Kontext nutzen, beispielsweise in einem Content-Skript oder auf einer Erweiterungsseite. Damit Seitenskripte ohne Benutzerinteraktion in die Zwischenablage schreiben können, muss die Berechtigung "clipboard-write" über die Web-API navigator.permissions angefordert werden. Ihre Erweiterung kann diese Berechtigung mit navigator.permissions.query() prüfen:

  js

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

  Hinweis: Die Berechtigung clipboard-write wird in Firefox und Safari nicht unterstützt.

In Firefox:

• Die Möglichkeit, die Lesemethoden der Clipboard API nach Bestätigung einer Einfügeaufforderung durch den Benutzer zu verwenden, wurde für Webseiten in Firefox 127 und für Erweiterungen in Firefox 147 eingeführt. Davor waren die Methoden nur verfügbar, wenn die Berechtigung "clipboardRead" festgelegt war.

In Safari:

• Die Berechtigung "clipboardWrite" wird nur in Erweiterungskontexten unterstützt, nicht in Content-Skripten.
• Die Berechtigung "clipboardRead" wird nicht unterstützt.

Browser-Kompatibilität

api.Clipboard

webextensions.api.clipboard

Siehe auch

• Clipboard API
• Permissions API
• Inhalte bearbeitbar machen