使用 VirtualKeyboard API 完全控管

Thomas Steiner

瀏覽器支援

  • 94
  • 94
  • x
  • x

平板電腦或手機等裝置通常會有用於輸入文字的虛擬鍵盤。 虛擬鍵盤不同於隨時顯示且一律相同的實體鍵盤， 取決於使用者的動作，他們也能動態調整 例如根據 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 是屬性，其關鍵字是 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>

示範

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

特別銘謝

VirtualKeyboard API 是由 Microsoft 的 Anupam Snigdha 指定， Microsoft 的前編輯人員 Grisha Lyukshin。主頁橫幅製作者： @freestocks： Unsplash。