本頁面由 Cloud Translation API 翻譯而成。

使用 VirtualKeyboard API 完全控管

Thomas Steiner

瀏覽器支援

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