Pełna kontrola dzięki interfejsowi VirtualKeyboard API

Thomas Steiner

Twitter GitHub Glitch Mastodon strona główna

Obsługa przeglądarek

• 94
• 94
• x
• x

Urządzenia takie jak tablety czy telefony komórkowe zazwyczaj mają wirtualną klawiaturę do pisania tekstu. W przeciwieństwie do klawiatury fizycznej, która jest zawsze dostępna i zawsze taka sama, klawiatura wirtualna wyświetla się i znika w zależności od działań użytkownika, do której może też dynamicznie się dostosowywać, np. na podstawie atrybutu inputmode.

Ta elastyczność wiąże się z ceną, ż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 do wprowadzania tekstu, w którym użytkownik ma zamiar wpisać, może być zasłonięte przez klawiaturę wirtualną, więc przeglądarka musi je przewinąć, żeby je zobaczyć.

Zazwyczaj przeglądarki radziły sobie z tym wyzwaniem samodzielnie, jednak bardziej złożone aplikacje mogą wymagać większej kontroli nad działaniem przeglądarki. Dotyczy to na przykład urządzeń mobilnych na wielu urządzeniach, na których tradycyjne podejście powodowałoby „zmarnowanie” miejsca na ekranie, gdyby klawiatura wirtualna była wyświetlana tylko na jednym segmencie ekranu, ale jednocześnie zmniejszony widoczny obszar na obu ekranach. Na ilustracji poniżej widać, jak za pomocą interfejsu VirtualKeyboard API można dynamicznie optymalizować układ dokumentu w celu skompensowania obecności klawiatury wirtualnej.

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

• Interfejs VirtualKeyboard w obiekcie navigator umożliwiający programowy dostęp do klawiatury wirtualnej z poziomu JavaScriptu.
• Zestaw zmiennych środowiskowych CSS, które dostarczają informacji o wyglądzie klawiatury wirtualnej.
• Zasada klawiatury wirtualnej, która określa, czy klawiatura wirtualna ma być widoczna.

Obecny stan,

Interfejs VirtualKeyboard API jest dostępny w Chromium 94 na komputerach i urządzeniach mobilnych.

Wykrywanie funkcji i obsługa przeglądarek

Aby sprawdzić, 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 VirtualKeyboard API dodaje do obiektu navigator nowy interfejs VirtualKeyboard.

Wyrażam zgodę na nowe działanie klawiatury wirtualnej

Aby poinformować przeglądarkę, że samodzielnie zajmujesz się blokowaniem klawiatury wirtualnej, musisz najpierw włączyć nowe działanie klawiatury wirtualnej, ustawiając właściwość wartości logicznej 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 ta funkcja działała, zaznaczony element musi być elementem sterującym formularza (takim jak element textarea) lub być hostem edycji (np. za pomocą atrybutu contenteditable). Metoda zawsze zwraca undefined, ale wyzwala zdarzenie geometrychange, jeśli klawiatura wirtualna nie została wcześniej wyświetlona.

navigator.virtualKeyboard.show();

Aby ukryć klawiaturę wirtualną, wywołaj metodę hide(). Metoda zawsze zwraca undefined, ale wyzwala zdarzenie geometrychange, jeśli klawiatura wirtualna została wcześniej wyświetlona.

navigator.virtualKeyboard.hide();

Pobieranie bieżącej geometrii

Aktualną geometrię klawiatury wirtualnej możesz sprawdzić we właściwości boundingRect. Bieżące wymiary klawiatury wirtualnej są widoczne jako obiekt DOMRect. Wstaw odpowiada właściwościom górnym, prawym, dolnym i/lub lewym.

const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);

Informacje o zmianach geometrycznych

Za każdym razem, gdy pojawia się lub znika klawiatura wirtualna, wysyłane jest zdarzenie geometrychange. Właściwość target zdarzenia zawiera obiekt virtualKeyboard (jak omówiliśmy powyżej), który ma nową geometrię wstawienia 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 środowiskowe CSS

Interfejs VirtualKeyboard 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ącej właściwościom górnym, prawym, dolnym lub lewym.

• keyboard-inset-top
• keyboard-inset-right
• keyboard-inset-bottom
• keyboard-inset-left
• keyboard-inset-width
• keyboard-inset-height

Wbudowane ustawienia klawiatury wirtualnej to 6 zmiennych środowiskowych, które definiują prostokąt obwodującymi prostokątami od góry, z prawej, do lewej i z lewej strony względem krawędzi widocznego obszaru. Wstawianie szerokości i wysokości jest obliczane na podstawie innych wektorów dla ergonomii programisty. Jeśli nie podasz wartości zastępczej, każda wbudowana klawiatura ma wartość 0px.

Zwykle używa się zmiennych środowiskowych jak w tym przykładzie:

.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);
}

Zasada dotycząca klawiatury wirtualnej

Czasami klawiatura wirtualna nie powinna wyświetlać się, gdy zaznaczony jest element z możliwością edytowania. Przykładem może być aplikacja do obsługi arkuszy kalkulacyjnych, w której użytkownik może kliknąć komórkę, by uwzględnić jej wartość w formule innej komórki. virtualkeyboardpolicy to atrybut, którego słowa kluczowe są ciągami auto i manual. Jeśli zostanie określony w elemencie, który jest hostem contenteditable, auto powoduje, że odpowiadający mu edytowalny element automatycznie wyświetla klawiaturę wirtualną po jej zaznaczeniu lub kliknięciu. manual rozłącza zaznaczenie i klikanie elementu możliwego do edytowania w przypadku 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>

Wersja demonstracyjna

Aby zobaczyć, jak działa interfejs VirtualKeyboard API, możesz obejrzeć prezentację Glitch. Zapoznaj się z kodem źródłowym, by zobaczyć, jak został zaimplementowany. Zdarzenia geometrychange można obserwować w elemencie iframe, ale rzeczywiste działanie klawiatury wirtualnej wymaga otwarcia wersji demonstracyjnej w osobnej karcie przeglądarki.

Przydatne linki

• Specyfikacja
• Repozytorium
• Wpis ChromeStatus
• Błąd w Chromium
• Ocena W3C TAG
• Żądanie pozycji standardów Mozilla
• Żądanie pozycji w standardzie WebKit

Podziękowania

Interfejs Virtualkey API został opracowany przez Anupama Snigdhę z firmy Microsoft. We współpracy z nią opublikowała go była redaktor Grishy Lyukshin, podobnie jak Microsoft. Baner powitalny od @freestocks w serwisie Unsplash.