Буфер обмена: метод write()

Метод write() интерфейса Clipboard записывает произвольные данные ClipboardItem, такие как изображения и текст, в буфер обмена, выполняя возвращённую Promise по завершении. Это можно использовать для реализации функций вырезания и копирования.

Метод теоретически может записывать произвольные данные (в отличие от writeText(), который может записывать только текст). Браузеры обычно поддерживают запись данных текстового, HTML и PNG-изображений.

data

Массив объектов ClipboardItem, содержащих данные, которые нужно записать в буфер обмена.

Promise, который разрешается, когда данные записаны в буфер обмена. Обратите внимание, что если операционная система не поддерживает несколько нативных элементов буфера обмена в системном буфере обмена, то записывается только первый ClipboardItem в массиве.

Обещание отклоняется, если буфер обмена не может записать в буфер обмена.

NotAllowedError DOMException

Выбрасывается, если запись в буфер обмена запрещена.

Запись в буфер обмена может выполняться только в безопасном контексте.

Дополнительные требования к безопасности описаны в разделе «Учёт мер безопасности» в описании API.

В этом примере функция заменяет текущее содержимое буфера обмена заданной строкой при нажатии кнопки. Обратите внимание, что в данном случае вы могли бы использовать Clipboard.writeText().

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]);
}

Функция setClipboard() задаёт тип MIME "text/plain" в константе type, затем задаёт объект clipboardItemData, имеющий единственное свойство — его ключ — это тип MIME, а его значение — это передаваемый текст, который мы хотим записать в буфер обмена. Затем мы создаём новый объект ClipboardItem, в который передаём объект clipboardItemData.

Наконец, вызывается write() с await, чтобы записать данные в буфер обмена.

В этом примере на холст рисуется синий прямоугольник. Вы можете нажать на прямоугольник, чтобы скопировать содержимое холста в буфер обмена как изображение, а затем выбрать другой элемент и вставить содержимое из буфера обмена.

HTML

HTML просто определяет наш элемент <canvas> и элемент <div> с id target, где будет вставлено изображение холста.

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

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

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

JavaScript

Сначала мы определяем функцию async для копирования холста в blob. Она оборачивает старый метод HTMLCanvasElement.toBlob() в стиле обратного вызова в более удобную функцию на основе Promise.

// 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"));
      }
    });
  });
}

Далее мы настраиваем наш холст и добавляем обработчик событий для события click.

При нажатии на синий прямоугольник код сначала проверяет, поддерживает ли буфер обмена данные типа "image/png". Если да, то изображение холста, отображающее прямоугольник, копируется в blob, а затем blob добавляется в ClipboardItem и записывается в буфер обмена.

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() {
  if (ClipboardItem.supports("image/png")) {
    // Copy canvas to blob
    try {
      const blob = await getBlobFromCanvas(canvas);
      // Create ClipboardItem with blob and it's 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);
    }
  } else {
    log("image/png is not supported");
  }
}

Обратите внимание, что поддержка буфером обмена PNG-файлов является обязательной частью спецификации, поэтому нам не нужно проверять с помощью ClipboardItem.supports() выше (она всегда возвращает true). Проверка будет более полезной в случаях, когда мы получаем необязательный тип файла или ресурс, тип которого мы не знаем заранее.

Затем мы определяем обработчик событий для событий вставки в элемент, где мы хотим отобразить содержимое буфера обмена в виде изображения. API FileReader позволяет нам прочитать blob с помощью метода readAsDataUrl и создать элемент <img> с содержимым холста:

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);
});

Результат

Результат показан ниже. Сначала щелкните по синему квадрату, а затем выберите текст «Вставить здесь» и используйте сочетания клавиш своей ОС для вставки из буфера обмена (например, Ctrl+V в Windows).

• API буфера обмена
• Статья о поддержке изображений в асинхронном буфере обмена
• Clipboard.writeText()
• Clipboard.read()
• Clipboard.readText()