Interaktion mit der Zwischenablage

Schreiben in die Zwischenablage

Dieser Abschnitt beschreibt die Möglichkeiten, Daten in die Zwischenablage zu schreiben.

Verwendung der Clipboard API

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

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

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

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 "cut"- und "copy"-Befehle der Methode document.execCommand() werden verwendet, um den Inhalt der Zwischenablage mit dem ausgewählten Material zu ersetzen. Diese Befehle können ohne besondere Berechtigung in kurzlebigen Ereignis-Handlern für eine Benutzeraktion (z. B. ein Klick-Handler) verwendet werden.

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

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

Um den "copy"-Button so einzustellen, dass er den Inhalt des <input>-Elements kopiert, 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 der execCommand()-Aufruf innerhalb eines Klick-Ereignis-Handlers liegt, sind keine speziellen Berechtigungen erforderlich.

Angenommen, Sie möchten stattdessen die Kopie von einem Alarm auslösen:

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 es nicht funktionieren und Sie sehen eine Meldung wie diese in Ihrer Konsole:

document.execCommand('cut'/'copy') wurde abgelehnt, weil es nicht innerhalb eines kurzlebigen, benutzergenerierten Ereignis-Handlers aufgerufen wurde.

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

Browserspezifische Überlegungen

Die Zwischenablage und andere beteiligte APIs entwickeln sich rasch weiter, sodass es zwischen den Browsern Unterschiede gibt, wie sie funktionieren.

In Chrome:

• Sie benötigen nicht "clipboardWrite", selbst um außerhalb eines benutzergenerierten Ereignis-Handlers in die Zwischenablage zu schreiben.

In Firefox:

• navigator.clipboard.write() wird nicht unterstützt.

Siehe die Browser-Kompatibilitätstabelle für weitere Informationen.

Lesen aus der Zwischenablage

Dieser Abschnitt beschreibt die Möglichkeiten, Daten aus der Zwischenablage zu lesen oder einzufügen.

Verwendung der Clipboard API

Die Methoden navigator.clipboard.readText() und navigator.clipboard.read() der Clipboard API erlauben Ihnen das Lesen von beliebigem Text oder Binärdaten aus der Zwischenablage in sicheren Kontexten. Dies ermöglicht den Zugriff auf Daten in der Zwischenablage, ohne sie in ein bearbeitbares Element einzufügen.

Sobald Sie die Berechtigung "clipboard-read" von der Permissions API haben, können Sie problemlos aus der Zwischenablage lesen. Zum Beispiel holt dieses Codesnippet 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" anfordern. Dies ist auch der Fall, wenn Sie den "paste"-Befehl innerhalb eines benutzergenerierten Ereignis-Handlers wie click oder keypress verwenden.

Betrachten Sie HTML, das in etwa so aussieht:

<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 den "paste" <button> 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

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

Browser-Kompatibilität

api.Clipboard

webextensions.api.clipboard

Siehe auch

• Clipboard API
• Permissions API
• Inhalte bearbeitbar machen