Berhenti memblokir akses papan klip

Akses papan klip yang lebih aman dan tidak diblokir untuk teks dan gambar

Cara tradisional untuk mendapatkan akses ke papan klip sistem adalah melalui document.execCommand() untuk interaksi papan klip. Meskipun didukung secara luas, metode pemotongan dan penempelan ini memiliki biaya: akses papan klip bersifat sinkron, dan hanya dapat membaca dan menulis ke DOM.

Hal ini tidak masalah untuk teks yang sangat kecil, tetapi sering kali pemblokiran halaman untuk transfer papan klip merupakan pengalaman yang buruk. Sanitasi atau dekode gambar yang memakan waktu mungkin diperlukan sebelum konten dapat ditempel dengan aman. Browser mungkin perlu memuat atau membuat resource tertaut menjadi inline dari dokumen yang ditempelkan. Tindakan itu akan memblokir halaman saat menunggu di {i>disk<i} atau jaringan. Bayangkan jika Anda menambahkan izin ke dalam campuran, browser harus memblokir halaman saat meminta akses papan klip. Pada saat yang sama, izin yang diterapkan di sekitar document.execCommand() untuk interaksi papan klip ditentukan secara longgar dan bervariasi antar-browser.

Async Clipboard API dapat mengatasi masalah ini, dengan menyediakan model izin yang jelas yang tidak memblokir halaman. Async Clipboard API terbatas untuk menangani teks dan gambar di sebagian besar browser, tetapi dukungannya bervariasi. Pastikan Anda mempelajari dengan cermat ringkasan kompatibilitas browser untuk setiap bagian berikut.

Salin: menulis data ke papan klip

writeText()

Untuk menyalin teks ke papan klip, panggil writeText(). Karena API ini asinkron, fungsi writeText() menampilkan Promise yang di-resolve atau ditolak, bergantung pada apakah teks yang diteruskan berhasil disalin:

async function copyPageUrl() {
  try {
    await navigator.clipboard.writeText(location.href);
    console.log('Page URL copied to clipboard');
  } catch (err) {
    console.error('Failed to copy: ', err);
  }
}

write()

Sebenarnya, writeText() hanyalah metode praktis untuk metode write() generik, yang juga memungkinkan Anda menyalin gambar ke papan klip. Seperti writeText(), metode ini asinkron dan menampilkan Promise.

Untuk menulis gambar ke papan klip, Anda memerlukan gambar sebagai blob. Salah satu cara untuk melakukannya adalah dengan meminta image dari server menggunakan fetch(), lalu memanggil blob() pada respons.

Anda mungkin tidak menginginkan gambar dari server karena berbagai alasan. Untungnya, Anda juga dapat menggambar gambar ke kanvas dan memanggil metode toBlob() kanvas.

Selanjutnya, teruskan array objek ClipboardItem sebagai parameter ke metode write(). Saat ini, Anda hanya dapat meneruskan satu gambar pada satu waktu, tetapi kami berharap dapat menambahkan dukungan untuk beberapa gambar pada masa mendatang. ClipboardItem mengambil objek dengan jenis MIME gambar sebagai kunci dan blob sebagai nilainya. Untuk objek blob yang diperoleh dari fetch() atau canvas.toBlob(), properti blob.type secara otomatis berisi jenis MIME yang benar untuk sebuah gambar.

try {
  const imgURL = '/images/generic/file.png';
  const data = await fetch(imgURL);
  const blob = await data.blob();
  await navigator.clipboard.write([
    new ClipboardItem({
      // The key is determined dynamically based on the blob's type.
      [blob.type]: blob
    })
  ]);
  console.log('Image copied.');
} catch (err) {
  console.error(err.name, err.message);
}

Atau, Anda dapat menulis promise ke objek ClipboardItem. Untuk pola ini, Anda perlu mengetahui jenis MIME data terlebih dahulu.

try {
  const imgURL = '/images/generic/file.png';
  await navigator.clipboard.write([
    new ClipboardItem({
      // Set the key beforehand and write a promise as the value.
      'image/png': fetch(imgURL).then(response => response.blob()),
    })
  ]);
  console.log('Image copied.');
} catch (err) {
  console.error(err.name, err.message);
}

Peristiwa penyalinan

Jika pengguna memulai penyalinan papan klip dan tidak memanggil preventDefault(), peristiwa copy menyertakan properti clipboardData dengan item yang sudah dalam format yang tepat. Jika ingin mengimplementasikan logika sendiri, Anda harus memanggil preventDefault() untuk mencegah perilaku default yang mendukung penerapan Anda sendiri. Dalam hal ini, clipboardData akan kosong. Pertimbangkan halaman yang berisi teks dan gambar, dan saat pengguna memilih semua serta memulai salinan papan klip, solusi kustom Anda harus menghapus teks dan hanya menyalin gambar. Anda dapat melakukannya seperti yang ditunjukkan dalam contoh kode di bawah ini. Hal yang tidak tercakup dalam contoh ini adalah cara kembali ke API sebelumnya saat Clipboard API tidak didukung.

<!-- The image we want on the clipboard. -->
<img src="kitten.webp" alt="Cute kitten.">
<!-- Some text we're not interested in. -->
<p>Lorem ipsum</p>

document.addEventListener("copy", async (e) => {
  // Prevent the default behavior.
  e.preventDefault();
  try {
    // Prepare an array for the clipboard items.
    let clipboardItems = [];
    // Assume `blob` is the blob representation of `kitten.webp`.
    clipboardItems.push(
      new ClipboardItem({
        [blob.type]: blob,
      })
    );
    await navigator.clipboard.write(clipboardItems);
    console.log("Image copied, text ignored.");
  } catch (err) {
    console.error(err.name, err.message);
  }
});

Untuk peristiwa copy:

Untuk ClipboardItem:

Tempelkan: membaca data dari papan klip

readText()

Untuk membaca teks dari papan klip, panggil navigator.clipboard.readText() dan tunggu hingga promise yang ditampilkan selesai:

async function getClipboardContents() {
  try {
    const text = await navigator.clipboard.readText();
    console.log('Pasted content: ', text);
  } catch (err) {
    console.error('Failed to read clipboard contents: ', err);
  }
}

read()

Metode navigator.clipboard.read() juga asinkron dan menampilkan promise. Untuk membaca gambar dari papan klip, dapatkan daftar objek ClipboardItem, lalu lakukan iterasi pada objek tersebut.

Setiap ClipboardItem dapat menyimpan kontennya dalam berbagai jenis, sehingga Anda harus melakukan iterasi pada daftar jenis, lagi menggunakan loop for...of. Untuk setiap jenis, panggil metode getType() dengan jenis saat ini sebagai argumen untuk mendapatkan blob yang sesuai. Seperti sebelumnya, kode ini tidak terikat dengan gambar, dan akan berfungsi dengan jenis file lainnya di masa mendatang.

async function getClipboardContents() {
  try {
    const clipboardItems = await navigator.clipboard.read();
    for (const clipboardItem of clipboardItems) {
      for (const type of clipboardItem.types) {
        const blob = await clipboardItem.getType(type);
        console.log(URL.createObjectURL(blob));
      }
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}

Bekerja dengan file yang ditempelkan

Fitur ini berguna bagi pengguna untuk dapat menggunakan pintasan keyboard papan klip, seperti ctrl+c dan ctrl+v. Chromium mengekspos file hanya baca di papan klip seperti yang diuraikan di bawah ini. Hal ini terpicu saat pengguna menekan pintasan tempel default sistem operasi atau saat pengguna mengklik Edit lalu Tempel di panel menu browser. Tidak diperlukan kode saluran air lebih lanjut.

document.addEventListener("paste", async e => {
  e.preventDefault();
  if (!e.clipboardData.files.length) {
    return;
  }
  const file = e.clipboardData.files[0];
  // Read the file's contents, assuming it's a text file.
  // There is no way to write back to it.
  console.log(await file.text());
});

Peristiwa menempelkan

Seperti yang telah disebutkan sebelumnya, ada rencana untuk memperkenalkan peristiwa agar berfungsi dengan Clipboard API, tetapi untuk saat ini Anda dapat menggunakan peristiwa paste yang sudah ada. Fitur ini berfungsi dengan baik dengan metode asinkron baru untuk membaca teks papan klip. Seperti halnya peristiwa copy, jangan lupa untuk memanggil preventDefault().

document.addEventListener('paste', async (e) => {
  e.preventDefault();
  const text = await navigator.clipboard.readText();
  console.log('Pasted text: ', text);
});

Menangani beberapa jenis MIME

Sebagian besar implementasi menempatkan beberapa format data di papan klip untuk satu operasi pemotongan atau penyalinan. Ada dua alasan untuk hal ini: sebagai developer aplikasi, Anda tidak memiliki cara untuk mengetahui kemampuan aplikasi yang ingin dijadikan tujuan penyalinan teks atau gambar oleh pengguna, dan banyak aplikasi mendukung penempelan data terstruktur sebagai teks biasa. Opsi ini biasanya ditampilkan kepada pengguna dengan item menu Edit dengan nama seperti Tempel dan cocokkan gaya atau Tempel tanpa format.

Contoh berikut menunjukkan cara melakukannya. Contoh ini menggunakan fetch() untuk mendapatkan data gambar, tetapi juga dapat berasal dari <canvas> atau File System Access API.

async function copy() {
  const image = await fetch('kitten.png').then(response => response.blob());
  const text = new Blob(['Cute sleeping kitten'], {type: 'text/plain'});
  const item = new ClipboardItem({
    'text/plain': text,
    'image/png': image
  });
  await navigator.clipboard.write([item]);
}

Keamanan dan izin

Akses papan klip selalu menghadirkan permasalahan keamanan bagi {i>browser<i}. Tanpa izin yang tepat, halaman dapat tanpa suara menyalin segala jenis konten berbahaya ke papan klip pengguna yang akan memberikan hasil fatal saat ditempel. Bayangkan halaman web yang secara diam-diam menyalin rm -rf / atau gambar bom dekompresi ke papan klip Anda.

Memberikan akses baca ke papan klip secara tidak terbatas pada halaman web akan menjadi lebih merepotkan. Pengguna secara rutin menyalin informasi sensitif seperti sandi dan detail pribadi ke papan klip, yang kemudian dapat dibaca oleh halaman mana pun tanpa sepengetahuan pengguna.

Seperti banyak API baru, Clipboard API hanya didukung untuk halaman yang ditayangkan melalui HTTPS. Untuk membantu mencegah penyalahgunaan, akses papan klip hanya diizinkan jika halaman dalam tab aktif. Halaman di tab aktif dapat menulis ke papan klip tanpa meminta izin, tetapi membaca dari papan klip selalu memerlukan izin.

Izin untuk salin dan tempel telah ditambahkan ke Permissions API. Izin clipboard-write diberikan secara otomatis ke halaman saat halaman tersebut adalah tab aktif. Izin clipboard-read harus diminta, yang dapat Anda lakukan dengan mencoba membaca data dari papan klip. Kode di bawah menunjukkan yang kedua:

const queryOpts = { name: 'clipboard-read', allowWithoutGesture: false };
const permissionStatus = await navigator.permissions.query(queryOpts);
// Will be 'granted', 'denied' or 'prompt':
console.log(permissionStatus.state);

// Listen for changes to the permission state
permissionStatus.onchange = () => {
  console.log(permissionStatus.state);
};

Anda juga dapat mengontrol apakah gestur pengguna diperlukan untuk memanggil memotong atau menempel menggunakan opsi allowWithoutGesture. Nilai default untuk nilai ini bervariasi menurut browser, jadi Anda harus selalu menyertakannya.

Di sinilah sifat asinkron Clipboard API benar-benar berguna: mencoba membaca atau menulis data papan klip secara otomatis meminta izin pengguna jika belum diberikan. Karena API berbasis promise, API ini sepenuhnya transparan, dan pengguna yang menolak izin papan klip menyebabkan janji ditolak sehingga halaman dapat merespons dengan tepat.

Karena browser hanya mengizinkan akses papan klip saat halaman adalah tab aktif, Anda akan melihat bahwa beberapa contoh di sini tidak akan dijalankan jika ditempelkan langsung ke konsol browser, karena alat developer itu sendiri adalah tab aktif. Ada triknya: tunda akses papan klip menggunakan setTimeout(), lalu klik cepat di dalam halaman untuk memfokusnya sebelum fungsi dipanggil:

setTimeout(async () => {
  const text = await navigator.clipboard.readText();
  console.log(text);
}, 2000);

Integrasi kebijakan izin

Untuk menggunakan API di iframe, Anda harus mengaktifkannya dengan Kebijakan Izin, yang mendefinisikan mekanisme yang memungkinkan untuk mengaktifkan dan menonaktifkan berbagai fitur browser dan API secara selektif. Singkatnya, Anda harus meneruskan salah satu atau kedua clipboard-read atau clipboard-write, bergantung pada kebutuhan aplikasi Anda.

<iframe
    src="index.html"
    allow="clipboard-read; clipboard-write"
>
</iframe>

Deteksi fitur

Untuk menggunakan Async Clipboard API sekaligus mendukung semua browser, uji navigator.clipboard dan kembali ke metode sebelumnya. Misalnya, berikut ini cara Anda mengimplementasikan tempel untuk menyertakan {i>browser<i} lain.

document.addEventListener('paste', async (e) => {
  e.preventDefault();
  let text;
  if (navigator.clipboard) {
    text = await navigator.clipboard.readText();
  }
  else {
    text = e.clipboardData.getData('text/plain');
  }
  console.log('Got pasted text: ', text);
});

Hal ini belum tentu secara keseluruhan. Sebelum Async Clipboard API, ada berbagai penerapan salin dan tempel yang berbeda di seluruh browser web. Di sebagian besar browser, salin dan tempel browser sendiri dapat dipicu menggunakan document.execCommand('copy') dan document.execCommand('paste'). Jika teks yang akan disalin adalah string yang tidak ada dalam DOM, teks tersebut harus dimasukkan ke dalam DOM dan dipilih:

button.addEventListener('click', (e) => {
  const input = document.createElement('input');
  input.style.display = 'none';
  document.body.appendChild(input);
  input.value = text;
  input.focus();
  input.select();
  const result = document.execCommand('copy');
  if (result === 'unsuccessful') {
    console.error('Failed to copy text.');
  }
  input.remove();
});

Demo

Anda dapat mencoba Async Clipboard API dalam demo di bawah ini. Di Glitch, Anda dapat me-remix demo teks atau demo gambar untuk bereksperimen dengannya.

Contoh pertama menunjukkan cara memindahkan teks ke dalam dan keluar dari papan klip.

Untuk mencoba API dengan gambar, gunakan demo ini. Ingat bahwa hanya PNG yang didukung dan hanya di beberapa browser.

Link terkait

• MDN
• Format kustom web

Ucapan terima kasih

Asynchronous Clipboard API diimplementasikan oleh Darwin Huang dan Gary Kačmarčík. Darwin juga menyediakan demonya. Terima kasih kepada Kyarik dan sekali lagi Gary Kačmarčík telah meninjau sebagian dari artikel ini.

Banner besar oleh Markus Winkler di Unsplash.