Controllo completo con l'API VirtualKeyboard

Supporto dei browser

  • Chrome: 94.
  • Edge: 94.
  • Firefox: non supportato.
  • Safari: non supportato.

Origine

Dispositivi come tablet o cellulari in genere dispongono di una tastiera virtuale per digitare il testo. A differenza di una tastiera fisica, sempre presente e sempre uguale, una tastiera virtuale appare e scompare in base alle azioni dell'utente, a cui può anche adattarsi dinamicamente, ad esempio in base all'attributo inputmode.

Questa flessibilità ha il prezzo che l'engine di layout del browser deve essere informato della presenza della tastiera virtuale e potenzialmente deve modificare il layout del documento per compensare. Ad esempio, un campo di immissione in cui l'utente sta per digitare potrebbe essere oscurato dalla tastiera virtuale, quindi il browser deve scorrerlo per visualizzarlo.

Tradizionalmente, i browser hanno gestito 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 "spreco" dello spazio sullo schermo se la tastiera virtuale viene visualizzata su un solo segmento dello schermo, ma in cui l'area visibile disponibile viene comunque ridotta su entrambi gli schermi. L'immagine seguente mostra come l'API VirtualKeyboard potrebbe essere utilizzata per ottimizzare dinamicamente il layout del documento in modo da compensare la presenza della tastiera virtuale.

L'approccio tradizionale comporta

In situazioni come questa è utile l'API VirtualKeyboard. È composto da tre parti:

  • Interfaccia VirtualKeyboard nell'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 da Chromium 94 su computer e dispositivi mobili.

Rilevamento delle funzionalità e supporto dei 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 occupi personalmente delle occlusioni della tastiera virtuale, devi prima attivare il nuovo comportamento della tastiera virtuale impostando la proprietà booleana overlaysContent su true.

navigator.virtualKeyboard.overlaysContent = true;

Visualizzazione e occultamento della tastiera virtuale

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

navigator.virtualKeyboard.show();

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

navigator.virtualKeyboard.hide();

Recupero della geometria corrente

Puoi ottenere la geometria attuale della tastiera virtuale esaminando la proprietà boundingRect. Espone le dimensioni correnti della tastiera virtuale come oggetto DOMRect. L'inserimento corrisponde alle proprietà top, right, bottom e/o left.

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

Essere informati 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 dell'inserto della tastiera virtuale 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. Sono modellati in modo simile alla proprietà CSS inset, ovvero in corrispondenza delle proprietà superiore, destra, inferiore e/o sinistra.

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

Gli inserimenti della tastiera virtuale sono sei variabili di ambiente che definiscono un rettangolo in base agli inserimenti superiore, destro, inferiore e sinistro dal bordo dell'area visibile. Gli inserimenti di larghezza e altezza vengono calcolati dall'altro per l'ergonomia dello sviluppatore. Il valore predefinito di ogni incavo della tastiera è 0px se non viene fornito un valore alternativo.

In genere, le variabili di ambiente vengono utilizzate 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 essere visualizzata quando è attivo un elemento modificabile. Un esempio è un'applicazione di foglio di lavoro in cui l'utente può toccare una cella per includerne il valore in una formula di un'altra cella. virtualkeyboardpolicy è un attributo le cui parole chiave sono le stringhe auto e manual. Se specificato in un elemento che è un host contenteditable, auto fa in modo che l'elemento modificabile corrispondente mostri automaticamente la tastiera virtuale quando viene selezionato o toccato e manual scollega lo stato attivo e il tocco dell'elemento modificabile dalle modifiche allo 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 esaminare il codice sorgente per scoprire come viene implementato. Sebbene gli eventi geometrychange possano essere osservati nell'iframe incorporato, il comportamento effettivo della tastiera virtuale richiede l'apertura della demo nella relativa scheda del browser.

Ringraziamenti

L'API VirtualKeyboard è stata specificata da Anupam Snigdha di Microsoft, con il contributo dell'ex editor Grisha Lyukshin, anch'esso di Microsoft.