Clipboard API: Menyalin dan Menempel di React

navigator.clipboard.writeText(text) menulis string ke papan klip sistem dan mengembalikan hasil asinkron. Ini merupakan pengganti modern untuk pendekatan lama execCommand. Selalu tunggu hasilnya hingga selesai dan tangani kemungkinan penolakan, misalnya ketika pengguna menolak akses papan klip.

navigator.clipboard.readText() membaca isi papan klip saat ini sebagai teks dan juga mengembalikan hasil asinkron. Pembacaan memerlukan izin clipboard-read, yang akan diminta oleh peramban kepada pengguna. Dalam praktiknya, pembacaan papan klip lebih jarang digunakan daripada penulisan dalam aplikasi React pada umumnya.

Peramban menetapkan bahwa clipboard.writeText hanya dapat dipanggil di dalam penangan gestur pengguna, seperti peristiwa klik atau penekanan tombol. Memanggilnya di dalam useEffect atau secara asinkron setelah gestur akan menimbulkan kesalahan keamanan. Selalu picu penulisan secara langsung dari penangan onClick.

Pola standarnya adalah: pengguna mengeklik tombol salin, penangan Anda memanggil navigator.clipboard.writeText(value), setelah berhasil Anda menetapkan status copied ke true, dan tombol untuk sementara menampilkan tanda centang atau label "Tersalin!". Setelah jeda singkat, tombol kembali ke keadaan normal.

Rangkum logika ini dalam pengait useCopyToClipboard yang mengembalikan tupel: [copied, copyFn]. Nilai benar-salah copied mengendalikan umpan balik antarmuka, sedangkan copyFn menerima teks yang akan disalin. Pengait ini menangani penulisan asinkron dan kesalahan apa pun secara internal agar komponen tetap sederhana.

Di dalam pengait, setelah penyalinan berhasil, tetapkan setCopied(true) dan jadwalkan pengaturan ulang dengan setTimeout(() => setCopied(false), 2000). Simpan ID pengatur waktu dan hapus ID tersebut dalam pembersihan useEffect untuk mencegah pembaruan status setelah komponen dilepas. Cara ini menghindari peringatan "tidak dapat memperbarui status pada komponen yang telah dilepas".

Peramban lama dan halaman non-HTTPS tidak mendukung API Papan Klip. Cadangan lama ini membuat textarea sementara, menetapkan nilainya, menambahkannya ke badan dokumen, memanggil document.execCommand('copy'), lalu menghapus elemennya. Pendekatan ini berjalan secara sinkron dan berfungsi di mana saja, meskipun sudah tidak digunakan lagi.

Sebelum menggunakan API Papan Klip, lakukan pemeriksaan: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. Jika tidak tersedia, gunakan pendekatan lama execCommand. Pemeriksaan pencegahan ini mencegah kesalahan saat dijalankan di lingkungan yang tidak mendukung API tersebut.

Pembacaan papan klip memerlukan izin pengguna melalui API Izin. Anda dapat menanyakan status saat ini: navigator.permissions.query({ name: 'clipboard-read' }) mengembalikan PermissionStatus dengan state berupa granted, denied, atau prompt. Peramban akan meminta izin secara otomatis ketika Anda memanggil readText().

API Papan Klip hanya tersedia dalam konteks aman (HTTPS atau localhost). Pada halaman HTTP, navigator.clipboard bernilai undefined. Ini merupakan pembatasan keamanan karena isi papan klip dapat bersifat sensitif. Selalu periksa ketersediaan API sebelum merujuk ke metodenya untuk menghindari kesalahan referensi null.

jsdom (yang digunakan oleh Jest) tidak mengimplementasikan API Papan Klip. Buat tiruan API tersebut dalam penyiapan pengujian Anda: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). Dengan demikian, Anda dapat menguji bahwa komponen memanggil writeText dengan argumen yang benar tanpa lingkungan peramban sungguhan.

Kapan navigator.clipboard.writeText() dapat dipanggil dengan aman di peramban?

Gunakan navigator.clipboard.writeText() di dalam penangan klik untuk menyalin teks. Buat hook useCopyToClipboard yang mengembalikan [copied, copyFn] dengan pengaturan ulang berjangka waktu. Selalu periksa ketersediaan API, sediakan alternatif execCommand untuk peramban lama, dan buat tiruan navigator.clipboard dalam pengujian Jest.