![](https://developer.android.com/static/images/guide/topics/ui/look-and-feel/darktheme.png?authuser=0000&hl=zh-tw)
深色主題適用於 Android 10 (API 級別 29) 及以上版本。這個元件具有 以下優點:
- 可大幅減少耗電量 (視裝置而定) 螢幕技術。
- 可改善低視能及對明亮光線敏感使用者的可視性。
- 能讓你在低光源環境中更輕鬆地使用裝置。
深色主題適用於在裝置上執行的 Android 系統 UI 和應用程式。
在 Android 10 以上版本中啟用深色主題的方式有三種:
- 使用系統設定:依序前往「設定」>顯示 >主題: 啟用深色主題。
- 您可以使用「快速設定」方塊,從通知匣中切換主題 如已啟用
- 在 Pixel 裝置上啟用省電模式後,就能同時啟用深色主題 讓應用程式從可以最快做出回應的位置 回應使用者要求其他裝置可能不支援這項行為。
如要瞭解如何使用 WebView 元件將深色主題套用至網路內容,請參閱「在 WebView 中調暗網頁內容」。
在應用程式中支援深色主題
如要支援深色主題,請設定應用程式主題 (通常位於
res/values/styles.xml
—從 DayNight
主題繼承:
<style name="AppTheme" parent="Theme.AppCompat.DayNight">
您也可以使用 Material Design 元件深色 主題:
<style name="AppTheme" parent="Theme.MaterialComponents.DayNight">
這會將應用程式的主要主題與系統控制的夜間模式旗標結合 啟用後,系統會為應用程式提供預設的深色主題。
主題與樣式
避免使用適合淺色主題的硬式編碼顏色或圖示。使用 主題屬性或夜間合格資源。
深色主題中最重要的兩個主題屬性如下:
?android:attr/textColorPrimary
:一般用途文字顏色。是 在淺色主題中接近黑色,在深色主題中則接近白色。具有停用狀態。?attr/colorControlNormal
:一般用途圖示顏色。具有停用狀態。
建議您使用 Material Design
元件,因為其顏色主題設定
例如主題系統
?attr/colorSurface
和 ?attr/colorOnSurface
屬性,可讓您輕鬆存取
挑選合適的顏色。您可以在主題中自訂這些屬性。
變更應用程式內主題
您可以讓使用者在應用程式執行期間變更應用程式主題。下列 建議選項:
- 淺色
- 深色
- 系統預設 (建議的預設選項)
這些選項會直接對應至 AppCompat.DayNight
模式:
淺色:
MODE_NIGHT_NO
。深色:
MODE_NIGHT_YES
。系統預設:
MODE_NIGHT_FOLLOW_SYSTEM
。
如要切換主題,請按照下列步驟操作:
在 API 級別 31 以上版本中,請使用
UiModeManager#setApplicationNightMode
敬上 ,讓系統瞭解您的應用程式執行哪個主題。系統才能比對 顯示主題。在 API 級別 30 以下版本中,請使用
AppCompatDelegate.setDefaultNightMode()
敬上 即可切換主題
強制使用深色模式
Android 10 提供強制使用深色功能,開發人員可以
快速實作深色主題,而無須明確設定 DayNight
主題。
「強制使用深色模式」會分析淺色主題應用程式的每個檢視畫面,並套用深色主題 並在繪製到螢幕前自動顯示你可以使用「強制使用深色模式」 原生實作系統,可縮短導入 主題。
應用程式必須在以下位置設定「強制使用深色模式」:android:forceDarkAllowed="true"
活動的主題。系統會在所有系統上設定這個屬性
AndroidX 提供的淺色主題,例如 Theme.Material.Light
。使用方法
「強制使用深色模式」:對應用程式進行全面測試,並視需要排除檢視畫面。
如果應用程式使用深色主題 (例如 Theme.Material
),則不會使用「強制使用深色模式」
已套用。同樣地,如果應用程式主題沿用 DayNight
主題,Force
自動主題切換功能並未套用深色。
在檢視畫面上停用「強制使用深色模式」
可以使用「強制使用深色模式」設定,控制特定檢視畫面
android:forceDarkAllowed
版面配置屬性,或含有
setForceDarkAllowed()
。
網路內容
如要瞭解如何在網路內容中使用深色主題,請參閱「調暗網路亮度」 WebView 中的內容深色主題範例 每個 WebView 都會套用這個 API,請參閱 WebView 示範 GitHub ,直接在 Google Cloud 控制台實際操作。
最佳做法
下列各節說明實作深色主題的最佳做法。
通知和小工具
對於您在裝置上顯示但未直接控制的 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; }