Clipboard API: kopiointi ja liittäminen Reactissa

navigator.clipboard.writeText(text) kirjoittaa merkkijonon järjestelmän leikepöydälle ja palauttaa Promisen. Se on vanhan execCommand-tavan nykyaikainen korvaaja. Odottakaa Promisea aina await-operaattorilla ja käsitelkää mahdollinen hylkäys, esimerkiksi silloin, kun käyttäjä estää leikepöydän käytön.

navigator.clipboard.readText() lukee leikepöydän nykyisen sisällön merkkijonona ja palauttaa myös Promisen. Lukeminen edellyttää clipboard-read-oikeutta, jonka selain pyytää käyttäjältä. Käytännössä leikepöydältä lukemista käytetään tyypillisissä React-sovelluksissa harvemmin kuin leikepöydälle kirjoittamista.

Selaimet varmistavat, että clipboard.writeText-funktiota voidaan kutsua vain käyttäjän toiminnon käsittelijän sisältä, esimerkiksi napsautus- tai keydown-tapahtumasta. Sen kutsuminen useEffect-funktion sisällä tai asynkronisesti toiminnon jälkeen aiheuttaa suojausvirheen. Käynnistäkää kirjoitus aina suoraan onClick-käsittelijästä.

Yleinen toimintamalli on seuraava: käyttäjä napsauttaa kopiointipainiketta, käsittelijä kutsuu navigator.clipboard.writeText(value)-funktiota, ja onnistumisen jälkeen asetatte copied-tilan arvoksi true. Painike näyttää hetken valintamerkin tai tekstin "Kopioitu!". Lyhyen viiveen jälkeen painike palaa normaalitilaansa.

Kapseloikaa logiikka useCopyToClipboard-hookiin, joka palauttaa tuplen: [copied, copyFn]. copied-totuusarvo ohjaa käyttöliittymän palautetta, ja copyFn ottaa kopioitavan tekstin vastaan. Hook käsittelee asynkronisen kirjoituksen ja mahdolliset virheet sisäisesti, joten komponentit pysyvät yksinkertaisina.

Asettakaa hookissa onnistuneen kopioinnin jälkeen setCopied(true) ja ajoittakaa nollaus kutsulla setTimeout(() => setCopied(false), 2000). Tallentakaa aikakatkaisun tunnus ja tyhjentäkää se useEffect-funktion siivouksessa, jotta tilaa ei päivitetä komponentin irrottamisen jälkeen. Näin vältetään varoitus siitä, ettei irrotetun komponentin tilaa voi päivittää.

Vanhat selaimet ja muut kuin HTTPS-sivut eivät tue Clipboard API:a. Vanha varamenetelmä luo väliaikaisen textarea-elementin, asettaa sen arvon, liittää sen bodyyn, kutsuu document.execCommand('copy')-funktiota ja poistaa elementin. Tämä tapa on synkroninen ja toimii kaikkialla, vaikka se onkin vanhentunut.

Tarkistakaa ennen Clipboard API:n käyttämistä: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. Jos rajapinta ei ole käytettävissä, käyttäkää vanhaa execCommand-tapaa. Tämä varmistava tarkistus estää suoritusnaikaiset virheet ympäristöissä, joissa rajapintaa ei tueta.

Leikepöydältä lukeminen edellyttää käyttäjän lupaa Permissions API:n kautta. Voitte kysyä nykyisen tilan näin: navigator.permissions.query({ name: 'clipboard-read' }) palauttaa PermissionStatus-olion, jonka state voi olla granted, denied tai prompt. Selain pyytää luvan automaattisesti, kun kutsutte readText()-funktiota.

Clipboard API on käytettävissä vain suojatuissa konteksteissa (HTTPS tai localhost). HTTP-sivuilla navigator.clipboard on undefined. Tämä on suojausrajoitus, koska leikepöydän sisältö voi olla arkaluonteista. Tarkistakaa rajapinnan saatavuus aina ennen sen metodien käyttämistä, jotta vältätte null-viitevirheet.

Jestin käyttämä jsdom ei toteuta Clipboard APIa. Simuloikaa se testiasetuksissa: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). Näin voitte testata, että komponenttinne kutsuu writeText-funktiota oikealla argumentilla ilman oikeaa selainympäristöä.

Käyttäkää navigator.clipboard.writeText()-funktiota napsautuksen käsittelijässä tekstin kopioimiseen. Rakentakaa useCopyToClipboard-hook, joka palauttaa [copied, copyFn]-parin ja nollaa tilan ajastetusti. Tarkistakaa aina API:n saatavuus, tarjotkaa vanhemmille selaimille execCommand-varamenetelmä ja simuloikaa navigator.clipboard Jest-testeissä.