Interaktion mit der Zwischenablage

Schreiben in die Zwischenablage

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 jedoch nur, nachdem der Benutzer der Erweiterung eine transiente Aktivierung vorgenommen hat. Mit der Berechtigung "clipboardWrite" ist jedoch keine transiente Aktivierung erforderlich.

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

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

Verwendung von execCommand()

Die Befehle "cut" und "copy" der Methode document.execCommand() werden verwendet, um den Inhalt der Zwischenablage mit dem ausgewählten Material zu ersetzen. Erweiterungen können diese Befehle ohne spezielle Berechtigung in kurzlebigen Ereignishandlern verwenden, die durch Benutzeraktionen ausgelöst werden (zum Beispiel ein Klick-Handler).

Angenommen, Sie haben ein Popup, das dieses HTML enthält:

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

Um die Schaltfläche "copy" dazu zu bringen, den Inhalt des <input>-Elements zu kopieren, 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 execCommand()-Aufruf innerhalb eines Klick-Ereignishandlers erfolgt, benötigt Ihre Erweiterung keine besonderen Berechtigungen.

Betrachten Sie jedoch das Beispiel, bei dem Ihre Erweiterung die Kopie von einem 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 Sie sehen eine Meldung wie diese in der Konsole:

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

Um diesen Anwendungsfall zu ermöglichen, muss Ihre Erweiterung die Berechtigung "clipboardWrite" anforderung: "clipboardWrite" ermöglicht es Ihrer Erweiterung, außerhalb eines kurzlebigen Ereignishandlers für eine Benutzeraktion in die Zwischenablage zu 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. Diese Methoden ermöglichen es Erweiterungen, auf Daten in der Zwischenablage zuzugreifen, ohne sie in ein bearbeitbares Element einfügen zu müssen.

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

Dieser Codeausschnitt holt den Text aus der Zwischenablage und ersetzt den Inhalt des Elements mit der ID "outbox" durch diesen Text:

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

Verwendung von execCommand()

Um document.execCommand("paste") zu verwenden, benötigt Ihre Erweiterung die Berechtigung "clipboardRead" /anforderung. Diese Anforderung besteht, auch wenn Sie den Befehl "paste" innerhalb eines nutzergenerierten Ereignishandlers verwenden, wie z.B. click oder keypress.

Stellen Sie sich HTML vor, das Folgendes enthält:

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

Um den Inhalt des <textarea>-Elements mit der ID "output" von der Zwischenablage zu setzen, wenn der Benutzer auf die Schaltfläche "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);

Browser-spezifische Überlegungen

In Chrome:

• Chrome stellt navigator.clipboard für Erweiterungs-Service-Worker nicht bereit und Offscreen-Dokumente können wegen der Anforderungen der API an die Dokumentenfokussierung nicht auf navigator.clipboard zugreifen. Daher müssen Chrome-Erweiterungen entweder die veralteten document.execCommand()-APIs in einem Offscreen-Dokument verwenden oder navigator.clipboard in einem anderen Kontext, wie z.B. einem Content-Skript oder einer Erweiterungsseite, nutzen. Damit Seitenskripte ohne Benutzerinteraktion in die Zwischenablage schreiben können, muss die Berechtigung "clipboard-write" mit der 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 oder Safari nicht unterstützt.

In Firefox:

• Die Verfügbarkeit der Lese-Methoden der Clipboard API als Reaktion des Benutzers auf eine Einfügeaufforderung wurde für Webseiten in Firefox 127 und Erweiterungen in Firefox 147 eingeführt. Zuvor 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
• Inhalt bearbeitbar machen