關於視窗插邊

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

在 Android 14 (API 級別 34) 以下版本中，應用程式的 UI 預設不會在系統列下方繪製，也不會顯示缺口。

在 Android 15 (API 級別 35) 以上版本中，如果應用程式指定 SDK 35 以上版本，應用程式會在系統列下方繪製並顯示螢幕缺口。這可提供更流暢的使用者體驗，並讓應用程式充分運用可用的視窗空間。

在系統 UI 後方顯示內容稱為「無邊框」。您將在這頁面中瞭解不同類型的內嵌、如何進行邊到邊處理，以及如何使用內嵌 API 為 UI 製作動畫，並確保應用程式內容不會遭系統 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 的組合，確保內容不會有視覺重疊和手勢重疊。

為您推薦

• 注意：系統會在 JavaScript 關閉時顯示連結文字
• Material Design 元件和版面配置
• 將 CoordinatorLayout 遷移至 Compose
• 其他考量