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 設定視窗屬性，藉此套用 View 終止說明文件中描述的相同設定。不過，系統會將凹口模式套用至整個活動，且無法根據個別可組合項控制。

如要遵循特定可組合項中的螢幕凹口，而不遵循其他可組合項，請使用 WindowInset.displayCutout。這個 API 可讓您視需要存取截斷資訊。

最佳做法

使用螢幕凹口時，請考量下列事項：

• 注意 UI 重要元素的位置。不要讓提示區域遮蓋任何重要文字、控制項或其他資訊。
• 請勿在凹口區域放置或擴充任何需要觸控辨識的互動元素。觸控敏感度可能會較低。
• 遵循無邊框指南時，safeDrawing / safeContent 插邊中會包含截斷資訊。
• 請盡可能使用 Modifier.windowInsetsPadding(WindowInsets.safeDrawing) 決定要套用至內容的適當邊框間距。請避免將狀態列高度硬式編碼，因為這樣可能會導致內容重疊或截斷。

利用凹口測試內容的呈現效果

請務必測試應用程式的所有畫面和體驗。如果可以，請針對採用不同類型凹口的裝置進行測試。如果裝置沒有發生中斷情形，您可以在任何搭載 Android 9 以上版本的裝置或模擬器上，模擬常見的凹口設定，步驟如下：

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

   

   圖 3. 使用開發人員選項測試內容轉譯方式。