在標題列區域使用視窗控制覆蓋顯示內容

安裝在桌面上的漸進式網頁應用程式 (PWA) ，可以透過 Window Controls Overlay API 將內容顯示在標題欄通常所在的位置，讓 PWA 感覺更原生。

視窗控制覆蓋層 API 的功能如下：

讓你能在整個應用程式的表面區域上顯示網頁內容。
將系統所需的關鍵視窗控制項移入覆蓋層。
這樣你的內容就能避免被這種疊加層覆蓋。

PWA (漸進式網頁應用程式) 可透過網頁應用程式清單檔案中的顯示成員，定義其在行動平台上的顯示方式。然而，為了打造沉浸式、原生感的體驗，桌面 PWA 可以採用另一種方式。

預設情況下，安裝在桌面上的 PWA 可以在保留標題列區域下方的區域顯示內容：

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

將內容顯示在標題欄通常所在的位置，能讓 PWA 感覺更貼近原生。許多桌面應用程式，如 Visual Studio Code、Microsoft Teams 和 Microsoft Edge 已經具備此功能：

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

在你的應用程式中啟用視窗控制覆蓋

首先，啟用你應用程式網頁應用程式清單檔案中的視窗控制覆蓋功能。為此，在清單檔案中設定 display_override 以下屬性：

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

另請參閱:

display_override MDN > 參考 > 網頁應用清單。
網頁應用程式的顯現資料可參考 MDN > 參考資料。
網頁應用程式的表現形式包括 MDN> 參考漸>進式網頁應用>指南。

切換標題欄

啟用視窗控制覆蓋功能後，使用者可點擊標題欄切換按鈕，選擇是否擁有標題列：

你的程式碼不能假設視窗控制覆蓋層會顯示，因為：

使用者可以選擇是否顯示標題列。
你的應用程式也可以在網頁瀏覽器或行動裝置上執行，也可以作為桌面應用程式執行。

因此，你的程式碼需要對標題列幾何形狀的變化做出反應。欲了解更多，請參閱 React to overlay 變更。

使用 CSS 環境變數以避免覆蓋層

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

視窗控制覆蓋功能新增了四個環境變數：

變數	描述
`titlebar-area-x`	距離視窗左側標題欄通常佔據區域的距離（in `px`）
`titlebar-area-y`	距離視窗上方標題欄通常佔據區域的距離（in `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 事件。要判斷標題列是否可見，請使用物件上的navigator.windowControlsOverlay屬性visible。

當使用者調整視窗大小時，事件 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));
}