Deze pagina is vertaald door de Cloud Translation API.

Volledige controle met de VirtualKeyboard API

Thomas Steiner

Browser Support

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 hetzelfde is, verschijnt en verdwijnt een virtueel toetsenbord afhankelijk van de handelingen van de gebruiker. Het kan zich hier ook dynamisch aan aanpassen, bijvoorbeeld op basis van het inputmode -attribuut.

Deze flexibiliteit heeft wel als nadeel dat de lay-out engine van de browser op de hoogte moet zijn van de aanwezigheid van het virtuele toetsenbord en mogelijk de lay-out van het document moet aanpassen om dit te compenseren. Zo kan een invoerveld waarin de gebruiker op het punt staat te typen, worden geblokkeerd door het virtuele toetsenbord, waardoor de browser het moet scrollen om het zichtbaar te maken.

Traditioneel hebben browsers deze uitdaging zelfstandig aangepakt, maar complexere applicaties 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 "verspilde" schermruimte als het virtuele toetsenbord op slechts één schermsegment wordt weergegeven, terwijl de beschikbare viewport desondanks 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 dit soort situaties 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 verschaffen 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 via Chromium 94 op desktop en mobiel.

Functiedetectie en browserondersteuning

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

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

De VirtualKeyboard API gebruiken

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 de virtuele toetsenbordafdekkingen verzorgt, moet u zich eerst aanmelden voor het nieuwe gedrag van het virtuele toetsenbord door de Booleaanse eigenschap overlaysContent in te stellen op true .

navigator.virtualKeyboard.overlaysContent = true;

Het virtuele toetsenbord weergeven en verbergen

U kunt het virtuele toetsenbord programmatisch weergeven door de show() methode aan te roepen. Hiervoor moet het gefocuste element een formulierbesturingselement zijn (zoals een textarea ) of een bewerkingshost (bijvoorbeeld met behulp van het attribuut contenteditable ). De methode retourneert altijd undefined , maar activeert een geometrychange -gebeurtenis als het virtuele toetsenbord eerder niet werd weergegeven.

navigator.virtualKeyboard.show();

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

navigator.virtualKeyboard.hide();

De huidige geometrie verkrijgen

U kunt de huidige geometrie van het virtuele toetsenbord bepalen door naar de eigenschap boundingRect te kijken. Deze geeft de huidige afmetingen van het virtuele toetsenbord weer als een DOMRect object. De inset komt overeen met de eigenschappen top, right, bottom en/of left.

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

Op de hoogte zijn van veranderingen in de geometrie

Wanneer het virtuele toetsenbord verschijnt of verdwijnt, wordt de geometrychange verzonden. De eigenschap target van de gebeurtenis bevat het object virtualKeyboard , dat (zoals hierboven besproken) de nieuwe geometrie van de virtuele toetsenbordinset 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 set CSS-omgevingsvariabelen beschikbaar die informatie verschaffen over het uiterlijk van het virtuele toetsenbord. Ze zijn gemodelleerd op een vergelijkbare manier als de CSS-eigenschap ' inset , dat wil zeggen dat ze overeenkomen met de eigenschappen 'top', 'right', 'bottom' en 'left'.

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 bovenste, rechter, onderste en linker inzetstukken vanaf de rand van de viewport. De breedte- en hoogte-inzetstukken worden berekend op basis van de andere inzetstukken voor ontwikkelaarsergonomie. De standaardwaarde van elk toetsenbordinzetstuk 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 mag het virtuele toetsenbord niet verschijnen wanneer een bewerkbaar element de focus heeft. Een voorbeeld hiervan is een spreadsheettoepassing waarbij de gebruiker op een cel kan tikken om de waarde ervan in een formule van een andere cel op te nemen. Het virtualkeyboardpolicy is een kenmerk waarvan de sleutelwoorden de strings auto en manual zijn. Wanneer dit wordt gespecificeerd voor een element dat een contenteditable host is, zorgt auto ervoor dat het bijbehorende bewerkbare element automatisch het virtuele toetsenbord weergeeft wanneer het de focus heeft of erop wordt getikt. manual koppelt de focus en het tikken op het bewerkbare element los van wijzigingen 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>

Demonstratie

Je kunt de VirtualKeyboard API in actie zien in een demo op Glitch. Bekijk de broncode om te zien hoe deze is geïmplementeerd. Hoewel geometrychange te zien zijn in de iframe-embed, vereist het daadwerkelijke gedrag van het virtuele toetsenbord het openen van de demo in een eigen browsertabblad .

Nuttige links

Dankbetuigingen

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