Sblocco dell'accesso agli appunti

Accesso più sicuro e sbloccato agli appunti per testo e immagini

Il modo tradizionale per accedere agli appunti di sistema era tramite document.execCommand() per le interazioni con gli appunti. Sebbene ampiamente supportato, questo metodo di taglio e L'operazione di incollare ha avuto un costo: l'accesso agli appunti era sincrono e poteva solo leggere e scrivere nel DOM.

Questo va bene per frammenti di testo di piccole dimensioni, ma ci sono molti casi in cui il blocco pagina per il trasferimento degli appunti è un'esperienza negativa. La sanificazione richiede molto tempo potrebbe essere necessaria la decodifica delle immagini per poter incollare i contenuti in modo sicuro. Il browser potrebbe dover caricare o incorporare risorse collegate da un documento incollato. Ciò significherebbe bloccare la pagina mentre si attendono sul disco o sulla rete. Immagina di aggiungere delle autorizzazioni nel mix, richiedendo che il browser blocchi la pagina durante la richiesta. accesso agli appunti. Allo stesso tempo, le autorizzazioni messe in atto document.execCommand() per l'interazione con gli appunti è definito a basso livello e può variare tra i browser.

La API Async Clipboard risolve questi problemi, fornendo un modello di autorizzazioni ben definito che non bloccare la pagina. L'API Async Clipboard è limitata alla gestione di testo e immagini sulla maggior parte dei browser, ma il supporto varia. Assicurati di studiare attentamente il browser panoramica della compatibilità per ognuna delle sezioni seguenti.

Copy: scrittura di dati negli appunti

writeText()

Per copiare il testo negli appunti, chiama writeText(). Poiché questa API è asincrona, la funzione writeText() restituisce una promessa che si risolve o rifiuta a seconda che il testo passato sia stato copiato o meno:

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()

In realtà, writeText() è solo un metodo di convenienza per il valore generico write() che consente anche di copiare immagini negli appunti. Come writeText(), è asincrono e restituisce una promessa.

Per scrivere un'immagine negli appunti, hai bisogno dell'immagine blob Un modo per farlo richiedendo l'immagine a un server utilizzando fetch(), quindi chiamando blob() il la risposta corretta.

La richiesta di un'immagine al server potrebbe non essere desiderabile o possibile per un per diversi motivi. Fortunatamente, puoi anche disegnare l'immagine su un canvas e chiama la tela" toBlob() .

Quindi, passa un array di oggetti ClipboardItem come parametro a write() . Al momento puoi trasmettere una sola immagine alla volta, ma ci auguriamo di poter aggiungere di immagini in futuro. ClipboardItem prende un oggetto con il tipo MIME dell'immagine come chiave e il blob come valore. Per blob oggetti ottenuti da fetch() o canvas.toBlob(), la proprietà blob.type contiene automaticamente il tipo MIME corretto per un'immagine.

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

In alternativa, puoi scrivere una promessa per l'oggetto ClipboardItem. Per questo pattern, devi conoscere in anticipo il tipo MIME dei dati.

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

L'evento di copia

Nel caso in cui un utente avvii una copia degli appunti e non chiama preventDefault(), Evento copy include una proprietà clipboardData con gli elementi già nel formato corretto. Se vuoi implementare la tua logica, devi chiamare preventDefault() a impedire il comportamento predefinito a favore della tua implementazione. In questo caso, il campo clipboardData sarà vuoto. Considera una pagina con testo e un'immagine e quando l'utente li seleziona tutti e avvia una copia degli appunti, la soluzione personalizzata dovrebbe ignorare il testo e e copio l'immagine. Puoi farlo come mostrato nell'esempio di codice riportato di seguito. Ciò che non viene trattato in questo esempio è come tornare API quando l'API Clipboard non è supportata.

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

Per l'evento copy:

Per ClipboardItem:

Incolla: lettura dei dati degli appunti

readText()

Per leggere il testo negli appunti, chiama navigator.clipboard.readText() e attendi per risolvere la promessa restituita:

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()

Anche il metodo navigator.clipboard.read() è asincrono e restituisce un la promessa. Per leggere un'immagine dagli appunti, recupera un elenco di ClipboardItem ed eseguire l'iterazione su di essi.

Ogni ClipboardItem può contenere contenuti di tipi diversi, quindi dovrai Esegui l'iterazione dell'elenco dei tipi, sempre utilizzando un loop for...of. Per ogni tipo, chiama il metodo getType() con il tipo corrente come argomento per ottenere blob corrispondente. Come in precedenza, questo codice non è legato alle immagini e lavorare con altri tipi di file futuri.

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

Utilizzare i file incollati

È utile per gli utenti essere in grado di utilizzare le scorciatoie da tastiera degli appunti, come Ctrl+C e Ctrl+V. Chromium espone i file di sola lettura negli appunti come descritto di seguito. Si attiva quando l'utente fa clic sulla scorciatoia predefinita del sistema operativo per incollare oppure quando l'utente fa clic su Modifica e poi su Incolla nella barra dei menu del browser. Non sono necessari ulteriori codici idraulico.

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

L'evento Incolla

Come indicato in precedenza, sono in programma l'introduzione di eventi da utilizzare con l'API Clipboard, ma per ora puoi usare l'evento paste esistente. Funziona bene con il nuovo metodi asincroni per leggere il testo degli appunti. Come per l'evento copy, non dimentica di chiamare preventDefault().

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

Gestione di più tipi MIME

La maggior parte delle implementazioni inserisce più formati di dati negli appunti per un singolo taglio o copia l'operazione. I motivi sono due: in qualità di sviluppatore di app, devi conoscere le funzionalità dell'app in cui un utente vuole copiare testo o immagini, e molte applicazioni supportano l'operazione di incollare dati strutturati come testo normale. In genere si tratta di una situazione presentati agli utenti con una voce di menu Modifica con un nome come Incolla e stile di corrispondenza o Incolla senza formattazione.

L'esempio seguente mostra come eseguire questa operazione. Questo esempio utilizza fetch() per ottenere ma potrebbe anche provenire da un <canvas> o l'API File System Access.

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

Sicurezza e autorizzazioni

L'accesso agli appunti ha sempre rappresentato un problema di sicurezza per i browser. Senza le autorizzazioni appropriate, una pagina potrebbe copiare in silenzio tutti i tipi di contenuti dannosi negli appunti di un utente che, una volta incollati, produrrebbero risultati catastrofici. Immagina una pagina web che copia automaticamente rm -rf / o un immagine della bomba di decompressione negli appunti.

Fornire alle pagine web l'accesso in lettura senza limitazioni agli appunti è ancora più fastidioso. Gli utenti copiano regolarmente informazioni sensibili, come password dettagli personali negli appunti, che potrebbero essere letti da qualsiasi pagina senza in base alle conoscenze dell'utente.

Come avviene con molte nuove API, l'API Clipboard è supportata soltanto per le pagine pubblicate su HTTPS. Per prevenire comportamenti illeciti, l'accesso agli appunti è consentito solo quando una pagina viene la scheda attiva. Le pagine nelle schede attive possono scrivere negli appunti senza richiedere l'autorizzazione, ma per leggere dagli appunti è sempre necessario autorizzazione.

Le autorizzazioni per il copia e incolla sono state aggiunte al API Autorizzazioni. L'autorizzazione clipboard-write viene concessa automaticamente alle pagine quando queste la scheda attiva. È necessario richiedere l'autorizzazione clipboard-read, che puoi cercando di leggere i dati dagli appunti. Il codice seguente mostra quest'ultimo:

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

Puoi anche stabilire se è necessario un gesto dell'utente per richiamare la funzionalità di taglio o incollando usando l'opzione allowWithoutGesture. Il valore predefinito per questo valore varia a seconda del browser, quindi dovresti sempre includerlo.

Ecco dove la natura asincrona dell'API Clipboard diventa davvero utile: di leggere o scrivere dati degli appunti richiede automaticamente all'utente l'autorizzazione, se non è già stata concessa. Poiché l'API è basata sulle promesse, è completamente trasparente. Se un utente nega l'autorizzazione agli appunti, la promessa di rifiutare in modo che la pagina possa rispondere in modo appropriato.

Poiché i browser consentono l'accesso agli appunti solo quando una pagina è la scheda attiva, puoi notare che alcuni degli esempi riportati qui non vengono eseguiti se sono stati incollati direttamente console del browser, poiché gli strumenti per sviluppatori sono la scheda attiva. C'è un trucco: rimandare accesso agli appunti utilizzando setTimeout(), quindi fai clic rapidamente all'interno della pagina per prima che le funzioni vengano chiamate:

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

Integrazione dei criteri relativi alle autorizzazioni

Per utilizzare l'API in iframe, devi abilitarla con Criteri relativi alle autorizzazioni, che definisce un meccanismo che consente di abilitare selettivamente la disattivazione di varie funzionalità e API del browser. Concretamente, devi passare o entrambi di clipboard-read o clipboard-write, a seconda delle esigenze della tua app.

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

Rilevamento delle caratteristiche

Per utilizzare l'API Async Clipboard mentre supporti tutti i browser, testa per navigator.clipboard e torna ai metodi precedenti. Ad esempio, ecco come potresti implementare l'opzione Incolla per includere altri browser.

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

Non è tutto. Prima dell'API Async Clipboard, un mix di diverse implementazioni di copia e incolla nei vari browser web. Nella maggior parte dei browser, la funzione di copia e incolla del browser può essere attivata utilizzando document.execCommand('copy') e document.execCommand('paste'). Se il testo da copiare è una stringa non presente nel DOM, deve essere inserita nel DOM e selezione:

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

Puoi giocare con l'API Async Clipboard nelle demo qui sotto. Su Glitch you possono fare il remix della demo testuale o l'immagine demo per fare esperimenti con loro.

Il primo esempio mostra lo spostamento del testo dentro e fuori gli appunti.

Per provare l'API con le immagini, utilizza questa demo. Ricorda che sono supportati solo i file PNG e solo nelle alcuni browser.

Link correlati

• MDN
• Formati personalizzati per il web

Ringraziamenti

L'API Asynchronous Clipboard è stata implementata da Darwin Huang e Gary Kačmarčík. Darwin ha fornito anche la demo. Grazie a Kyarik e ancora Gary Kačmarčík per esaminare parti di questo articolo.

Immagine hero di Markus Winkler su Rimuovi schermo.