Compose 中的凹口

螢幕凹口是指部分裝置延伸至顯示器的區域 途徑。不但能享受無邊框體驗，同時也能為 重要的感應器 (須位於裝置正面)

Android 支援搭載 Android 9 (API 級別 28) 以上版本的裝置的螢幕切口。不過，裝置製造商也支援 搭載 Android 8.1 以下版本的裝置。

本頁說明如何在 Compose 中實作對有缺口裝置的支援，包括如何使用缺口區域，也就是含有缺口的顯示面上的邊到邊矩形。

預設大小寫

根據預設，視窗內嵌資訊會納入螢幕缺口。因此，當您追蹤內容時，您的應用程式不會在螢幕凹口區域繪製 本指南，說明如何打造無邊框應用程式

舉例來說，如果您使用 Modifier.windowInsetsPadding(WindowInsets.safeContent) 或 Modifier.windowInsetsPadding(WindowInsets.safeDrawing)，應用程式就不會自動在放置裁剪區的區域中繪製。WindowInsets.safeContent 和 WindowInsets.safeDrawing 都包含螢幕裁剪資訊，且不會在裝置裁剪處繪製。

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    WindowCompat.setDecorFitsSystemWindows(window, false)

    setContent {
        Box(Modifier.windowInsetsPadding(WindowInsets.safeContent)) {
            // Any composable inside here will avoid drawing behind cutouts
        }
    }
}
CutoutSnippets.kt

如要進一步自訂這項行為，您需處理凹口資訊 你自己。

手動處理裁剪資訊

您可以透過下列任一方式處理裁剪區域：

• 使用 WindowInsets.displayCutout

• 使用 android:windowLayoutInDisplayCutoutMode 在主題資訊清單中設定

• 使用 window.attributes.layoutInDisplayCutoutMode，透過程式輔助方式在 Window 上設定選項

• 使用 LocalView.current.rootWindowInsets.displayCutout 存取裁剪 Path 物件

如果是 Compose，建議您將 windowLayoutInDisplayCutoutMode 設為 在整體主題中default，然後採用 WindowInsets.displayCutout 處理可組合函式中的插邊：

Canvas(modifier = Modifier.fillMaxSize().windowInsetsPadding(WindowInsets.displayCutout)) {
    drawRect(Color.Red, style = Stroke(2.dp.toPx()))
}
CutoutSnippets.kt

這個方法可讓您在必要時遵循 displayCutout 邊框間距。 或忽略該指令碼

您也可以套用與 Views Cutout 相同的設定 說明文件 活動主題 android:windowLayoutInDisplayCutoutMode 變更為其他主題 選項或使用視窗屬性來設定視窗屬性 window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT。不過，裁剪模式會套用至整個活動，無法針對個別可組合項進行控制。

如要讓特定可組合項遵循螢幕裁切，而其他可組合項則不遵循，請使用 WindowInset.displayCutout。這個 API 可讓你 接收必要的資訊

最佳做法

處理螢幕凹口時，請考量以下事項：

• 留意放置 UI 的重要元素。切勿讓 截斷區域會遮住所有重要的文字、控制項或其他資訊。
• 請勿放置或擴充任何需要微調的互動元素 確實辨識在凹口區域在 凹口區域
• 在遵循邊到邊指引時，會在 safeDrawing/safeContent 內嵌項目中加入裁切資訊。
• 盡可能使用 Modifier.windowInsetsPadding(WindowInsets.safeDrawing) 判斷要為內容套用的適當邊框間距。避開 以硬式編碼的方式寫入狀態列高度，以免重疊 內容。

使用凹口測試內容的顯示方式

請務必測試應用程式的所有畫面和體驗。在搭載以下作業系統的裝置上測試： 不同類型的凹口類型如果你的裝置沒有搭載 您可以在任何裝置或模擬器上模擬常見的凹口設定 (執行 Android 9 以上版本)，請按照下列步驟操作：

1. 啟用「開發人員選項」。
2. 在「開發人員選項」畫面中，向下捲動至「Drawing」部分，然後選取「Simulate a display with a cutout」。
3. 選取凹口類型。