Questa pagina è stata tradotta dall'API Cloud Translation.

Controllo completo con l'API VirtualKeyboard

Thomas Steiner

Twitter GitHub Glitch Mastodon Homepage

Supporto dei browser

I dispositivi come i tablet o i cellulari in genere dispongono di una tastiera virtuale per la digitazione di testo. A differenza di una tastiera fisica sempre presente e sempre uguale, appare e scompare una tastiera virtuale, a seconda delle azioni dell'utente e alle quali può adattarsi dinamicamente, ad esempio in base all'attributo inputmode.

Questa flessibilità ha il costo per cui il motore di layout del browser deve essere informato della presenza della tastiera virtuale e potrebbe dover regolare il layout del documento per compensare. Ad esempio, un campo di immissione in cui l'utente sta per digitare potrebbe essere nascosto dalla tastiera virtuale, in modo che il browser debba scorrerlo per renderlo visibile.

Tradizionalmente, i browser hanno affrontato questa sfida autonomamente, ma le applicazioni più complesse potrebbero richiedere un maggiore controllo sul comportamento del browser. Alcuni esempi sono i dispositivi mobili multischermo in cui l'approccio tradizionale comporterebbe uno spazio "sprecato" sullo schermo se la tastiera virtuale viene visualizzata su un solo segmento di schermo, ma in cui l'area visibile disponibile viene ridotta su entrambi gli schermi. L'immagine seguente mostra come utilizzare l'API VirtualKeyboard per ottimizzare il layout del documento in modo dinamico e compensare la presenza della tastiera virtuale.

L'approccio tradizionale si traduce

Situazioni come questa è la fase in cui entra in gioco l'API VirtualKeyboard. È costituito da tre parti:

Interfaccia VirtualKeyboard sull'oggetto navigator per l'accesso programmatico alla tastiera virtuale da JavaScript.
Un insieme di variabili di ambiente CSS che forniscono informazioni sull'aspetto della tastiera virtuale.
Un criterio della tastiera virtuale che determina se la tastiera virtuale deve essere visualizzata.

Stato attuale

L'API VirtualKeyboard è disponibile in Chromium 94 su computer e dispositivi mobili.

Rilevamento delle funzionalità e supporto del browser

Per rilevare se l'API VirtualKeyboard è supportata nel browser corrente, utilizza il seguente snippet:

if ('virtualKeyboard' in navigator) {
  // The VirtualKeyboard API is supported!
}

Utilizzo dell'API VirtualKeyboard

L'API VirtualKeyboard aggiunge una nuova interfaccia VirtualKeyboard all'oggetto navigator.

Attivazione del nuovo comportamento della tastiera virtuale

Per comunicare al browser che ti stai occupando delle coperture della tastiera virtuale, devi prima attivare il nuovo comportamento della tastiera virtuale impostando la proprietà booleana overlaysContent su true.

navigator.virtualKeyboard.overlaysContent = true;

Come visualizzare e nascondere la tastiera virtuale

Puoi mostrare la tastiera virtuale in modo programmatico chiamando il relativo metodo show(). Affinché questo comando funzioni, l'elemento attivo deve essere un controllo modulo (ad esempio un elemento textarea) o un host di modifica (ad esempio, utilizzando l'attributo contenteditable). Il metodo restituisce sempre undefined, ma attiva un evento geometrychange se la tastiera virtuale non era mostrata in precedenza.

navigator.virtualKeyboard.show();

Per nascondere la tastiera virtuale, chiama il metodo hide(). Il metodo restituisce sempre undefined, ma attiva un evento geometrychange se in precedenza la tastiera virtuale era stata mostrata.

navigator.virtualKeyboard.hide();

Recupero della geometria attuale

Puoi ottenere la geometria attuale della tastiera virtuale osservando la proprietà boundingRect. Espone le dimensioni attuali della tastiera virtuale come oggetto DOMRect. Il riquadro corrisponde alle proprietà in alto, a destra, in basso e/o a sinistra.

const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);

Ricevere informazioni sulle modifiche alla geometria

Ogni volta che la tastiera virtuale appare o scompare, viene inviato l'evento geometrychange. La proprietà target dell'evento contiene l'oggetto virtualKeyboard che (come discusso sopra) contiene la nuova geometria del riquadro della tastiera virtuale impostata come DOMRect.

navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
  const { x, y, width, height } = event.target.boundingRect;
  console.log('Virtual keyboard geometry changed:', x, y, width, height);
});

Le variabili di ambiente CSS

L'API VirtualKeyboard espone un insieme di variabili di ambiente CSS che forniscono informazioni sull'aspetto della tastiera virtuale. Il modello è simile alla proprietà CSS inset, ovvero corrisponde alle proprietà top, right, bottom e/o left.

keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height

Gli insiemi della tastiera virtuale sono sei variabili di ambiente che definiscono un rettangolo dai riquadri superiore, destro, inferiore e sinistro dal bordo dell'area visibile. I riquadri di larghezza e altezza sono calcolati dagli altri riquadri per garantire l'ergonomia degli sviluppatori. Se non viene fornito un valore di riserva, il valore predefinito di ogni riquadro della tastiera è 0px.

In genere, utilizzi le variabili di ambiente come nell'esempio seguente:

.some-class {
  /**
   * Use a margin that corresponds to the virtual keyboard's height
   * if the virtual keyboard is shown, else use the fallback value of `50px`.
   */
  margin-block-end: env(keyboard-inset-height, 50px);
}

.some-other-class {
  /**
   * Use a margin that corresponds to the virtual keyboard's height
   * if the virtual keyboard is shown, else use the default fallback value of `0px`.
   */
  margin-block-end: env(keyboard-inset-height);
}

Il criterio della tastiera virtuale

A volte la tastiera virtuale non dovrebbe apparire quando è attivo un elemento modificabile. Un esempio è un'applicazione per fogli di lavoro in cui l'utente può toccare una cella per includere il relativo valore in una formula di un'altra cella. virtualkeyboardpolicy è un attributo le cui parole chiave sono le stringhe auto e manual. Se specificato su un elemento che è un host contenteditable, auto fa sì che l'elemento modificabile corrispondente mostri automaticamente la tastiera virtuale quando viene attivato o toccato. manual disaccoppia lo stato attivo e tocca l'elemento modificabile dalle modifiche nello stato corrente della tastiera virtuale.

<!-- Do nothing on regular focus, but show the virtual keyboard on double-click. -->
<div
  contenteditable
  virtualkeyboardpolicy="manual"
  inputmode="text"
  ondblclick="navigator.virtualKeyboard.show();"
>
  Double-click to edit.
</div>

Demo

Puoi vedere l'API VirtualKeyboard in azione in una demo su Glitch. Assicurati di esplorare il codice sorgente per vedere come viene implementato. Sebbene gli eventi geometrychange possano essere osservati nell'incorporamento dell'iframe, il comportamento effettivo della tastiera virtuale richiede l'apertura della demo nella propria scheda del browser.

Link utili

Ringraziamenti

L'API VirtualKeyboard è stata specificata da Anupam Snigdha di Microsoft, con il contributo dell'ex editor Grisha Lyukshin, analogamente a quello di Microsoft. Immagine hero di @freestocks su Unsplash.