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.
In situazioni come questa è utile l'API VirtualKeyboard. È composto da tre parti:
- Interfaccia
VirtualKeyboard
nell'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 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.
Link utili
- Specifiche
- Repository
- Voce ChromeStatus
- Bug di Chromium
- Revisione del TAG del W3C
- Richiesta di posizione 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, anch'esso di Microsoft.