Clipboard: write() Methode

Syntax

write(data)

Parameter

data

Ein Array von ClipboardItem-Objekten, die die in die Zwischenablage zu schreibenden Daten enthalten.

Rückgabewert

Ein Promise, das aufgelöst wird, wenn die Daten in die Zwischenablage geschrieben wurden. Beachten Sie, dass, wenn das zugrunde liegende Betriebssystem keine mehrere nativen Zwischenablageelemente auf der Systemzwischenablage unterstützt, nur das erste ClipboardItem im Array geschrieben wird.

Das Promise wird abgelehnt, wenn es nicht möglich ist, in die Zwischenablage zu schreiben.

Ausnahmen

NotAllowedError DOMException

Wird ausgelöst, wenn das Schreiben in die Zwischenablage nicht erlaubt ist.

Sicherheitsüberlegungen

Das Schreiben in die Zwischenablage kann nur in einem sicheren Kontext erfolgen.

Weitere Sicherheitsanforderungen sind im Abschnitt Sicherheitsüberlegungen des API-Übersichtsthemas behandelt.

Beispiele

Text in die Zwischenablage schreiben

Diese Beispielmethode ersetzt den aktuellen Inhalt der Zwischenablage durch eine angegebene Zeichenkette, wenn eine Schaltfläche gedrückt wird. Beachten Sie, dass Sie für diesen speziellen Fall ebenso gut Clipboard.writeText() verwenden könnten.

button.addEventListener("click", () => setClipboard("<empty clipboard>"));

async function setClipboard(text) {
  const type = "text/plain";
  const clipboardItemData = {
    [type]: text,
  };
  const clipboardItem = new ClipboardItem(clipboardItemData);
  await navigator.clipboard.write([clipboardItem]);
}

Die Funktion setClipboard() spezifiziert einen "text/plain" MIME-Typ in der type Konstante und dann ein clipboardItemData Objekt mit einer einzigen Eigenschaft — deren Schlüssel der MIME-Typ ist und deren Wert der übergebene Text ist, den wir in die Zwischenablage schreiben möchten. Anschließend konstruieren wir ein neues ClipboardItem Objekt, in das das clipboardItemData Objekt übergeben wird.

Schließlich wird write() mit await aufgerufen, um die Daten in die Zwischenablage zu schreiben.

Canvas-Inhalte in die Zwischenablage schreiben

Dieses Beispiel zeichnet ein blaues Rechteck auf die Canvas. Sie können auf das Rechteck klicken, um den Inhalt der Canvas als Bild in die Zwischenablage zu kopieren, und dann ein anderes Element auswählen und den Inhalt aus der Zwischenablage einfügen.

HTML

Das HTML definiert nur unser <canvas>-Element und das <div>-Element mit der ID target, in das das Canvas-Bild eingefügt wird.

<canvas id="canvas" width="100" height="100"></canvas>

<div id="target">Paste here.</div>

<pre id="log"></pre>

#log {
  height: 60px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

Wir definieren zuerst eine async Funktion, um eine Canvas in ein Blob zu kopieren. Dies umschließt die alte Callback-basierte Methode HTMLCanvasElement.toBlob() in die intuitivere, auf Promise basierende Funktion.

// Async/await method replacing toBlob() callback
async function getBlobFromCanvas(canvas) {
  return new Promise((resolve, reject) => {
    canvas.toBlob((blob) => {
      if (blob) {
        resolve(blob);
      } else {
        reject(new Error("Canvas toBlob failed"));
      }
    });
  });
}

Als nächstes richten wir unser Canvas ein und fügen einen Event-Listener für das click-Event hinzu.

Wenn Sie auf das blaue Rechteck klicken, wird die Canvas, die das Rechteck anzeigt, in ein Blob kopiert, und dann wird das Blob einem ClipboardItem hinzugefügt und dann in die Zwischenablage geschrieben.

const canvas = document.getElementById("canvas");

// Set up canvas
const ctx = canvas.getContext("2d");
ctx.fillStyle = "cornflowerblue";
ctx.fillRect(0, 0, 100, 100);

canvas.addEventListener("click", copyCanvasContentsToClipboard);
const target = document.getElementById("target");

async function copyCanvasContentsToClipboard() {
  // Copy canvas to blob
  try {
    const blob = await getBlobFromCanvas(canvas);
    // Create ClipboardItem with blob and its type, and add to an array
    const data = [new ClipboardItem({ [blob.type]: blob })];
    // Write the data to the clipboard
    await navigator.clipboard.write(data);
    log("Copied");
  } catch (error) {
    log(error);
  }
}

Beachten Sie, dass Sie, wenn Sie einen weniger verbreiteten Dateityp abholen oder eine Ressource, deren Typ Sie im Voraus nicht kennen, möglicherweise ClipboardItem.supports() verwenden möchten, um zu überprüfen, ob der Dateityp unterstützt wird, und eine aussagekräftige Fehlermeldung an den Benutzer ausgeben, falls dies nicht der Fall ist.

Wir definieren dann einen Event-Listener für paste events auf dem Element, in dem wir die Zwischenablageinhalte als Bild anzeigen möchten. Die FileReader API ermöglicht es uns, das Blob mit der Methode readAsDataURL zu lesen und ein <img>-Element mit den Canvas-Inhalten zu erstellen:

target.addEventListener("paste", (event) => {
  const items = (event.clipboardData || window.clipboardData).items;
  const blob = items[0].getAsFile();
  const reader = new FileReader();

  reader.addEventListener("load", (event) => {
    const img = new Image();
    img.src = event.target.result;
    target.appendChild(img);
  });

  reader.readAsDataURL(blob);
});

body {
  font-family: sans-serif;
}
#target {
  border: 2px solid;
  padding: 1rem;
  height: 150px;
}
img {
  margin: 0.5rem;
}

Ergebnis

Das Ergebnis wird unten angezeigt. Klicken Sie zuerst auf das blaue Quadrat und wählen Sie dann den Text "Hier einfügen" und verwenden Sie Ihre OS-spezifischen Tastenkombinationen, um aus der Zwischenablage einzufügen (wie Strg+V auf Windows).

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Clipboard API
• Bildunterstützung für Async Clipboard Artikel
• Clipboard.writeText()
• Clipboard.read()
• Clipboard.readText()