實作深色主題

試用 Compose
Jetpack Compose 是 Android 推薦的 UI 工具包。瞭解如何在 Compose 中使用主題設定。
色彩配置 - Material Design 3 →

圖 1. 深色主題。

深色主題適用於 Android 10 (API 級別 29) 及以上版本。它的優點如下：

  • 視裝置的螢幕技術而定，可大幅減少耗電量。
  • 可改善低視能及對明亮光線敏感使用者的可視性。
  • 能讓你在低光源環境中更輕鬆地使用裝置。

深色主題適用於在裝置上執行的 Android 系統 UI 和應用程式。

在 Android 10 以上版本中啟用深色主題的方式有三種：

  • 依序前往「Settings」>「Display」>「Theme」，使用系統設定即可啟用深色主題。
  • 如果已啟用，請用「快速設定」方塊從通知匣中切換主題。
  • 如果是 Pixel 裝置，只要啟用省電模式，即可同時啟用深色主題。其他裝置可能不支援這項行為。

如要瞭解如何使用 WebView 元件將深色主題套用至網路內容，請參閱「在 WebView 中調暗網頁內容」。

在應用程式中支援深色主題

如要支援深色主題，請設定應用程式主題 (通常位於 res/values/styles.xml 中)，使其繼承 DayNight 主題：

<style name="AppTheme" parent="Theme.AppCompat.DayNight">

您也可以使用 Material 元件深色主題：

<style name="AppTheme" parent="Theme.MaterialComponents.DayNight">

這會將應用程式的主要主題與系統控制的夜間模式旗標繫結，並在啟用時為應用程式提供預設的深色主題。

主題與樣式

避免使用適合淺色主題的硬式編碼顏色或圖示。請改用主題屬性或夜間合格資源。

深色主題中最重要的兩個主題屬性如下：

  • ?android:attr/textColorPrimary：一般用途文字顏色。在淺色主題中接近黑色，在深色主題中則接近白色。具有停用狀態。
  • ?attr/colorControlNormal：一般用途圖示顏色。具有停用狀態。

建議您使用質感設計元件，因為其顏色主題設定系統 (例如主題屬性 ?attr/colorSurface 和 ?attr/colorOnSurface) 可讓您輕鬆存取合適的顏色。您可以在主題中自訂這些屬性。

變更應用程式內主題

您可以讓使用者在應用程式執行期間變更應用程式主題。以下是建議選項：

  • 和緩
  • 深色
  • 系統預設 (建議的預設選項)

這些選項會直接對應至 AppCompat.DayNight 模式：

如要切換主題，請按照下列步驟操作：

強制使用深色模式

Android 10 提供「強制使用深色模式」，開發人員不必明確設定 DayNight 主題，即可快速實作深色主題。

「強制使用深色模式」會分析淺色主題應用程式的每個檢視畫面，並在繪圖至螢幕前自動套用深色主題。您可以搭配使用「強制使用深色模式」和原生實作項目，縮短實作深色主題所需的時間。

應用程式必須在活動主題中設定 android:forceDarkAllowed="true"，選擇啟用「強制使用深色模式」。這個屬性會在所有系統和 AndroidX 提供的淺色主題上設定，例如 Theme.Material.Light。使用「強制使用深色模式」時，請仔細檢查應用程式，然後視需要排除檢視畫面。

如果您的應用程式使用深色主題 (例如 Theme.Material)，系統不會套用「強制使用深色模式」。同理，如果應用程式的主題繼承自 DayNight 主題，由於自動主題切換功能，系統不會套用「強制使用深色模式」。

在檢視畫面上停用「強制使用深色模式」

可以使用 android:forceDarkAllowed 版面配置屬性或 setForceDarkAllowed()，來控管特定檢視畫面上的「強制使用深色模式」設定。

網路內容

如要瞭解如何在網路內容中使用深色主題，請參閱「在 WebView 中調暗網頁內容」。如需套用至 WebView 的深色主題範例，請參閱 GitHub 上的 WebView 示範。

最佳做法

下列各節說明實作深色主題的最佳做法。

通知和小工具

對於您在裝置上顯示但未直接控制的 UI 介面，請確保您使用的任何檢視畫面皆符合主應用程式的主題。其中兩個例子為通知和啟動器小工具。

通知

使用系統提供的通知範本，例如 MessagingStyle。這表示系統會負責套用正確的檢視樣式。

小工具與自訂通知檢視畫面

如果是啟動器小工具，或應用程式使用自訂通知內容檢視畫面，請在淺色和深色主題上測試內容。

應留意的常見陷阱如下：

  • 假設背景顏色一律為淺色。
  • 硬式編碼文字顏色。
  • 使用預設文字顏色時設定硬式編碼背景顏色。
  • 使用靜態色彩的可繪圖示。

在這些情況下，請使用適當的主題屬性，而非硬式編碼顏色。

啟動畫面

如果您的應用程式有自訂啟動畫面，可能需要加以修改，以便反映所選主題。

請移除所有硬式編碼顏色，例如設為白色的背景顏色。請改用 ?android:attr/colorBackground 佈景主題屬性。

設定變更

當應用程式的主題透過系統設定或 AppCompat 變更時，會觸發 uiMode 設定變更。也就是說，系統會自動重新建立活動。

在某些情況下，您可能會希望應用程式處理設定變更。例如，由於正在播放影片，因此您想要延遲設定變更。

應用程式可以宣告每個 Activity 皆可處理 uiMode 設定變更，以處理深色主題的實作：

<activity
    android:name=".MyActivity"
    android:configChanges="uiMode" />

當 Activity 宣告會處理設定變更時，當主題變更時，系統會呼叫其 onConfigurationChanged() 方法。

如要查看目前主題，應用程式可以執行下列程式碼：

Kotlin

val currentNightMode = configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
when (currentNightMode) {
    Configuration.UI_MODE_NIGHT_NO -> {} // Night mode is not active, we're using the light theme.
    Configuration.UI_MODE_NIGHT_YES -> {} // Night mode is active, we're using dark theme.
}

Java

int currentNightMode = configuration.uiMode & Configuration.UI_MODE_NIGHT_MASK;
switch (currentNightMode) {
    case Configuration.UI_MODE_NIGHT_NO:
        // Night mode is not active, we're using the light theme
        break;
    case Configuration.UI_MODE_NIGHT_YES:
        // Night mode is active, we're using dark theme
        break;
}