Zugriff auf die Zwischenablage: synchron und asynchron

Inhaltsverzeichnis

Für die Arbeit mit der Systemzwischenablage stellt die W3C-Spezifikation "Clipboard API and events" zwei APIs zur Verfügung: die synchrone "Clipboard Event API" und die asynchrone "Asynchronous Clipboard API".

Der programmatische Zugriff auf die Zwischenablage innerhalb einer Webanwendung hat in den letzten Jahren einen Wandel durchgemacht. Noch vor ein paar Jahren griff man gerne auf Bibliotheken wie ZeroClipboard zurück, die unter der Haube Flash voraussetzten. Mit dem Verschwinden von Flash in die Bedeutungslosigkeit verloren allerdings auch diese Bibliotheken an Bedeutung. Die execCommand API wiederum, über die man unter anderem programmatisch Befehle wie das Kopieren oder Einfügen ausführen kann, leidet unter Interoperabilitätsproblemen, gilt mittlerweile als veraltet und wird aller Voraussicht auch nicht mehr über den Status eines "Unofficial Draft" hinauskommen. Hinzu kommt, dass hierüber Daten nur aus dem DOM gelesen und auch nur in das DOM geschrieben werden können:

// Achtung: veraltet! 

// Kopieren
const source = document.querySelector("#source"); 
source.select(); 
document.execCommand("copy"); 

// Und Einfügen
const target = document.querySelector("#target"); 
target.focus(); 
document.execCommand("paste");

Beim W3C liegt der Fokus der Entwicklung daher auf der Spezifikation "Clipboard API and events", die aktuell als Working Draft vorliegt. Sie definiert für die Arbeit mit der Systemzwischenablage zwei verschiedene APIs: die Clipboard Event API (bzw. Synchronous Clipboard API) und die relativ neue Asynchronous Clipboard API.

Synchroner Zugriff

Die Clipboard Event API bietet zum einen die Möglichkeit, sich in die gängigen Operationen auf der Zwischenablage "einzuhaken", sprich auf Events zu reagieren, die beim Ausschneiden, Kopieren und Einfügen ausgelöst werden sowie zum anderen synchron schreibend und lesend auf die Zwischenablage zuzugreifen.

Für Ersteres definiert die API vier verschiedene Events:

• "copy": wird ausgelöst, wenn Daten in die Zwischenablage kopiert werden.
• "paste": wird ausgelöst, wenn Daten aus der Zwischenablage eingefügt werden.
• "cut": wird ausgelöst, wenn Daten "ausgeschnitten" und dabei in die Zwischenablage kopiert werden.
• "clipboardchange": wird ausgelöst, wenn der Inhalt der Zwischenablage geändert wird. Dies betrifft im Übrigen auch Änderungen, die außerhalb des Browsers ausgelöst werden. In diesem Fall wird das Event genau dann ausgelöst, wenn der Browser wieder den Fokus erhält.

Auf diese Events kann man, wie in folgendem Listing gezeigt, über entsprechende Event-Listener reagieren. Der EventListener für das copy-Event definiert, was passieren soll, wenn innerhalb der Webseite eine Kopieraktion durchgeführt wird. Über die Eigenschaft clipboardData des entsprechenden Events gelangt man an ein Objekt vom Typ DataTransfer. Zur Erinnerung: Dieses Objekt repräsentiert ein Objekt, das ursprünglich für den Datentransfer bei Drag&Drop-API-Aktionen zuständig ist. Über die Methode setData() können an diesem Transferobjekt die zu übertragenden Daten definiert werden, wobei der Methode als erster Parameter das Format der Daten (in Form des MIME-Typen) und als zweiter Parameter die eigentlichen Daten übergeben werden. Auf der Gegenseite (innerhalb des Event-Listeners, der für die Einfügeoperation zuständig ist) werden analog über die Methode getData() unter Angabe des MIME-Typen die Daten aus dem Transferobjekt gelesen.

document.addEventListener('copy', (event) => {
  const { clipboardData } = event;
  clipboardData.setData(
    'text/plain', 
    'Dieser Text kommt synchron in die Zwischenablage.'
  );
  event.preventDefault();
});

document.addEventListener('paste', (event) => {
  const { clipboardData } = event;
  const data = clipboardData.getData('text/plain');
  console.log(data);
  // => "Dieser Text kommt synchron in die Zwischenablage."
  event.preventDefault();
});

Grundsätzlich kann ein Transferobjekt Daten für verschiedene Formate enthalten. Auf diese Weise lassen sich in einer einzelnen Kopier- beziehungsweise Einfügeoperation die Daten direkt in mehreren Formaten übertragen. Das ist beispielsweise dann praktisch, um abhängig vom Ziel der Einfügeoperation die Daten entweder in dem einen oder dem anderen Format zu verarbeiten beziehungsweise. einzufügen. Folgendes Listing zeigt, wie auf diese Weise gleichzeitig Daten als einfacher Text, als formatierter HTML-Text und als JSON übertragen werden können (da sich die Daten nur als Zeichenkette übergeben lassen, muss im Fall von JSON entsprechend serialisiert (JSON.stringify()) und deserialisiert (JSON.parse()) werden).

document.addEventListener('copy', (event) => {
  const { clipboardData } = event; 
  console.log(clipboardData); 
  clipboardData.setData(
    'text/plain', 
    'Dieser Text kommt synchron in die Zwischenablage.'
  );
  clipboardData.setData(
    'text/html', 
    'Dieser <strong>Text</strong> kommt synchron in die Zwischenablage.'
  ); 
  clipboardData.setData(
    'application/json', 
    JSON.stringify({ 
      message: 'Dieser Text kommt synchron in die Zwischenablage.' 
    })); 
  event.preventDefault();
}); 

document.addEventListener('paste', (event) => { 
  const { clipboardData } = event; 
  const data = clipboardData.getData('text/plain'); 
  console.log(data); 
  // => "Dieser Text kommt synchron in die Zwischenablage." 

  const dataHTML = clipboardData.getData('text/html'); 
  console.log(dataHTML); 
  // => "<meta charset='utf-8'>Dieser <strong>Text</strong> \
  // kommt synchron in die Zwischenablage." 

  const dataJSON = JSON.parse(clipboardData.getData('application/json'));     
  console.log(dataJSON); 
  // => { message: "Dieser Text kommt synchron in die Zwischenablage." }
  event.preventDefault();
});

Asynchroner Zugriff

Der oben beschriebene synchrone Zugriff auf die Zwischenablage eignet sich – weil die Ausführung der Webanwendung während der Kopier- beziehungsweise Einfügeoperation blockiert wird – nur für Daten, die eine überschaubare Größe haben. Möchte man dagegen komplexere oder größere Daten wie Bilddaten in die Zwischenablage kopieren oder aus der Zwischenablage in eine Webanwendung einfügen, greift man besser auf die Asynchronous Clipboard API zurück. Wie der Name vermuten lässt, können Daten hierüber asynchron in die Zwischenablage geschrieben und aus ihr gelesen werden, ohne dass die entsprechenden Operationen dabei den Browser blockieren. Allerdings müssen Nutzer den Zugriff der entsprechenden Webanwendung auf die Zwischenablage erlauben, damit der Einsatz der Asynchronous Clipboard API überhaupt möglich ist.

Der Zugriff auf die API erfolgt über das Objekt navigator.clipboard, das entsprechende Methoden für das Schreiben (write()) sowie das Lesen (read()) bereitstellt. Beide Methoden liefern als Rückgabewert ein Promise-Objekt, sodass sie sich bequem sowohl über die Promise API als auch über async/await verwenden lassen.

Beim Schreiben werden der Methode write() die zu kopierenden Daten in Form eines Arrays von ClipboardItem-Objekten übergeben. Jedem einzelnen Objekt übergibt man die Daten mit einem Konfigurationsobjekt als Schlüssel/Wert-Paare, wobei der Schlüssel das Format repräsentiert und der Wert die Daten als Blob enthält:

const copy = async () => { 
  try { 
    const data = [ 
      new ClipboardItem(
        { 
          'text/plain': new Blob( 
            ['Dieser Text kommt asynchron in die Zwischenablage.'], 
            { type: 'text/plain' } 
          )
        }) ]; 
    await navigator.clipboard.write(data); 
  } catch (error) { 
    console.error(error); 
  } 
} 

Der lesende Zugriff geschieht über die Methode read(), über die man an die entsprechenden Daten in Form eines Arrays von ClipboardItem-Objekte gelangt. Die Eigenschaft types jedes einzelnen ClipboardItem-Objekts enthält die verschiedenen Datenformate, die mit dem Objekt übertragen wurden:

const paste = async () => { 
  try {
    const items = await navigator.clipboard.read();
    for (const item of items) { 
      for (const type of item.types) { 
        const data = await item.getType(type); 
        const text = await data.text(); 
        console.log(text); 
      } 
    } 
  } catch (error) { 
    console.error(error); 
  } 
} 

Mit write() und read() können derzeit Texte und Bilder übertragen werden. Grundsätzlich sind weitere Formate denkbar, beispielsweise solche für Audio- oder Videodaten. Diese werden momentan aber in Bezug auf die Übertragung über die Zwischenablage noch nicht von allen Browsern unterstützt.

Für die Arbeit mit Texten stehen neben write() und read() noch die beiden Convenience-Methoden writeText() und readText() zur Verfügung, über die der Code von eben etwas einfacher gestaltet werden kann, weil man sich nicht mit ClipboardItem- und Blob-Objekten herumschlagen muss:

const copyText = async () => { 
  try { 
    await navigator.clipboard.writeText(
      "Dieser Text kommt asychron in die Zwischenablage."
    ); 
  } catch (error) { 
    console.error(error); 
  } 
}

const pasteText = async () => { 
  try { 
    const text = await navigator.clipboard.readText(); 
    console.log(text); 
  } catch (error) { 
    console.error(error); 
  } 
} 

Fazit

Mit der Asynchronous Clipboard API wird der Zugriff auf die Zwischenablage um einen asynchronen Kommunikationskanal erweitert. Alle "großen" Browser bieten Support für die Clipboard API an, sowohl für die Synchronous Clipboard API als auch für die Asynchronous Clipboard API, wobei der Support für Erstere auch ältere Browserversionen umschließt. Wer auf Nummer sicher gehen möchte, dass die neuere asychrone Version im jeweiligen Browser zur Verfügung steht, kann dies über Feature Detection anhand des navigator.clipboard-Objekts überprüfen. Alternativ kann man auf eine Polyfill-Bibliothek wie clipboard-polyfill oder auf beliebte Alternativen wie clipboard.js zurückgreifen. ()