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ıdaki 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ğı 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'den sanal klavyeye programatik erişim için navigator nesnesinde bulunan 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, 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!
}

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 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 yerleştirilen öğe, ü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 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

VirtualKeyboard API, sanal klavyenin görünümü hakkında bilgi sağlayan bir dizi CSS ortam değişkeni gösterir. 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 makine olan bir öğede belirtildiğinde auto, ilgili düzenlenebilir öğenin odaklandığında veya dokunulduğunda sanal klavyeyi otomatik olarak göstermesine neden olur ve manual, 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 demo'da ç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.

Faydalı bağlantı

Teşekkür ederiz

VirtualKeyboard API, Microsoft'tan Anupam Snigdha tarafından, yine Microsoft'tan eski düzenleyici Grisha Lyukshin'in katkılarıyla belirlenmiştir.