Compose 中的凹口

螢幕凹口是指某些裝置上延伸至螢幕表面的區域。這可提供從邊到邊的體驗，同時在裝置前端留出空間放置重要感應器。

圖 1. 直向模式的凹口範例

圖 2. 橫向模式下的剪裁範例

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 設定視窗屬性，以便套用 Views 裁剪功能說明文件所述的相同設定。不過，裁剪模式會套用至整個活動，無法針對個別可組合項進行控制。

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

最佳做法

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

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

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

請務必測試應用程式的所有螢幕和體驗。請盡可能使用不同類型的凹口裝置進行測試。如果裝置沒有凹口，可以在搭載 Android 9 以上版本的裝置或模擬器上，模擬常見的凹口設定，步驟如下：

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

   

   圖 3. 使用開發人員選項測試內容的顯示方式。