Controllo completo con l'API VirtualKeyboard

Thomas Steiner

Dispositivi come tablet o cellulari in genere dispongono di una tastiera virtuale per digitare il testo. A differenza di una tastiera fisica che è sempre presente e sempre uguale, viene visualizzata una tastiera virtuale e scompare, a seconda delle azioni dell'utente, a cui può anche adattarsi in modo dinamico, per Ad esempio, in base inputmode .

Questa flessibilità equivale al prezzo che il motore di layout del browser deve essere informato della tastiera virtuale e potrebbe essere necessario modificare il layout del documento per compensare. Ad esempio, un campo di immissione in cui l'utente sta per digitare potrebbe essere oscurato tastiera virtuale, quindi il browser deve scorrerla per visualizzarla.

Tradizionalmente, i browser hanno affrontato questa sfida da soli, ma per applicazioni più complesse potrebbero richiedere un maggiore controllo sul comportamento del browser. Esempi: i dispositivi mobili multischermo in cui l'approccio tradizionale comporterebbe uno "spreco" sullo schermo se la tastiera virtuale viene mostrata su un solo segmento dello schermo, ma dove l'area visibile disponibile si riduce in entrambi gli schermi ciononostante. L'immagine seguente mostra come utilizzare l'API VirtualKeyboard per ottimizzare il layout del documento in modo dinamico per compensare la presenza della tastiera virtuale.

In situazioni come questa entra in gioco l'API VirtualKeyboard. Si compone di tre parti:

• L'interfaccia VirtualKeyboard nell'oggetto navigator per l'accesso programmatico all'istanza da JavaScript.
• Un insieme di variabili di ambiente CSS che forniscono informazioni sulla tastiera virtuale aspetto.
• Un criterio della tastiera virtuale che determina se deve essere visualizzata la tastiera virtuale.

Stato attuale

L'API VirtualKeyboard è disponibile da 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 indicare al browser che ti stai occupando delle occlusioni della tastiera virtuale, devi occorre innanzitutto attivare il nuovo comportamento della tastiera virtuale impostando la proprietà booleana overlaysContent a true.

navigator.virtualKeyboard.overlaysContent = true;

Come mostrare e nascondere la tastiera virtuale

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

navigator.virtualKeyboard.show();

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

navigator.virtualKeyboard.hide();

Recupero della geometria corrente

Puoi ottenere la geometria corrente della tastiera virtuale osservando la proprietà boundingRect. Espone le dimensioni correnti della tastiera virtuale come DOMRect. Il riquadro corrisponde alle proprietà superiore, destra, inferiore e/o sinistra.

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 la proprietà target dell'evento contiene l'oggetto virtualKeyboard che (come discusso sopra) contiene la nuova geometria del riquadro della tastiera virtuale DOMRect

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

Variabili di ambiente CSS

L'API VirtualKeyboard espone un insieme di variabili di ambiente CSS che forniscono informazioni l'aspetto della tastiera virtuale. Il loro modello è simile a quello della proprietà CSS inset, cioè corrisponde alle 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

I riquadri della tastiera virtuale sono sei variabili di ambiente che definiscono un rettangolo in base al riquadri in basso e a sinistra dal bordo dell'area visibile. I riquadri di larghezza e altezza vengono calcolati degli altri inserti per l'ergonomia dello sviluppatore. Il valore predefinito di ogni riquadro di tastiera è 0px se non viene fornito un valore di riserva.

In genere, vengono utilizzate 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 essere visualizzata quando lo stato attivo è un elemento modificabile. Un esempio è un applicazione per fogli di lavoro in cui l'utente può toccare una cella per includere il suo valore in una formula di in 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 causa il elemento modificabile corrispondente per mostrare automaticamente la tastiera virtuale quando viene selezionata toccato: manual disaccoppia lo stato attivo e tocca l'elemento modificabile dalle modifiche lo stato corrente della tastiera.

<!-- 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 le codice sorgente per vedere come è implementato. Anche se gli eventi geometrychange possono essere osservati nell'incorporamento iframe, la tastiera virtuale effettiva richiede l'apertura della demo in una scheda del browser dedicata.

Link utili

• Specifiche
• Repository
• Voce ChromeStatus
• Bug di Chromium
• Revisione del tag W3C
• Richiesta di posizione standard Mozilla
• Richiesta di posizione standard WebKit

Ringraziamenti

L'API VirtualKeyboard è stata specificata da Anupam Snigdha di Microsoft, con il contributo di l'ex editor Grisha Lyukshin, anch'essa di Microsoft. Immagine hero di @freestocks su Rimuovi schermo.