Deze pagina is vertaald door de Cloud Translation API.

Volledige controle met de VirtualKeyboard API

Thomas Steiner

Browserondersteuning

Apparaten zoals tablets of mobiele telefoons hebben doorgaans een virtueel toetsenbord om tekst te typen. In tegenstelling tot een fysiek toetsenbord dat altijd aanwezig en altijd hetzelfde is, verschijnt en verdwijnt een virtueel toetsenbord, afhankelijk van de acties van de gebruiker, waaraan het zich ook dynamisch kan aanpassen, bijvoorbeeld op basis van het inputmode attribuut.

Deze flexibiliteit brengt de prijs met zich mee dat de lay-outengine van de browser op de hoogte moet worden gesteld van de aanwezigheid van het virtuele toetsenbord en mogelijk de lay-out van het document moet aanpassen om dit te compenseren. Een invoerveld waarin de gebruiker op het punt staat te typen, kan bijvoorbeeld worden verborgen door het virtuele toetsenbord, zodat de browser het in beeld moet scrollen.

Traditioneel hebben browsers deze uitdaging zelfstandig aangepakt, maar complexere toepassingen vereisen mogelijk meer controle over het gedrag van de browser. Voorbeelden hiervan zijn mobiele apparaten met meerdere schermen waarbij de traditionele aanpak zou resulteren in "verspilling" van schermruimte als het virtuele toetsenbord op slechts één schermsegment wordt weergegeven, maar waarbij de beschikbare viewport toch op beide schermen wordt verkleind. De onderstaande afbeelding laat zien hoe de VirtualKeyboard API kan worden gebruikt om de lay-out van het document dynamisch te optimaliseren om de aanwezigheid van het virtuele toetsenbord te compenseren.

De traditionele aanpak resulteert in

In situaties als deze komt de VirtualKeyboard API van pas. Deze bestaat uit drie delen:

De VirtualKeyboard interface op het navigator voor programmatische toegang tot het virtuele toetsenbord vanuit JavaScript.
Een set CSS-omgevingsvariabelen die informatie geven over het uiterlijk van het virtuele toetsenbord.
Een virtueel toetsenbordbeleid dat bepaalt of het virtuele toetsenbord moet worden weergegeven.

Huidige status

De VirtualKeyboard API is beschikbaar vanaf Chromium 94 op desktop en mobiel.

Functiedetectie en browserondersteuning

Gebruik het volgende fragment om te detecteren of de VirtualKeyboard API wordt ondersteund in de huidige browser:

if ('virtualKeyboard' in navigator) {
  // The VirtualKeyboard API is supported!
}

Met behulp van de VirtualKeyboard-API

De VirtualKeyboard API voegt een nieuwe interface VirtualKeyboard toe aan het navigator .

Aanmelden voor het nieuwe virtuele toetsenbordgedrag

Om de browser te laten weten dat u zelf voor virtuele toetsenbordocclusies zorgt, moet u zich eerst aanmelden voor het nieuwe virtuele toetsenbordgedrag door de booleaanse eigenschap overlaysContent in te stellen op true .

navigator.virtualKeyboard.overlaysContent = true;

Het virtuele toetsenbord tonen en verbergen

U kunt het virtuele toetsenbord programmatisch weergeven door de show() -methode aan te roepen. Om dit te laten werken, moet het gefocuste element een formulierbesturingselement zijn (zoals een textarea element) of een bewerkingshost zijn (bijvoorbeeld door het contenteditable attribuut te gebruiken). De methode retourneert altijd undefined , maar activeert een geometrychange als het virtuele toetsenbord voorheen niet werd weergegeven.

navigator.virtualKeyboard.show();

Om het virtuele toetsenbord te verbergen, roept u de methode hide() aan. De methode retourneert altijd undefined , maar activeert een geometrychange als het virtuele toetsenbord eerder werd getoond.

navigator.virtualKeyboard.hide();

De huidige geometrie ophalen

U kunt de huidige geometrie van het virtuele toetsenbord verkrijgen door naar de eigenschap boundingRect te kijken. Het geeft de huidige afmetingen van het virtuele toetsenbord weer als een DOMRect object. De inzet komt overeen met de eigenschappen bovenaan, rechts, onderaan en/of links.

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

Op de hoogte blijven van veranderingen in de geometrie

Telkens wanneer het virtuele toetsenbord verschijnt of verdwijnt, wordt de geometrychange verzonden. De target eigenschap van de gebeurtenis bevat het virtualKeyboard object dat (zoals hierboven besproken) de nieuwe geometrie van de virtuele toetsenbordinzet bevat als een DOMRect .

navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
  const { x, y, width, height } = event.target.boundingRect;
  console.log('Virtual keyboard geometry changed:', x, y, width, height);
});

De CSS-omgevingsvariabelen

De VirtualKeyboard API stelt een reeks CSS-omgevingsvariabelen beschikbaar die informatie geven over het uiterlijk van het virtuele toetsenbord. Ze worden op dezelfde manier gemodelleerd als de inset CSS-eigenschap, dat wil zeggen dat ze overeenkomen met de eigenschappen bovenaan, rechts, onderaan en/of links.

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

De virtuele toetsenbordinzetstukken zijn zes omgevingsvariabelen die een rechthoek definiëren aan de hand van de inzetstukken bovenaan, rechts, onderaan en links vanaf de rand van de viewport. De breedte- en hoogte-inzetstukken worden berekend op basis van de andere inzetstukken voor de ergonomie van de ontwikkelaar. De standaardwaarde van elke toetsenbordinzet is 0px als er geen fallback-waarde is opgegeven.

Normaal gesproken gebruikt u de omgevingsvariabelen zoals in het onderstaande voorbeeld:

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

Het virtuele toetsenbordbeleid

Soms zou het virtuele toetsenbord niet moeten verschijnen wanneer een bewerkbaar element is gefocust. Een voorbeeld is een spreadsheettoepassing waarbij de gebruiker op een cel kan tikken om de waarde ervan op te nemen in een formule van een andere cel. Het virtualkeyboardpolicy is een attribuut waarvan de trefwoorden de strings auto en manual zijn. Wanneer gespecificeerd op een element dat een contenteditable host is, zorgt auto ervoor dat het corresponderende bewerkbare element automatisch het virtuele toetsenbord toont wanneer erop wordt gefocust of erop wordt getikt, en manual wordt de focus en het tikken op het bewerkbare element losgekoppeld van veranderingen in de huidige status van het virtuele toetsenbord.

<!-- 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>

Demo

Je kunt de VirtualKeyboard API in actie zien in een demo op Glitch. Zorg ervoor dat u de broncode verkent om te zien hoe deze is geïmplementeerd. Hoewel geometrychange kunnen worden waargenomen in de iframe-insluiting, vereist het daadwerkelijke gedrag van het virtuele toetsenbord het openen van de demo op een eigen browsertabblad .

Nuttige links

Dankbetuigingen

De VirtualKeyboard API is gespecificeerd door Anupam Snigdha van Microsoft, met bijdragen van voormalig redacteur Grisha Lyukshin, eveneens van Microsoft.