Pełna kontrola dzięki interfejsowi VirtualKeyboard API

Thomas Steiner

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ść ma swoją cenę: mechanizm układu przeglądarki musi być informowany o obecności klawiatury wirtualnej i w razie potrzeby dostosowywać układ dokumentu. Na przykład pole wprowadzania, w które użytkownik ma zamiar wpisać tekst, może być zasłonięte przez klawiaturę wirtualną, więc przeglądarka musi przewinąć pole, aby je wyświetlić.

Do tej pory przeglądarki radziły sobie z tym problemem samodzielnie, ale bardziej złożone aplikacje mogą wymagać większej kontroli nad działaniem 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 na jednym z segmentów ekranu, ale dostępne pole widzenia będzie zmniejszone na obu ekranach. Ilustracja poniżej pokazuje, jak można użyć interfejsu VirtualKeyboard API do dynamicznego optymalizowania układu dokumentu, aby uwzględnić obecność wirtualnej klawiatury.

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 zajmujesz się zasłonięciem klawiatury wirtualnej, musisz najpierw włączyć nowe działanie 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, element skupienia musi być elementem formularza (takim jak element textarea) lub hostem edycji (np. za pomocą atrybutu contenteditable). Metoda zawsze zwraca 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 została wyświetlona klawiatura wirtualna.

navigator.virtualKeyboard.hide();

Pobieranie bieżącej geometrii

Bieżącą geometrię klawiatury wirtualnej można sprawdzić w właściwości boundingRect. Wyświetla bieżące wymiary klawiatury wirtualnej jako obiekt DOMRect. Wstawka odpowiada właściwościom góra, prawo, dół lub lewo.

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 API klawiatury wirtualnej udostępnia zestaw zmiennych środowiskowych CSS, które zawierają informacje 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 przez wstawki górne, prawe, dolne i lewe 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 pojawiać się, 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.manual

<!-- 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. Chociaż zdarzenia geometrychange można obserwować w ramce iframe, aby zobaczyć działanie klawiatury wirtualnej, należy otworzyć wersję demonstracyjną w nowej karcie przeglądarki.

Przydatne linki

• Specyfikacja
• Repozytorium
• Wpis w ChromeStatus
• Błąd w Chromium
• Sprawdzanie 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 edytora Grisha Lyukshina, również z Microsoftu.