Perangkat seperti tablet atau ponsel biasanya memiliki {i>keyboard<i} virtual untuk mengetik teks.
Tidak seperti {i>keyboard<i} fisik yang selalu ada dan selalu sama, {i>keyboard<i} virtual muncul
dan menghilang, tergantung pada tindakan pengguna, di mana ia juga dapat beradaptasi secara dinamis, untuk
berdasarkan
inputmode
.
Fleksibilitas ini mengharuskan mesin tata letak browser memberi tahu tentang kehadiran {i>keyboard<i} virtual dan berpotensi menyesuaikan tata letak dokumen untuk kompensasi. Misalnya, bidang {i>input <i}yang akan dimasukkan pengguna mungkin terhalang oleh {i>keyboard<i} virtual, sehingga browser harus menggulirnya ke dalam tampilan.
Biasanya, browser mengatasi tantangan ini sendiri, namun aplikasi yang lebih kompleks mungkin memerlukan kontrol lebih besar terhadap perilaku browser. Contohnya mencakup perangkat seluler multilayar di mana pendekatan tradisional akan mengakibatkan "pemborosan" ruang layar jika {i>keyboard<i} virtual ditampilkan hanya pada satu segmen layar, tetapi area pandang yang tersedia menyusut di kedua layar meskipun begitu. Gambar di bawah menunjukkan cara penggunaan VirtualKeyboard API untuk mengoptimalkan tata letak dokumen secara dinamis untuk mengompensasi kehadiran {i>keyboard<i} virtual.
Dalam situasi seperti ini, VirtualKeyboard API hadir. Ini terdiri dari tiga bagian:
- Antarmuka
VirtualKeyboard
pada objeknavigator
untuk akses terprogram ke virtual dari JavaScript. - Serangkaian variabel lingkungan CSS yang menyediakan informasi tentang atribut keyboard virtual tampilan.
- Kebijakan keyboard virtual yang menentukan apakah keyboard virtual harus ditampilkan.
Status saat ini
VirtualKeyboard API tersedia dari Chromium 94 di desktop dan perangkat seluler.
Deteksi fitur dan dukungan browser
Untuk mendeteksi apakah VirtualKeyboard API didukung di browser saat ini, gunakan cuplikan berikut:
if ('virtualKeyboard' in navigator) {
// The VirtualKeyboard API is supported!
}
Menggunakan VirtualKeyboard API
VirtualKeyboard API menambahkan antarmuka baru VirtualKeyboard
ke objek navigator
.
Memilih untuk menerapkan perilaku keyboard virtual baru
Untuk memberi tahu browser bahwa Anda menangani sendiri pemblokiran keyboard virtual, Anda harus
pertama-tama pilih untuk menggunakan perilaku keyboard virtual baru dengan menyetel properti boolean overlaysContent
ke true
.
navigator.virtualKeyboard.overlaysContent = true;
Menampilkan dan menyembunyikan keyboard virtual
Anda dapat menampilkan keyboard virtual secara terprogram dengan memanggil metode show()
. Agar berhasil,
elemen yang difokuskan harus berupa kontrol formulir (seperti elemen textarea
), atau menjadi host pengeditan
(misalnya, dengan menggunakan
contenteditable
). Metode ini selalu menampilkan undefined
tetapi memicu peristiwa geometrychange
jika {i>keyboard<i} virtual sebelumnya
tidak ditampilkan.
navigator.virtualKeyboard.show();
Untuk menyembunyikan keyboard virtual, panggil metode hide()
. Metode ini selalu menampilkan undefined
tetapi memicu
peristiwa geometrychange
jika keyboard virtual sebelumnya ditampilkan.
navigator.virtualKeyboard.hide();
Mendapatkan geometri saat ini
Anda bisa mendapatkan geometri keyboard virtual saat ini dengan melihat properti boundingRect
.
Tampilan ini menampilkan dimensi {i>keyboard<i} virtual saat ini sebagai
Objek DOMRect
.
Inset sesuai dengan properti atas, kanan, bawah, dan/atau kiri.
const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);
Mendapatkan informasi tentang perubahan geometri
Setiap kali keyboard virtual muncul atau menghilang, peristiwa geometrychange
akan dikirim. Tujuan
properti target
peristiwa berisi objek virtualKeyboard
yang (seperti yang dibahas di atas) berisi geometri baru dari inset keyboard virtual sebagai
DOMRect
navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
const { x, y, width, height } = event.target.boundingRect;
console.log('Virtual keyboard geometry changed:', x, y, width, height);
});
Variabel lingkungan CSS
VirtualKeyboard API mengekspos sekumpulan variabel lingkungan CSS yang menyediakan informasi tentang
tampilan {i>keyboard<i} virtual.
Properti tersebut dimodelkan mirip dengan properti CSS inset
.
yaitu, yang sesuai dengan properti atas, kanan, bawah, dan/atau kiri.
keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height
Inset {i>keyboard<i} virtual adalah enam variabel lingkungan yang
menentukan persegi panjang di atas, di kanan,
inset bawah, dan kiri dari tepi area tampilan. Inset lebar dan tinggi dihitung
dari inset lain untuk ergonomi developer. Nilai default setiap inset keyboard adalah
0px
jika nilai penggantian tidak diberikan.
Anda biasanya akan menggunakan variabel lingkungan seperti dalam contoh di bawah ini:
.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);
}
Kebijakan keyboard virtual
Terkadang keyboard virtual tidak muncul saat elemen yang dapat diedit difokuskan. Contohnya adalah
aplikasi {i>spreadsheet <i}di mana pengguna dapat mengetuk sel agar nilainya dimasukkan dalam rumus
sel lain. virtualkeyboardpolicy
adalah atribut yang kata kuncinya adalah string auto
dan
manual
. Jika ditentukan pada elemen yang merupakan host contenteditable
, auto
menyebabkan
elemen yang sesuai dan dapat diedit untuk otomatis menampilkan keyboard virtual saat difokuskan atau
diketuk, dan manual
memisahkan fokus dan mengetuk elemen yang dapat diedit dari perubahan di virtual
status keyboard saat ini.
<!-- 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
Anda bisa melihat VirtualKeyboard API beraksi dalam
demo di Glitch. Pastikan untuk mempelajari
kode sumber untuk melihat cara penerapannya.
Meskipun peristiwa geometrychange
dapat diamati dalam sematan iframe, keyboard virtual yang sebenarnya
perilaku ini mengharuskan Anda membuka demo di tab browsernya sendiri.
Link penting
- Spesifikasi
- Repositori
- Entri ChromeStatus
- Bug Chromium
- Peninjauan TAG W3C
- Permintaan posisi standar Mozilla
- Permintaan posisi standar WebKit
Ucapan terima kasih
VirtualKeyboard API ditetapkan oleh Anupam Snigdha dari Microsoft, dengan kontribusi dari mantan editor Grisha Lyukshin, juga dari Microsoft. Banner besar oleh @freestocks pada Buka pembuka.