Mit der Zwischenablage interagieren

In die Zwischenablage schreiben

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

Diese Funktion nimmt einen String entgegen und schreibt ihn 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() werden verwendet, um den Inhalt der Zwischenablage durch das ausgewählte Material zu ersetzen. Erweiterungen können diese Befehle ohne besondere Berechtigung in kurzlebigen Event-Handlern verwenden, die durch Benutzeraktionen ausgelöst werden (beispielsweise ein Click-Handler).

Nehmen wir beispielsweise an, Sie haben ein Popup, das dieses HTML enthält:

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

Um die Schaltfläche "copy" den Inhalt des <input>-Elements kopieren zu lassen, können Sie folgenden Code verwenden:

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

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

Da sich der Aufruf von execCommand() innerhalb eines Click-Event-Handlers befindet, benötigt Ihre Erweiterung keine besonderen Berechtigungen.

Betrachten Sie jedoch das Beispiel, bei dem Ihre Erweiterung das Kopieren 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);

Abhängig vom Browser funktioniert dies möglicherweise nicht. In Firefox funktioniert es nicht, und in der Konsole wird eine Meldung wie diese angezeigt:

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

Um diesen Anwendungsfall zu ermöglichen, muss Ihre Erweiterung die Berechtigung "clipboardWrite" anfordern: "clipboardWrite" ermöglicht Ihrer Erweiterung, außerhalb eines kurzlebigen Event-Handlers für eine Benutzeraktion in die Zwischenablage zu schreiben.

Aus der Zwischenablage lesen

Die Clipboard-API-Methoden navigator.clipboard.read() und navigator.clipboard.readText() lesen beliebigen Text oder binäre Daten aus der Zwischenablage. Diese Methoden ermöglichen Erweiterungen den Zugriff auf Daten in der Zwischenablage, ohne sie in ein bearbeitbares Element einzufügen.

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

Dieser Codeausschnitt ruft den Text aus der Zwischenablage ab und ersetzt den Inhalt des Elements mit der ID "outbox" durch diesen Text.

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". Diese Anforderung besteht auch dann, wenn Sie den Befehl "paste" innerhalb eines vom Benutzer generierten Event-Handlers verwenden, beispielsweise click oder keypress.

Betrachten Sie HTML, das Folgendes enthält:

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

Um den Inhalt des <textarea>-Elements mit der ID "output" aus der Zwischenablage zu setzen, wenn der Benutzer auf die <button>-Schaltfläche "paste" klickt, können Sie folgenden Code verwenden:

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

Browserspezifische Überlegungen

In Chrome:

• Chrome stellt navigator.clipboard nicht für Erweiterungs-Service-Worker bereit, und Offscreen-Dokumente können aufgrund der Anforderungen der API an den Dokumentfokus nicht auf navigator.clipboard zugreifen. Daher müssen Chrome-Erweiterungen die veralteten document.execCommand()-APIs in einem Offscreen-Dokument verwenden oder navigator.clipboard in einem anderen Kontext nutzen, beispielsweise einem Content-Script oder 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() überprü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 Verfügbarkeit der Lese-Methoden der Clipboard API nach der Reaktion des Benutzers auf eine Einfügeaufforderung 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" gesetzt war.

In Safari:

• Die Berechtigung "clipboardWrite" wird nur in Erweiterungskontexten unterstützt (nicht in Content-Scripts).
• Die Berechtigung "clipboardRead" wird nicht unterstützt.

Browser-Kompatibilität

api.Clipboard

webextensions.api.clipboard

Siehe auch

• Clipboard API
• Permissions API
• Inhalte bearbeitbar machen