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 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. Ilustracja poniżej pokazuje, jak można użyć interfejsu VirtualKeyboard API do dynamicznego optymalizowania układu dokumentu, aby uwzględnić obecność klawiatury wirtualnej.

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;

Pokazywanie i ukrywanie klawiatury wirtualnej

Możesz programowo wyświetlić klawiaturę wirtualną, wywołując jej metodę show(). Aby to działało, element skupiony musi być elementem formularza (takim jak element textarea) lub hostem edycji (np. za pomocą atrybutu contenteditable). Ta metoda zawsze zwraca wartość undefined, ale wywołuje zdarzenie geometrychange, jeśli klawiatura wirtualna nie była wcześniej widoczna.

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();

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 omówiono powyżej) zawiera nową geometrię wstawki klawiatury wirtualnej w postaci 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 środowiskowe 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 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 podano wartości zastępczej, domyślną wartością każdego wcięcia klawiatury jest 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 znaków 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 dowiedzieć się, jak został on zaimplementowany. 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 Chromium
• sprawdzenie tagów W3C,
• Żądanie pozycji w standardzie Mozilla
• Żądanie pozycji w standardzie 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.