使用 VirtualKeyboard API 完全控管

瀏覽器支援

  • Chrome:94。
  • Edge:94。
  • Firefox:不支援。
  • Safari:不支援。

資料來源

平板電腦或手機等裝置通常會有用於輸入文字的虛擬鍵盤。 虛擬鍵盤不同於隨時顯示且一律相同的實體鍵盤, 取決於使用者的動作,他們也能動態調整 例如根據 inputmode敬上 屬性。

這項靈活彈性顧及瀏覽器的版面配置引擎 虛擬鍵盤的在家狀態,而且可能需要調整文件版面配置, 不利於報酬。舉例來說,使用者要輸入的輸入欄位可能會遭到 虛擬鍵盤,因此瀏覽器必須將其捲動至檢視畫面中。

傳統上,瀏覽器自行處理的是這項挑戰,但也比較複雜應用程式 可能需要進一步控制瀏覽器的行為。例如多螢幕行動裝置 傳統做法會導致「浪費」螢幕空間 (如果虛擬鍵盤的話) 只會顯示在一個畫面區隔上,但兩個螢幕都會縮小可用的檢視區。 不過,下圖顯示如何使用 VirtualKeyboard API 將版面配置最佳化 來彌補虛擬鍵盤的存在。

傳統做法則

像這樣的情境是 VirtualKeyboard API 得以派上用場的地方。其中包含三個部分:

  • navigator 物件的 VirtualKeyboard 介面,可透過程式輔助方式存取虛擬 鍵盤。
  • 一組 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 是屬性,其關鍵字是 automanual。在 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>

示範

您可以在 示範。請務必查看 原始碼以瞭解實作方式。 雖然可以在 iframe 嵌入中觀察到 geometrychange 事件,但實際的虛擬鍵盤 使用者必須在瀏覽器的分頁中開啟示範內容。

特別銘謝

VirtualKeyboard API 是由 Microsoft 的 Anupam Snigdha 指定, Microsoft 的前編輯人員 Grisha Lyukshin。主頁橫幅製作者: @freestocksUnsplash