Bu sayfa, Cloud Translation API ile çevrilmiştir.

VirtualKeyboard API ile tam kontrol

Thomas Steiner

Tarayıcı Desteği

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ı dengelemek için belge düzenini dinamik olarak optimize etmek amacıyla VirtualKlavye API'sinin nasıl kullanılabileceği gösterilmektedir.

Geleneksel yaklaşımın sonucunda

VirtualKlavye API'si bu gibi durumlarda 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

Geçerli tarayıcıda VirtualKlavye API'sinin desteklenip desteklenmediğini tespit etmek için şu 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 gizleme işlemlerini kendinizin yaptığını bildirmek için önce overlaysContent doğru/yanlış ö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 programlı bir şekilde 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österilmemişse bir geometrychange etkinliğini 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();

Geçerli 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 bilgilendirme

Sanal klavye her göründüğünde veya kaybolduğunda geometrychange etkinliği gönderilir. Etkinliğin target özelliği, sanal klavyenin DOMRect olarak eklenen yeni geometrisini içeren virtualKeyboard nesnesini içerir (yukarıda açıklandığı gibi).

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şkeni gösterir. inset CSS mülküne benzer şekilde, yani üst, sağ, alt ve/veya sol mülklerine karşılık gelen bir şekilde modellenirler.

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

Düzenlenebilir bir öğeye odaklanıldığında bazen sanal klavyenin görünmemesi gerekir. Ö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, anahtar kelimeleri auto ve manual dizeleri olan bir özelliktir. contenteditable ana makine olan bir öğede belirtildiğinde auto, ilgili düzenlenebilir öğenin odaklandığında veya dokunulduğunda sanal klavyeyi otomatik olarak göstermesine neden olur. manual ise düzenlenebilir öğeye odaklanmayı ve öğeye dokunmayı, 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'yi Glitch'teki demoda çalışırken görebilirsiniz. Nasıl uygulandığını görmek için kaynak kodunu keşfetmeyi unutmayın. iframe yerleştirmede geometrychange etkinlikleri gözlemlenebilir, ancak gerçek sanal klavye davranışı için demonun kendi tarayıcı sekmesinde açılması gerekir.

Faydalı bağlantı

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.