Interact with the clipboard

Існує два шляхи взаємодії веб-додатків з буфером обміну:  Document.execCommand() метод і новітній асинхронний Clipboard API.

Document.execCommand() може використовуватись, бажано з наступними командами:

  • document.execCommand("copy")
  • document.execCommand("cut")
  • document.execCommand("paste")

Clipboard API надає асинхронний доступ считування та запису прямо в буфер обміну. Наприклад, щоб зчитати текст з буферу обміну виконайте:

navigator.clipboard.readText().then(text => outputElem.innerText = text);

Ця команда запитує текст в буфері та, та коли відповідь надійде з буферу, вона буде записана прямісенько в елемент innerText.

Примітка: Асинхронний Clipboard API метод нещодавно доданий в специфікацію, і може ще працювати не в усіх веб-оглядачах. Запевнетесь щодо кожного методу в таблиці сумісності перед тим як використовувати його.

Запис в буфер обміну

Існує два шляхи запису в буфер обміну. Ви можете використати document.execCommand() для запиту  "cut" та "copy" дій, які замінюють контент в буфері із виділенним даними. Інша опція це Clipboard API's Clipboard.writeText() чи Clipboard.write().

Використання execCommand()

document.execCommand() метод "cut" та "copy" команди можуть бути використані для заміни буферу із виділенними даними. Ці команди можуть бути виконані без будь яких дозволів, якщо ви використовуєте їх короткочасних обробниках дій користувача(наприклад, обробник кліку).

Наприклад HTML:

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

Із кнопкою "copy" яка копіює контент <input> елементу, ви можете використати код такий як:

function copy() {
  var copyText = document.querySelector("#input");
  copyText.select();
  document.execCommand("copy");
}

document.querySelector("#copy").addEventListener("click", copy);

Тому що execCommand() виклик знаходится всередені обробника кліку, вам не потрібні ніякі спеціальні дозволи.

Однак, якщо наприклад замість того ви копіюєте з alarm:

function copy() {
  var copyText = document.querySelector("#input");
  copyText.select();
  document.execCommand("copy");
}

browser.alarms.create({
  delayInMinutes: 0.1
});

browser.alarms.onAlarm.addListener(copy);

Залежно від веб-оглядача, це може не спрацювати. У Firefox, це не спрацює, і ви побачете повідомлення помилки як:

document.execCommand(‘cut’/‘copy’) was denied because it was not called from inside a short running user-generated event handler.

Щоб надати можливість виконати це, вам потрібно запитати дозвол "clipboardWrite" permission. Тож: "clipboardWrite" дозволяє копіювати поза простих обробників дій користувача.

Використання Clipboard API

Clipboard API додає більшу гнучкість, в такому разі ви не обмежені лише в копіюванні поточного виділення в буфер обміну, ви маєте також можливість вказати будь яку інформацію внести в буфер.

Використання API потребує дозволу "clipboardRead" чи "clipboardWrite" в вашому manifest.json файлі.

Для страничних скриптів, Permissions API's потребує дозвіл "clipboard-write".  Ви можете запросити дозвіл з navigator.permissions.query():

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

Ця функція приймає строку вводу та вносить ії в буфер обміну:

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

Browser-specific considerations

Буфер обміну та інші APIs активно розвиваются, тож існують варіанти серед веб-оглядачів як вони працюють.

В Chrome:

  • Ви можете записувати в буфер обміну як інші операції з контекстом сторінки.
  • Вам не потрібні "clipboardWrite", навіть поза функцією оброки дій користувача(event handler).

В Firefox:

  • Ви можете записувата в буфер з execCommand в усіх обробках контенту, виключно в фонових сторінках. В Firefox ви не можете виділяти текст чи ставити фокус на input в фонових сторінках, тож ви не можете записувати в буфер з execCommand у фонових сторінках. Clipboard Web API не має таких обмежень.
  • З версії 57 і вищче, ви можете копіювати зображення в буфер використовуючи clipboard.setImageData() API.
  • Підтримка Clipboard API's navigator.clipboard.writeText() було додано Firefox 63.
  • Із використанням скриптів сторінок, Clipboard API доступна лише з HTTPS сторінками. В іншому випадку, використовуйте messaging між вашим контент скриптом та фоновим скриптом.

execCommand('copy') API не підтримує Safari

Зчитування буферу обміну

execCommand() дозволяє виконати "paste" команду, яка дозволяє вставити поточний контент в буфері обміну в область редагування. Ви можете отримати більшу гнучкість із  Clipboard API's Clipboard.read() та Clipboard.readText() методами.

Використання execCommand()

По-перше, вам потрібен дозвіл "clipboardRead" permission визначно до вашого додатку. Це обов'язвокі умови навіть якщо "paste" команда виконується в обробнику дій користувача такі як click чи keypress.

Наприклад HTML такий як:

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

Щоб вставити контент в <textarea> з ID "output" з буферу обміну коли користувач нажме на кнопку "paste" <button>, використовуйте код:

function paste() {
  var pasteText = document.querySelector("#output");
  pasteText.focus();
  document.execCommand("paste");
  console.log(pasteText.textContent);
}

document.querySelector("#paste").addEventListener("click", paste);

Використання Clipboard API

Clipboard API's navigator.clipboard.readText() та navigator.clipboard.read() методи дозволяють вам зчитувати  текст чи бінарні данні з буферу обміну. Вона надає можливість зчитувати данні в буфері без вставки його в елемент редагування.

Щойно ви отримали "clipboard-read" дозвіл з Permissions API, ви можете зчитати данні дуже легко:

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

Цей код витягує текст з буферу та замінює контент елементу з ID "outbox".

Browser-specific considerations

Firefox підтримує "clipboardRead" permission з версії 54, але личше підтримує вставку в елементи в content editable mode, які в контент скриптах лише працюють з  <textarea>. Для фонових скриптів, будь який елемент може бути змінений в режим редагування контенту.

Дивись також