Pełna kontrola dzięki interfejsowi VirtualKeyboard API

Obsługa przeglądarek

  • Chrome: 94.
  • Edge: 94.
  • Firefox: funkcja nieobsługiwana.
  • Safari: nieobsługiwane.

Źródło

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.

Tradycyjne podejście powoduje, że

W takich sytuacjach przydaje się interfejs VirtualKeyboard API. Składa się z 3 części:

  • Interfejs VirtualKeyboard obiektu navigator 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 automanual. 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.

Podziękowania

Interfejs API VirtualKeyboard został określony przez Anupam Snigdha z Microsoftu przy udziale byłego redaktora Grisha Lyukshina, również z Microsoftu.