Controllo completo con l'API VirtualKeyboard

Thomas Steiner

Supporto dei browser

• 94
• 94
• x
• x

Origine

I dispositivi come tablet o cellulari in genere hanno 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 scorrere 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, dove l'approccio tradizionale comporterebbe uno spazio sullo schermo "sprecato" se la tastiera virtuale viene visualizzata su un solo segmento dello schermo, ma dove l'area visibile disponibile viene 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.

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

• L'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 la tastiera virtuale in modo programmatico chiamando il relativo metodo show(). Affinché funzioni, l'elemento attivo deve essere un controllo di un modulo (ad esempio un elemento textarea) o un editor (ad esempio utilizzando l'attributo contenteditable). Il metodo restituisce sempre undefined, ma attiva un evento geometrychange se la tastiera virtuale non è stata 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 la tastiera virtuale è stata mostrata in precedenza.

navigator.virtualKeyboard.hide();

Ottenere la geometria corrente

Puoi ottenere la geometria attuale della tastiera virtuale consultando 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);

Ricevere informazioni sulle modifiche alla geometria

Ogni volta che la tastiera virtuale viene visualizzata o nascosta, 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 modellate in modo simile alla proprietà CSS inset, ovvero corrispondono 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 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 corrente della tastiera virtuale dall'assegnazione del focus e dal tocco dell'elemento modificabile.

<!-- 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 vedere 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.

Link utili

• Specifiche
• Repository
• Voce ChromeStatus
• Bug di Chromium
• Revisione del TAG del W3C
• Richiesta di posizione relativa agli standard di Mozilla
• Richiesta di posizione per gli standard WebKit

Ringraziamenti

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