VirtualKeyboard API ile tam kontrol

Thomas Steiner

Browser Support

  • Chrome: 94.
  • Edge: 94.
  • Firefox: not supported.
  • Safari: not supported.

Source

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

Bu esneklik, tarayıcının düzen motorunun sanal klavyenin varlığından haberdar olması ve telafi etmek için belgenin düzenini ayarlaması gerekebileceği anlamına gelir. Örneğin, kullanıcının yazmaya başlayacağı bir giriş alanı sanal klavye tarafından kapatılabilir. Bu durumda tarayıcının, alanı görünür hale getirmek için kaydırması gerekir.

Tarayıcılar bu zorluğun üstesinden genellikle kendi başlarına gelir ancak daha karmaşık uygulamalar, tarayıcının davranışı üzerinde daha fazla kontrol gerektirebilir. Örneğin, geleneksel yaklaşımda sanal klavye yalnızca bir ekran segmentinde gösterilse bile kullanılabilir görünüm alanı her iki ekranda da küçüldüğü için "boşa harcanan" ekran alanı oluşmasına neden olan çok ekranlı mobil cihazlar. Aşağıdaki resimde, sanal klavyenin varlığını telafi etmek için VirtualKeyboard API'nin dokümanın düzenini dinamik olarak optimize etmek amacıyla nasıl kullanılabileceği gösterilmektedir.

Geleneksel yaklaşım,

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 bir sanal klavye politikası.

Mevcut durum

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

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

VirtualKeyboard API'nin mevcut tarayıcıda desteklenip desteklenmediğini algılamak için aşağıdaki snippet'i kullanın:

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

VirtualKeyboard API'yi kullanma

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

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

Tarayıcıya sanal klavye kapatmalarını kendiniz hallettiğinizi bildirmek için öncelikle 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. Bu özelliğin çalışması için odaklanılan öğenin bir form kontrolü (ör. textarea öğesi) olması veya düzenleme ana makinesi olması gerekir (ör. contenteditable özelliği kullanılarak). Yöntem her zaman undefined değerini döndürür ancak sanal klavye daha önce gösterilmediyse geometrychange etkinliğini tetikler.

navigator.virtualKeyboard.show();

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

navigator.virtualKeyboard.hide();

Geçerli geometriyi alma

boundingRect özelliğine bakarak sanal klavyenin mevcut geometrisini elde edebilirsiniz. Sanal klavyenin mevcut boyutlarını DOMRect nesnesi olarak gösterir. İç kısım; ü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 özelliği, virtualKeyboard nesnesini içerir. Bu nesne (yukarıda bahsedildiği gibi) sanal klavye yerleştirme alanının 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

VirtualKeyboard API, sanal klavyenin görünümü hakkında bilgi sağlayan bir dizi CSS ortam değişkenini kullanıma sunar. Bunlar, inset CSS özelliğine benzer şekilde modellenir. 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ç kısımları, görüntü alanının kenarından üst, sağ, alt ve sol iç kısımlarıyla bir dikdörtgeni tanımlayan altı ortam değişkenidir. Genişlik ve yükseklik iç kısımları, geliştirici ergonomisi için diğer iç kısımlardan hesaplanır. Geri dönüş değeri sağlanmazsa her klavye yerleştirme alanının varsayılan değeri 0px olur.

Ortam değişkenlerini genellikle aşağıdaki örnekte olduğu 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 öğeye odaklanıldığı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ğladığı bir e-tablo uygulaması. virtualkeyboardpolicy, anahtar kelimeleri auto ve manual dizeleri olan bir özelliktir. contenteditable ana makinesi olan bir öğede belirtildiğinde auto, odaklanıldığında veya dokunulduğunda ilgili düzenlenebilir öğenin sanal klavyeyi otomatik olarak göstermesine neden olur. manual ise düzenlenebilir öğedeki odaklanma ve dokunma işlemlerini sanal klavyenin mevcut durumundaki değişikliklerden ayırır.

<!-- 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'nin nasıl çalıştığını demoda görebilirsiniz. Nasıl uygulandığını görmek için kaynak kodunu inceleyin. geometrychange etkinlikleri iframe yerleştirmesinde gözlemlenebilir ancak sanal klavyenin gerçek davranışını görmek için demoyu kendi tarayıcı sekmesinde açmak gerekir.

Teşekkür

VirtualKeyboard API, Microsoft'tan Anupam Snigdha tarafından belirtilmiş olup Microsoft'tan eski editör Grisha Lyukshin'in katkılarıyla oluşturulmuştur.