Supporto dei browser
- 94
- 94
- x
- x
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.
Situazioni come questa è la fase in cui entra in gioco l'API VirtualKeyboard. È costituito da tre parti:
- Interfaccia
VirtualKeyboard
sull'oggettonavigator
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
- Specifiche
- Repository
- Voce ChromeStatus
- Bug di Chromium
- Revisione del TAG W3C
- Richiesta di posizione sugli standard 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, analogamente a quello di Microsoft. Immagine hero di @freestocks su Unsplash.