平板電腦或手機等裝置通常會提供虛擬鍵盤,方便使用者輸入文字。與實體鍵盤總是顯示且一成不變不同,虛擬鍵盤的顯示和隱藏會依使用者的動作而定,且可動態調整,例如根據 inputmode
屬性。
這種彈性雖然方便,但瀏覽器的版面配置引擎必須知道虛擬鍵盤的存在,且可能需要調整文件的版面配置來進行補償。舉例來說,使用者要輸入的輸入欄位可能會被虛擬鍵盤遮住,因此瀏覽器必須將其捲動至可視範圍內。
傳統上,瀏覽器會自行處理這項挑戰,但較複雜的應用程式可能需要進一步控管瀏覽器的行為。例如多螢幕行動裝置,如果虛擬鍵盤只顯示在一個螢幕區段,傳統方法會導致螢幕空間「浪費」,但可用的檢視區會在兩個螢幕上縮小。下圖顯示如何使用 VirtualKeyboard API 以動態方式最佳化文件的版面配置,彌補虛擬鍵盤的不足。
這類情況就是 VirtualKeyboard API 的用武之地。其中包含三個部分:
navigator
物件上的VirtualKeyboard
介面,可透過 JavaScript 以程式輔助方式存取虛擬鍵盤。- 一組 CSS 環境變數,提供虛擬鍵盤外觀的相關資訊。
- 虛擬鍵盤政策,用於決定是否應顯示虛擬鍵盤。
目前狀態
在 Chromium 94 中,VirtualKeyboard API 已可供電腦和行動裝置使用。
功能偵測和瀏覽器支援
如要偵測目前瀏覽器是否支援 VirtualKeyboard API,請使用下列程式碼片段:
if ('virtualKeyboard' in navigator) {
// The VirtualKeyboard API is supported!
}
使用 VirtualKeyboard API
VirtualKeyboard API 會為 navigator
物件新增介面 VirtualKeyboard
。
啟用新的虛擬鍵盤行為
如要告知瀏覽器您會自行處理虛擬鍵盤遮蔽問題,請先將布林值屬性 overlaysContent
設為 true
,啟用新的虛擬鍵盤行為。
navigator.virtualKeyboard.overlaysContent = true;
顯示及隱藏虛擬鍵盤
您可以呼叫 show()
方法,透過程式輔助顯示虛擬鍵盤。為使這項功能正常運作,焦點元素必須是表單控制項 (例如 textarea
元素),或是編輯主機 (例如使用 contenteditable
屬性)。這個方法一律會傳回 undefined
,但如果先前未顯示虛擬鍵盤,則會觸發 geometrychange
事件。
navigator.virtualKeyboard.show();
如要隱藏虛擬鍵盤,請呼叫 hide()
方法。此方法一律會傳回 undefined
,但如果先前顯示虛擬鍵盤,則會觸發 geometrychange
事件。
navigator.virtualKeyboard.hide();
取得目前幾何圖形
您可以查看 boundingRect
屬性,取得虛擬鍵盤的目前幾何圖形。它會將虛擬鍵盤的目前尺寸公開為 DOMRect
物件。內嵌區塊會對應到頂端、右側、底部和/或左側屬性。
const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);
收到幾何圖形變更通知
每當虛擬鍵盤顯示或消失時,系統就會調度 geometrychange
事件。事件的 target
屬性包含 virtualKeyboard
物件,而該物件 (如上文所述) 會以 DOMRect
的形式包含虛擬鍵盤內嵌的新幾何圖形。
navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
const { x, y, width, height } = event.target.boundingRect;
console.log('Virtual keyboard geometry changed:', x, y, width, height);
});
CSS 環境變數
VirtualKeyboard API 會公開一組 CSS 環境變數,提供虛擬鍵盤外觀的相關資訊。這些屬性模擬的對象類似於 inset
CSS 屬性,也就是對應於上、右、下和/或左屬性。
keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height
虛擬鍵盤插邊是六個環境變數,可透過從可視區域邊緣的頂端、右側、底部和左側插邊定義矩形。寬度和高度插邊是由開發人員人體工學的其他插邊計算得出。如未提供備用值,每個鍵盤插邊的預設值為 0px
。
您通常會使用環境變數,如下列範例所示:
.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);
}
虛擬鍵盤政策
有時,當可編輯元素取得焦點時,虛擬鍵盤不應顯示。以試算表應用程式為例,使用者只要輕觸儲存格,就能將其值納入另一個儲存格的公式中。virtualkeyboardpolicy
是屬性,其關鍵字是 auto
和 manual
字串。如果在 contenteditable
主機元素上指定 auto
,則當對應的編輯元素獲得焦點或輕觸時,系統會自動顯示虛擬鍵盤,而 manual
會將焦點和輕觸與虛擬鍵盤的目前狀態變更分離。
<!-- 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>
示範
您可以在 Glitch 的示範中,查看 VirtualKeyboard API 的實際使用方式。請務必查看原始碼,瞭解實作方式。雖然您可以在 iframe 嵌入內容中觀察 geometrychange
事件,但要實際顯示虛擬鍵盤行為,您必須在自己的瀏覽器分頁中開啟示範畫面。
實用連結
特別銘謝
VirtualKeyboard API 是由 Microsoft 的 Anupam Snigdha 指定,並由 Microsoft 的前編輯 Grisha Lyukshin 提供貢獻。