關於視窗插邊

Android 平台負責繪製系統 UI，例如狀態列和導覽列。無論使用者使用哪一個應用程式，系統都會顯示這個系統 UI。

WindowInsets 提供系統 UI 的相關資訊，確保應用程式在正確的區域繪製，且 UI 不會遭到系統 UI 遮蔽。

圖 1. 採用無邊框設計，在系統資訊列後方繪製內容。

在 Android 14 (API 級別 34) 以下版本中，應用程式的 UI 預設不會在系統資訊列和螢幕凹口下方繪製。

在 Android 15 (API 級別 35) 以上版本中，如果應用程式指定 SDK 35 為目標，就會在系統資訊列和螢幕凹口下方繪製。這樣一來，使用者體驗會更流暢，應用程式也能充分運用可用的視窗空間。

在系統 UI 後方顯示內容稱為「無邊框」。本頁面將說明不同類型的插邊、如何採用無邊框設計，以及如何使用插邊 API 為 UI 加上動畫效果，並確保應用程式內容不會遭到系統 UI 元素遮蓋。

重要事項： 如果應用程式指定 SDK 35，在 Android 15 以上版本中會強制採用無邊框模式。如果應用程式尚未採用無邊框設計，部分內容可能會遭到遮蓋，因此您必須處理插邊。視應用程式而定，這項工作可能重要，也可能不重要。Material 3 Scaffold 元件可減少為符合 Android 15 無邊框強制規定所需的工作。請參閱「建立 Scaffold 元件來整合 UI」。

插圖基本概念

應用程式採用無邊框設計時，請務必確保重要內容和互動不會遭到系統 UI 遮蓋。舉例來說，如果按鈕位於導覽列後方，使用者可能無法點選。

系統 UI 的大小和位置資訊是使用插邊指定。

系統 UI 的每個部分都有對應的插邊類型，用來描述其大小和位置。舉例來說，狀態列插邊會提供狀態列的大小和位置，而導覽列插邊則會提供導覽列的大小和位置。每種插邊都包含四個像素尺寸：頂端、左側、右側和底部。這些維度會指定系統 UI 從應用程式視窗對應側延伸的距離。因此，為避免與這類系統 UI 重疊，應用程式 UI 必須內縮該數量。

您可以透過 WindowInsets 使用以下內建 Android 插邊類型：

WindowInsets.statusBars	描述狀態列的插邊。這是頂端的系統 UI 列，包含通知圖示和其他指標。
WindowInsets.statusBarsIgnoringVisibility	狀態列顯示時的插邊。如果狀態列因進入沉浸式全螢幕模式而隱藏，則主要狀態列插邊會是空白，但這些插邊不會是空白。
WindowInsets.navigationBars	描述導覽列的插邊。這些是裝置左側、右側或底部的系統 UI 列，用於描述工作列或導覽圖示。這些設定可在執行階段變更，具體取決於使用者偏好的導覽方式，以及與工作列的互動。
WindowInsets.navigationBarsIgnoringVisibility	導覽列顯示時的內嵌。如果導覽列隱藏 (因為進入沉浸式全螢幕模式)，則主要導覽列插邊會是空白，但這些插邊不會是空白。
WindowInsets.captionBar	如果位於任意形式視窗中，則為說明系統 UI 視窗裝飾的插邊，例如頂端標題列。
WindowInsets.captionBarIgnoringVisibility	字幕列顯示時的內嵌。如果隱藏字幕列，則主要字幕列插邊會是空白，但這些插邊不會是空白。
WindowInsets.systemBars	系統資訊列插邊的聯集，包括狀態列、導覽列和說明文字。
WindowInsets.systemBarsIgnoringVisibility	系統資訊列顯示時的系統資訊列內嵌。如果系統資訊列隱藏 (因為進入沉浸式全螢幕模式)，則主要系統資訊列插邊會是空白，但這些插邊不會是空白。
WindowInsets.ime	說明螢幕鍵盤在底部占用的空間量。
WindowInsets.imeAnimationSource	插邊，說明螢幕鍵盤在目前鍵盤動畫「之前」占用的空間量。
WindowInsets.imeAnimationTarget	插邊，說明螢幕鍵盤在目前鍵盤動畫「之後」將占用的空間量。
WindowInsets.tappableElement	一種插邊類型，可描述導覽 UI 的詳細資訊，提供系統 (而非應用程式) 處理「輕觸」的空間量。對於具有手勢操作功能的透明導覽列，某些應用程式元素可透過系統導覽 UI 輕觸。
WindowInsets.tappableElementIgnoringVisibility	可輕觸元素在顯示時的內嵌。如果可輕觸元素隱藏 (因為進入沉浸式全螢幕模式)，則主要可輕觸元素插邊會是空白，但這些插邊不會是空白。
WindowInsets.systemGestures	插邊代表系統會攔截手勢進行導覽的插邊數量。應用程式可以使用 Modifier.systemGestureExclusion，手動指定處理少量這類手勢。
WindowInsets.mandatorySystemGestures	一律由系統處理的系統手勢子集，無法使用 Modifier.systemGestureExclusion 停用。
WindowInsets.displayCutout	插邊代表避免與螢幕凹口 (凹口或針孔) 重疊所需的間距。
WindowInsets.waterfall	代表瀑布螢幕曲面區域的插邊。瀑布式螢幕的螢幕邊緣有弧形區域，螢幕會沿著裝置兩側包覆。

這些類型可歸納為三種「安全」插邊類型，可確保內容不會遭到遮蓋：

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

這些「安全」插邊類型會根據基礎平台插邊，以不同方式保護內容：

• 使用 WindowInsets.safeDrawing 保護不應在任何系統 UI 下方繪製的內容。這是最常見的插邊用途：避免繪製遭系統 UI 遮蔽 (部分或完全) 的內容。
• 使用 WindowInsets.safeGestures 透過手勢保護內容。這樣可以避免系統手勢與應用程式手勢 (例如底部功能表、輪轉介面或遊戲中的手勢) 衝突。
• 請使用 WindowInsets.safeContent 做為 WindowInsets.safeDrawing 和 WindowInsets.safeGestures 的組合，確保內容不會在視覺和手勢上重疊。