VirtualKeyboard API

概念

VirtualKeyboard API 由三部分組成：

• 透過 navigator.virtualKeyboard 訪問的 VirtualKeyboard 介面，用於退出自動虛擬鍵盤行為，以程式設計方式顯示或隱藏虛擬鍵盤，以及獲取虛擬鍵盤的當前位置和大小。
• keyboard-inset-* CSS 環境變數提供有關虛擬鍵盤位置和大小的資訊。
• virtualkeyboardpolicy 屬性指定是否應在 contenteditable 元素上顯示虛擬鍵盤。

退出自動虛擬鍵盤行為

要退出瀏覽器的自動虛擬鍵盤行為，請使用 navigator.virtualKeyboard.overlaysContent = true。瀏覽器將不再自動調整視口大小以容納虛擬鍵盤，而是讓虛擬鍵盤覆蓋您的內容。

使用 JavaScript 檢測虛擬鍵盤的幾何形狀

在退出預設的瀏覽器行為後，您可以使用 navigator.virtualKeyboard.boundingRect 獲取虛擬鍵盤的當前幾何形狀，並使用 CSS 和 JavaScript 適當地調整佈局。此外，您還可以透過使用 geometrychange 事件來監聽幾何形狀的變化，例如鍵盤何時顯示或隱藏。

這對於將重要 UI 元素定位在虛擬鍵盤未覆蓋的區域非常有用。

下面的程式碼片段使用 geometrychange 事件來檢測虛擬鍵盤幾何形狀何時發生變化；然後它訪問 boundingRect 屬性來查詢虛擬鍵盤的大小和位置。

if ("virtualKeyboard" in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;

  navigator.virtualKeyboard.addEventListener("geometrychange", (event) => {
    const { x, y, width, height } = event.target.boundingRect;
  });
}

使用 CSS 環境變數檢測虛擬鍵盤的幾何形狀

VirtualKeyboard API 還公開了以下 CSS 環境變數：keyboard-inset-top、keyboard-inset-right、keyboard-inset-bottom、keyboard-inset-left、keyboard-inset-width 和 keyboard-inset-height。

keyboard-inset-* CSS 環境變數可用於使用 CSS 將您的佈局適配到虛擬鍵盤的外觀。它們透過視口邊緣的頂部、右側、底部和左側內邊距定義一個矩形。如果需要，還可以使用 width 和 height 變數。

下面的程式碼片段使用 keyboard-inset-height CSS 變數為聊天類應用程式中訊息列表和輸入欄位下方顯示虛擬鍵盤預留空間。當虛擬鍵盤隱藏時，env() 函式返回 0px，並且 keyboard 網格區域被隱藏。訊息和輸入元素可以佔用視口的全部高度。當虛擬鍵盤出現時，keyboard 網格區域的高度將等於虛擬鍵盤的高度。

<ul id="messages"></ul>
<input type="text" />

body {
  display: grid;
  margin: 0;
  height: 100vh;
  grid-template:
    "messages" 1fr
    "input" auto
    "keyboard" env(keyboard-inset-height, 0px);
}

if ("virtualKeyboard" in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;
}

控制 contenteditable 元素上的虛擬鍵盤

預設情況下，使用 contenteditable 屬性的元素在被點選或輕觸時也會觸發虛擬鍵盤。在某些情況下，可能希望阻止此行為，而是改為在其他事件後顯示虛擬鍵盤。

將 virtualkeyboardpolicy 屬性設定為 manual，以阻止瀏覽器對虛擬鍵盤的預設處理，而是使用 VirtualKeyboard 介面的 show() 和 hide() 方法手動處理。

下面的程式碼片段展示瞭如何使用 virtualkeyboardpolicy 屬性和 navigator.virtualKeyboard.show() 方法在雙擊時顯示虛擬鍵盤。

<div contenteditable virtualkeyboardpolicy="manual" id="editor"></div>

if ("virtualKeyboard" in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;

  const editor = document.getElementById("editor");
  editor.addEventListener("dblclick", () => {
    navigator.virtualKeyboard.show();
  });
}

介面

VirtualKeyboard Experimental

提供用於檢索鍵盤佈局圖和切換物理鍵盤按鍵捕獲的函式。

其他介面的擴充套件

Navigator.virtualKeyboard Read only Experimental

返回一個指向 VirtualKeyboard API 的引用，用於控制螢幕上的虛擬鍵盤。

HTMLElement.virtualKeyboardPolicy Experimental

一個字串，指示是使用瀏覽器在元素獲得焦點時顯示虛擬鍵盤的預設策略，還是手動處理虛擬鍵盤的顯示。

規範

瀏覽器相容性

另見

• 使用 VirtualKeyboard API 完全控制