Compose 中的凹口

「螢幕凹口」是部分裝置延伸至顯示介面的區域。這種做法可以提供無邊框體驗，同時為裝置前方的重要感應器提供空間。

直向模式下的裁剪範例
圖 1. 直向模式的凹口範例
橫向模式下的剪裁範例
圖 2. 橫向模式下的剪裁範例

在搭載 Android 9 (API 級別 28) 以上版本的裝置上，Android 支援螢幕凹口。不過，在搭載 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

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

手動處理凹口資訊

您可以透過下列方式處理凹口：

針對 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 Cutout 說明文件中所述的設定。但是，凹口模式隨後會套用到整個活動，您無法按個別可組合項控制。

如要讓特定可組合項中的螢幕凹口顯示，但在其他可組合項中保持不變，請使用 WindowInset.displayCutout。這個 API 可讓您在必要時存取凹口資訊。

最佳做法

使用螢幕凹口時，請考慮以下幾點：

  • 留意放置 UI 的重要元素。請勿讓裁剪區域遮蓋任何重要的文字、控制項或其他資訊。
  • 請勿在凹口區域放置或擴充任何需要精細辨識的互動元素，凹口區域的觸控敏感度可能較低。
  • 按照無邊框指示執行時，凹口資訊會包含在 safeDrawing / safeContent 插邊中。
  • 請盡可能使用 Modifier.windowInsetsPadding(WindowInsets.safeDrawing) 來判斷要套用至內容的適當邊框間距。請避免對狀態列高度進行硬式編碼，以免內容重疊或遭到截斷。

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

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

  1. 啟用開發人員選項。
  2. 在「Developer options」畫面中，向下捲動至「Drawing」部分，然後選取「Simulate a display withCutout」。
  3. 選取凹口類型。
    在模擬器中模擬螢幕凹口
    圖 3. 使用「開發人員選項」測試內容的算繪方式。