VirtualKeyboard API ile tam kontrol

Tarayıcı desteği

  • Chrome: 94.
  • Kenar: 94.
  • Firefox: Desteklenmez.
  • Safari: desteklenmez.

Kaynak

Tablet veya cep telefonu gibi cihazlarda genellikle metin yazmak için sanal klavye bulunur. Her zaman mevcut olan ve her zaman aynı olan fiziksel bir klavyenin aksine, sanal klavye kullanıcının işlemlerine bağlı olarak görünür ve kaybolur. Ayrıca, dinamik olarak da uyarlanabilir (ör. inputmode özelliğine göre).

Bu esneklik, tarayıcının düzen motorunun sanal klavyenin varlığı hakkında bilgilendirilmesi ve bu durumu telafi etmek için dokümanın düzenini ayarlaması gerektiği anlamına gelir. Örneğin, kullanıcının yazmaya başlayacağı bir giriş alanı sanal klavye tarafından gizlenebilir. Bu nedenle, tarayıcının ekranı kaydırarak alanı görüntülemesi gerekir.

Tarayıcılar bu sorunu geleneksel olarak kendi başlarına çözmüştür ancak daha karmaşık uygulamalar, tarayıcı davranışı üzerinde daha fazla kontrol gerektirebilir. Örneğin, sanal klavye yalnızca bir ekran segmentinde gösterilirse geleneksel yaklaşımın "boşa harcanan" ekran alanı ile sonuçlanacağı, ancak yine de kullanılabilir görüntü alanının her iki ekranda da küçüldüğü çok ekranlı mobil cihazlar. Aşağıdaki resimde, sanal klavyenin varlığını telafi etmek için belgenin düzenini dinamik olarak optimize etmek amacıyla VirtualKeyboard API'nin nasıl kullanılabileceği gösterilmektedir.

Geleneksel yaklaşımın sonucunda

Bu gibi durumlarda VirtualKeyboard API devreye girer. Üç bölümden oluşur:

  • JavaScript'ten sanal klavyeye programatik erişim için navigator nesnesindeki VirtualKeyboard arayüzü.
  • Sanal klavyenin görünümü hakkında bilgi sağlayan bir dizi CSS ortam değişkeni.
  • Sanal klavyenin gösterilip gösterilmeyeceğini belirleyen sanal klavye politikası.

Mevcut durum

VirtualKeyboard API, Chromium 94'ten itibaren masaüstü ve mobil cihazlarda kullanılabilir.

Özellik algılama ve tarayıcı desteği

VirtualKeyboard API'nin geçerli tarayıcıda desteklenip desteklenmediğini tespit etmek için aşağıdaki snippet'i kullanın:

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

VirtualKlavye API'sini kullanma

VirtualKeyboard API, navigator nesnesine yeni bir arayüz VirtualKeyboard ekler.

Yeni sanal klavye davranışını etkinleştirme

Tarayıcıya, sanal klavye engellemelerini kendiniz hallettiğinizi bildirmek için önce overlaysContent boole özelliğini true olarak ayarlayarak yeni sanal klavye davranışını etkinleştirmeniz gerekir.

navigator.virtualKeyboard.overlaysContent = true;

Sanal klavyeyi gösterme ve gizleme

show() yöntemini çağırarak sanal klavyeyi programatik olarak gösterebilirsiniz. Bunun çalışması için odaklanan öğenin bir form denetimi (ör. textarea öğesi) veya düzenleme ana makinesi (ör. contenteditable özelliği kullanılarak) olması gerekir. Yöntem her zaman undefined değerini döndürür ancak sanal klavye daha önce gösterilmediyse bir geometrychange etkinliği tetikler.

navigator.virtualKeyboard.show();

Sanal klavyeyi gizlemek için hide() yöntemini çağırın. Yöntem her zaman undefined değerini döndürür ancak sanal klavye daha önce gösterildiyse bir geometrychange etkinliği tetikler.

navigator.virtualKeyboard.hide();

Mevcut geometriyi alma

boundingRect mülküne bakarak sanal klavyenin mevcut geometrisini alabilirsiniz. Sanal klavyenin mevcut boyutlarını DOMRect nesnesi olarak gösterir. İçe ekleme, üst, sağ, alt ve/veya sol özelliklerine karşılık gelir.

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

Geometri değişiklikleri hakkında bilgi alma

Sanal klavye her göründüğünde veya kaybolduğunda geometrychange etkinliği gönderilir. Etkinliğin target mülkü, virtualKeyboard nesnesini içerir. Bu nesne, yukarıda belirtildiği gibi sanal klavye eklentisinin yeni geometrisini DOMRect olarak içerir.

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

CSS ortamı değişkenleri

VirtualKlavye API'si, sanal klavyenin görünümü hakkında bilgi sağlayan bir dizi CSS ortam değişkeni sunar. Bunlar, inset CSS özelliğine benzer şekilde modellenmiştir. Yani üst, sağ, alt ve/veya sol özelliklerine karşılık gelir.

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

Sanal klavye iç içe yerleştirilmeleri, görüntü alanının kenarından üst, sağ, alt ve sol iç içe yerleştirilmelerine göre bir dikdörtgeni tanımlayan altı ortam değişkenidir. Genişlik ve yükseklik iç içe yerleştirilmeleri, geliştirici ergonomisi için diğer iç içe yerleştirilmelerden hesaplanır. Yedek değer sağlanmazsa her klavye eklentisinin varsayılan değeri 0px olur.

Ortam değişkenlerini genellikle aşağıdaki örnekte gösterildiği gibi kullanırsınız:

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

Sanal klavye politikası

Bazen düzenlenebilir bir öğe odaklandığında sanal klavye görünmemelidir. Örneğin, kullanıcının bir hücreye dokunarak değerinin başka bir hücrenin formülüne dahil edilmesini sağlayabileceği bir e-tablo uygulaması. virtualkeyboardpolicy, auto ve manual dizelerinin anahtar kelimeleri olduğu bir özelliktir. contenteditable ana makinesi olan bir öğede belirtildiğinde auto, karşılık gelen düzenlenebilir öğenin odaklanıldığında veya dokunulduğunda sanal klavyeyi otomatik olarak göstermesine neden olur ve manual, odağı sanal klavyenin mevcut durumundaki değişikliklerden ayırır ve düzenlenebilir öğeye dokunur.

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

VirtualKeyboard API'yi Glitch'teki demoda çalışırken görebilirsiniz. Nasıl uygulandığını görmek için kaynak kodunu keşfetmeyi unutmayın. geometrychange etkinlikleri iframe yerleşiminde gözlemlenebilir olsa da gerçek sanal klavye davranışı için demonun kendi tarayıcı sekmesinde açılması gerekir.

Teşekkür ederiz

VirtualKlavye API'sini Microsoft'tan Anupam Snigdha ve aynı şekilde Microsoft'tan eski editör Grisha Lyukshin'in katkılarıyla belirledi.