Urządzenia takie jak tablety czy telefony komórkowe zwykle mają wirtualną klawiaturę do pisania.
W przeciwieństwie do klawiatury fizycznej, która jest zawsze obecna i zawsze taka sama, klawiatura wirtualna pojawia się i znika w zależności od działań użytkownika, do których może się też dynamicznie dostosowywać, na przykład na podstawie atrybutu inputmode
.
Ta elastyczność wynika z tego, że mechanizm układu przeglądarki musi być informowany o obecności klawiatury wirtualnej, co może wymagać dostosowania układu dokumentu. Na przykład pole tekstowe, w które użytkownik ma zamiar wpisać tekst, może być zasłonięte przez klawiaturę wirtualną, więc przeglądarka musi przewinąć je w celu wyświetlenia.
Do tej pory przeglądarki radziły sobie z tym problemem samodzielnie, ale bardziej złożone aplikacje mogą wymagać większej kontroli nad zachowaniem przeglądarki. Przykładem są urządzenia mobilne z wieloma ekranami, w przypadku których tradycyjne podejście spowoduje „zmarnowanie” powierzchni ekranu, jeśli klawiatura wirtualna będzie wyświetlana tylko na jednym segmencie ekranu, ale dostępne pole widoku będzie zmniejszone na obu ekranach. Na ilustracji poniżej widać, jak przy użyciu interfejsu VirtualKlawiatura API można dynamicznie optymalizować układ dokumentu pod kątem obecności klawiatury wirtualnej.
W takich sytuacjach przydaje się interfejs VirtualKeyboard API. Składa się z 3 części:
- Interfejs
VirtualKeyboard
obiektunavigator
umożliwiający zautomatyzowany dostęp do wirtualnej klawiatury z poziomu JavaScriptu. - Zestaw zmiennych środowiskowych CSS, które zawierają informacje o wyglądzie klawiatury wirtualnej.
- Zasada dotycząca klawiatury wirtualnej, która określa, czy klawiatura wirtualna powinna być wyświetlana.
Obecny stan,
Interfejs API klawiatury wirtualnej jest dostępny w wersji Chromium 94 na komputerach i urządzeniach mobilnych.
Wykrywanie funkcji i obsługa przeglądarek
Aby wykryć, czy interfejs VirtualKeyboard API jest obsługiwany w bieżącej przeglądarce, użyj tego fragmentu kodu:
if ('virtualKeyboard' in navigator) {
// The VirtualKeyboard API is supported!
}
Korzystanie z interfejsu VirtualKeyboard API
Interfejs API klawiatury wirtualnej dodaje do obiektu navigator
nowy interfejs VirtualKeyboard
.
Włączanie nowego działania klawiatury wirtualnej
Aby poinformować przeglądarkę, że samodzielnie radzisz sobie z zasłonięciem klawiatury wirtualnej, musisz najpierw wyrazić zgodę na nowy sposób działania klawiatury wirtualnej, ustawiając właściwość logiczną overlaysContent
na true
.
navigator.virtualKeyboard.overlaysContent = true;
Wyświetlanie i ukrywanie klawiatury wirtualnej
Możesz wywołać klawiaturę wirtualną za pomocą kodu, wywołując metodę show()
. Aby to działało, zaznaczony element musi być kontrolką formularza (np. element textarea
) lub być hostem edycji (np. za pomocą atrybutu contenteditable
). Metoda zawsze zwraca wartość undefined
, ale powoduje wywołanie zdarzenia geometrychange
, jeśli klawiatura wirtualna nie była wcześniej wyświetlana.
navigator.virtualKeyboard.show();
Aby ukryć klawiaturę wirtualną, wywołaj metodę hide()
. Metoda zawsze zwraca wartość undefined
, ale powoduje też zdarzenie geometrychange
, jeśli wcześniej była wyświetlana klawiatura wirtualna.
navigator.virtualKeyboard.hide();
Pobieram bieżącą geometrię
Bieżącą geometrię klawiatury wirtualnej można sprawdzić w właściwości boundingRect
.
Wyświetla bieżące wymiary klawiatury wirtualnej jako obiekt DOMRect
.
Wcięcie odpowiada właściwościom: górna, prawa, dół i/lub lewa strona.
const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);
informowanie o zmianach geometrii;
Gdy klawiatura wirtualna pojawia się lub znika, wysyłane jest zdarzenie geometrychange
. Właściwość target
zdarzenia zawiera obiekt virtualKeyboard
, który (jak wspomniano powyżej) zawiera nową geometrię wstawki klawiatury wirtualnej jako DOMRect
.
navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
const { x, y, width, height } = event.target.boundingRect;
console.log('Virtual keyboard geometry changed:', x, y, width, height);
});
Zmienne środowiska CSS
Interfejs VirtualKlawiatura API udostępnia zestaw zmiennych środowiskowych CSS, które dostarczają informacji o wyglądzie klawiatury wirtualnej.
Są one modelowane podobnie do właściwości CSS inset
, czyli odpowiadają właściwościom top, right, bottom i left.
keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height
Wstawki klawiatury wirtualnej to 6 zmiennych środowiskowych, które definiują prostokąt w oparciu o wcięcia u góry, z prawej strony i u dołu od krawędzi widocznego obszaru. W celu ułatwienia pracy deweloperom w przypadku innych wstawek są one obliczane na podstawie wstawek szerokości i wysokości. Jeśli nie podasz wartości zastępczej, domyślna wartość każdego wstawionego elementu klawiatury to
0px
.
Zwykle używa się zmiennych środowiskowych w taki sposób:
.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);
}
Zasady dotyczące klawiatury wirtualnej
Czasami klawiatura wirtualna nie powinna się pojawiać, gdy element do edycji jest aktywny. Przykładem może być aplikacja arkusza kalkulacyjnego, w której użytkownik może kliknąć komórkę, aby jej wartość została uwzględniona w formule innej komórki. virtualkeyboardpolicy
to atrybut, którego słowa kluczowe to ciągi tekstowe auto
i manual
. Gdy jest on określony w elemencie, który jest elementem hosta contenteditable
, auto
powoduje, że odpowiedni element z możliwością edycji automatycznie wyświetla klawiaturę wirtualną, gdy zostanie on zaznaczony lub dotknięty, a auto
odłącza zaznaczanie i klikanie elementu z możliwością edycji od zmian w bieżącym stanie klawiatury wirtualnej.
<!-- 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>
Prezentacja
Interfejs API VirtualKeyboard możesz zobaczyć w akcji w demo na Glitch. Zapoznaj się z kodem źródłowym, aby zobaczyć, jak jest on implementowany.
Zdarzenia geometrychange
można obserwować w umieszczonym elemencie iframe, ale rzeczywiste działanie klawiatury wirtualnej wymaga otwarcia wersji demonstracyjnej w osobnej karcie przeglądarki.
Przydatne linki
- Specyfikacja
- Repozytorium
- Wpis w ChromeStatus
- Błąd w Chromium
- sprawdzenie tagów W3C,
- Prośba o pozycję w standardach Mozilli
- Prośba o pozycję w standardach WebKit
Podziękowania
Interfejs API VirtualKeyboard został określony przez Anupam Snigdha z Microsoftu przy udziale byłego redaktora Grisha Lyukshina, również z Microsoftu.