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 邊框間距，或在不需要時忽略。

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

如要讓特定可組合項遵循螢幕裁切，而其他可組合項則不遵循，請使用 WindowInset.displayCutout。這個 API 可讓您在需要時存取裁切資訊。

最佳做法

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

• 請留意使用者介面中關鍵元素的位置。請勿讓裁切區域遮蓋任何重要文字、控制項或其他資訊。
• 請勿將需要精細觸控辨識的互動元素放入裁剪區域或延伸至該區域。在挖孔區域的觸控敏感度可能較低。
• 在遵循邊緣到邊緣指引時，會在 safeDrawing / safeContent 內嵌項目中加入裁切資訊。
• 盡可能使用 Modifier.windowInsetsPadding(WindowInsets.safeDrawing) 判斷要為內容套用的適當邊框間距。請勿硬式編碼狀態列高度，否則可能會導致內容重疊或遭到截斷。

測試內容在裁剪區塊中的顯示方式

請務必測試應用程式的所有畫面和體驗。盡可能在不同類型的裝置上進行測試。如果您沒有裝置邊框，您可以按照下列步驟，在任何搭載 Android 9 以上版本的裝置或模擬器上模擬常見的邊框設定：

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