使用視窗控制項重疊在標題列區域中顯示內容

安裝在桌面上的漸進式 Web 應用程式 (PWA) 可以使用視窗控制項重疊 API,在標題列正常位置的位置顯示內容,讓 PWA 感覺更原生。

Window Controls Overlay API 會執行下列工作:

  • 可讓您在應用程式的整個表面區域上顯示 Web 內容。
  • 將系統所需的重要視窗控制項移至重疊中。
  • 可讓您的內容遠離此重疊。

漸進式 Web 應用程式 (PWA) 可以使用 Web 應用程式資訊清單檔案中的 顯示 成員來定義它在行動裝置上的顯示方式。 不過,若要建立類似原生的沉浸式體驗, 桌面 PWA 可以使用另一種方法。

根據預設,安裝在桌面上的 PWA 可以在緊接保留標題列區域下方開始的區域中顯示內容:

Windows 上的 PWA 應用程式,顯示應用程式內容顯示在保留的標題列區域下方

在標題列正常所在的位置顯示內容,可協助 PWA 感覺更原生。 許多桌面應用程式,例如 Visual Studio Code、Microsoft Teams 和 Microsoft Edge 已經執行此動作:

Visual Studio Code 會在標題列區域中顯示內容

在您的應用程式中啟用視窗控制項重疊

首先,在應用程式的 Web 應用程式資訊清單檔案中啟用 [視窗控制項重疊] 功能。 若要這樣做,請在資訊清單檔案中設定 display_override 屬性:

{
  "display_override": ["window-controls-overlay"]
}

另請參閱:

使用 CSS 環境變數避免重疊

env() CSS 函數可用於存取使用者代理定義的環境變數。

[視窗控制項重疊] 功能會新增四個環境變數:

變數 描述
titlebar-area-x 標題列通常從視窗左側佔據的區域的距離,以 為單位 px。
titlebar-area-y 標題列通常佔據的區域與視窗頂端的距離,以 為單位 px。
titlebar-area-width 標題列區域的寬度,以 為 px單位。
titlebar-area-height 標題列區域的高度,以 px為單位。

當停用視窗控制項重疊功能時,您可以使用這些環境變數來定位標題列正常顯示的位置和調整您自己的內容的大小:

#title-bar {
  position: fixed;
  left: env(titlebar-area-x, 0);
  top: env(titlebar-area-y, 0);
  height: env(titlebar-area-height, 50px);
  width: env(titlebar-area-width, 100%);
}

使用 position: fixed; 可確保您的標題列不會與其他內容一起捲動,而是與視窗控制項重疊保持一致。

了解覆蓋的位置及其大小非常重要。 覆蓋層可能並不總是在窗戶的同一側;在 macOS 上,重疊位於左側,但在 Windows 上,重疊位於右側。 此外,重疊的大小不一定相同。

env() CSS 函數採用第二個參數,當視窗控制項重疊功能遺失或停用時,此功能適用於定義應用程式內容的位置。

將區域設為視窗的拖曳控點

當標題列隱藏時,只有系統關鍵的視窗控制項會保持可見, ([最大化]、[最小化]、[關閉] 和 [應用程式資訊] 圖示) 。 這意味著可供使用者移動應用程式視窗的空間非常小。

您可以使用 app-region CSS 屬性為使用者提供更多拖曳應用程式的方式。 例如,如果您的應用程式有自己的標題列,您可以將其標題列轉換成視窗拖曳控點:

#title-bar {
  position: fixed;
  left: env(titlebar-area-x, 0);
  top: env(titlebar-area-y, 0);
  height: env(titlebar-area-height, 50px);
  width: env(titlebar-area-width, 100%);
  app-region: drag;
}

對重疊變更做出 React

使用者可以在應用程式執行時切換標題列或變更視窗尺寸。 了解這些事情何時發生,對您的應用程式非常重要。 您的應用程式可能需要重新排列標題列中顯示的部分內容,或重新排列頁面上其他位置的版面配置。

若要接聽變更,請使用 geometrychange 物件上的 navigator.windowControlsOverlay 事件。 若要偵測標題列是否可見,請使用 visible 物件上的 navigator.windowControlsOverlay 屬性。

geometrychange當使用者調整視窗大小時,事件會非常頻繁地引發。 若要避免過於頻繁地執行會變更版面配置的程式碼,導致應用程式發生效能問題,請使用 debounce 函式來限制處理事件的次數。 查看 節流和去跳動之間的差異。

const debounce = (func, wait) => {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
};

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', debounce(e => {
    // Detect if the Window Controls Overlay is visible.
    const isOverlayVisible = navigator.windowControlsOverlay.visible;

    // Get the size and position of the title bar area.
    const titleBarRect = e.titlebarAreaRect;

    console.log(`The overlay is ${isOverlayVisible ? 'visible' : 'hidden'}, the title bar width is ${titleBarRect.width}px`);
  }, 200));
}

示範應用程式

1DIV 是一個使用 Window Controls Overlay 功能的 PWA 演示應用程序。

  1. 在 Microsoft Edge 中,在新視窗或索引標籤中開啟 1DIV 示範應用程式。

  2. 在網址列中,按一下 可用的應用程式。安裝 1DIV (「應用程式應用程式可用。安裝 1DIV」圖示) 按鈕。 安裝 1DIV 應用程式對話 方塊隨即開啟。

  3. 按一下 [ 安裝 ] 按鈕。 1DIV 應用程式會在自己的視窗中開啟,並開啟「 應用程式已安裝 」對話方塊:

    1DIV 應用程式在其自己的視窗中,顯示「應用程式已安裝」對話方塊

  4. 按一下對話方塊的 [ 關閉 (X) ] 按鈕。 (或者,選取或清除核取方塊,然後按一下 [ 允許] 按鈕。)

    應用程式的標題列至少包含下列視窗控制項:

    圖示 工具提示
    [設定及其他] 圖示 設定及其他
    [最小化] 圖示 Minimize
    [還原] 圖示 還原
    [關閉] 圖示 Close

    應用程式現在會一直將內容顯示到視窗框架頂端,標題列原來所在的位置:

    地圖頂端區域可用來移動視窗

    應用程式的頂端區域是拖曳控點,方便使用者移動視窗。

此示範應用程式的原始程式碼位於 1DIV 存放庫中。

  • manifest.json 來源檔案會宣告應用程式使用視窗控制項重疊功能。

  • app.js 來源檔案會使用該navigator.windowControlsOverlay物件。

  • app.css 來源檔案使用 titlebar-area-* CSS 環境變數。

預覽自訂覆疊而不安裝 PWA

在 Microsoft Edge 開發工具 的應用程式工具 中,您可以模擬 [視窗控制項重疊] (WCO) 功能,而不需要先安裝 PWA 並啟用 WCO 功能。 藉由從開發工具內模擬 WCO 功能,您可以比重新安裝修訂的 PWA 更快速地測試標題列區域的 CSS 程式碼變更。

模擬重疊是靜態影像。 CSS 變數 env(titlebar-area-left)、 env(titlebar-area-top)env(titlebar-area-width)和 env(titlebar-area-height) 的值設定為與您選取的平台相符。

請參閱 在不安裝 PWA 的情況下模擬視窗控制項重疊 API。

另請參閱

MDN:

部落格:

YouTube:

示範: