在 WebView 中調暗網頁內容

在 Android 10 以上版本中，應用程式支援 深色主題並自動變更 根據系統主題切換淺色和深色主題的應用程式主題。如要比對 目前的應用程式主題，以及 WebView 中的網頁內容 還可以使用淺色、深色或預設樣式。

WebView 的行為會與 prefers-color-scheme敬上 和 color-scheme。 網路標準只要您所撰寫的網路內容能 要在 WebView 中顯示您的應用程式，您必須為每個應用程式定義深色主題 網站 實作 prefers-color-scheme，讓 WebView 能夠比對網頁的 加入三個主題

下表說明 WebView 如何在應用程式中轉譯網頁內容。 視網頁內容的樣式和應用程式條件而定：

應用程式條件 使用「prefers-color-scheme」的網路內容 未使用 prefers-color-scheme 的網路內容
應用程式使用以下主題的淺色主題： isLightTheme 設為「true」或未設定 WebView 會以淺色主題轉譯內容 內容作者定義。 WebView 會使用由 內容作者。
應用程式正在使用 強制使用深色模式 到 系統會運用演算法套用深色主題 加入 App Engine 應用程式 WebView 會使用深色主題來呈現內容 內容作者定義。 如果內容作者允許，WebView 會以 使用演算法產生的深色主題。
應用程式使用深色主題，且： isLightTheme 設為 false，且應用程式「不允許」演算法 WebView 的亮度提高 WebView 會使用深色主題來呈現內容 內容作者定義。 WebView 會使用由 內容作者。
應用程式使用深色主題，且： isLightTheme 設為 false，且應用程式允許 WebView 的演算法調暗。 WebView 會使用深色主題來呈現內容 內容作者定義。 如果內容作者允許，WebView 會以 使用演算法產生的深色主題。

內容作者樣式設定

應用程式的 isLightTheme 屬性 指出應用程式的主題為淺色或深色。WebView 一律會設定 prefers-color-scheme (資料來源：isLightTheme)。如果 isLightTheme 是 true 或是未指定，則 prefers-color-scheme 為 light；否則就是 dark。

也就是說，如果網頁內容使用 prefers-color-scheme 和 作者允許，這是由內容作者定義的淺色或深色主題 會自動套用到網頁內容，以符合應用程式的主題。

演算法調暗

綜合說明網路內容不使用 prefers-color-scheme、 您的應用程式可允許 WebView 視需要透過演算法套用暗點 視為單一主題的網頁內容。

如果您的應用程式目前使用應用程式層級 強制使用深色的演算法 為應用程式套用深色主題，請參閱以下章節，瞭解如何 現在可以使用「強制使用深色模式」模式，針對網路內容進行演算法調暗。

如果您的應用程式未使用「強制使用深色模式」，應如何指定要允許的時機 WebView 的演算法調暗功能取決於應用程式的 目標 API 級別。 請參閱以下章節，瞭解指定 Android 13 以上版本的應用程式和 指定 Android 12 以下版本的應用程式。

允許使用「強制使用深色模式」模式對網路內容進行演算法調暗

如果您的應用程式目前使用應用程式層級 強制使用深色模式，適用 WebView 在符合下列條件的情況下，系統就會調暗網頁內容：

  • WebView 及其父項元素允許「強制使用深色模式」，
  • 目前的活動主題會標示為淺色， isLightTheme已設為 true。
  • 網路內容作者尚未明確停用調暗功能。
  • 目標為 Android 13 (API 級別 33) 以上版本的應用程式，其網路內容 並未使用 prefers-color-scheme。
  • 如果應用程式指定 Android 12 (API 級別 32) 以下版本：該應用程式已設定 WebView 的 forceDarkMode 設定 到 FORCE_DARK_AUTO。 並將「強制使用深色模式」策略設為 DARK_STRATEGY_USER_AGENT_DARKENING_ONLY。

WebView 及其所有父項皆可透過 View.setForceDarkAllowed()。 預設值取自setForceDarkAllowed() Android 主題，必須也設為 true。

強制使用深色模式的主要目的是確保應用程式的回溯相容性 請勿提供自己的深色主題， 如果您的應用程式使用「強制使用深色模式」，建議您 新增對深色主題的支援。

允許使用演算法調暗 (指定 Android 13 以上版本的應用程式)

非使用應用程式層級「強制使用深色模式」的應用程式，且指定 Android 13 (API 級別) 為目標 33) 以上版本，請使用 AndroidX setAlgorithmicDarkeningAllowed()敬上 方法並傳入 true，以指定 WebView 應允許演算法 調暗。這個方法與先前的 Android 裝置具有回溯相容性 版本。

並在符合下列條件時，WebView 套用演算法調暗：

  • 網頁內容未使用 prefers-color-scheme。
  • 網路內容作者尚未明確停用調暗功能。

允許使用演算法調暗 (指定 Android 12 以下版本的應用程式)

非使用應用程式層級「強制使用深色模式」的應用程式，且指定 Android 12 (API 級別) 為目標 32) 以下，請使用 FORCE_DARK_ON敬上 以便讓演算法調暗

搭配使用 FORCE_DARK_ON 與 FORCE_DARK_OFF 如果您的應用程式有自己的方式可以切換淺色和深色主題， 例如 UI 中的可切換元素，或自動以時間為準選取選項

如要檢查系統是否支援這項功能，請加入以下這行程式碼 任何設定 WebView 物件的位置，例如 Activity.onCreate 中：

Kotlin

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    WebSettingsCompat.setForceDark(...)
}

Java

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    WebSettingsCompat.setForceDark(...);
}

如果應用程式需要偵測系統偏好設定的變更，應用程式應 明確監聽主題變更，並將這些變更套用至 WebView FORCE_DARK_ON 和 FORCE_DARK_OFF 狀態。

以下程式碼片段說明如何變更主題格式：

Kotlin

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    when (resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) {
        Configuration.UI_MODE_NIGHT_YES -> {
            WebSettingsCompat.setForceDark(myWebView.settings, FORCE_DARK_ON)
        }
        Configuration.UI_MODE_NIGHT_NO, Configuration.UI_MODE_NIGHT_UNDEFINED -> {
            WebSettingsCompat.setForceDark(myWebView.settings, FORCE_DARK_OFF)
        }
        else -> {
            //
        }
    }
}

Java

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    switch (getResources().getConfiguration().uiMode & Configuration.UI_MODE_NIGHT_MASK) {
        case Configuration.UI_MODE_NIGHT_YES:
            WebSettingsCompat.setForceDark(myWebView.getSettings(), FORCE_DARK_ON);
            break;
        case Configuration.UI_MODE_NIGHT_NO:
        case Configuration.UI_MODE_NIGHT_UNDEFINED:
            WebSettingsCompat.setForceDark(myWebView.getSettings(), FORCE_DARK_OFF);
            break;
    }
}

自訂深色主題處理方式

您也可以使用 ForceDarkStrategy API ，以控制對特定 WebView 套用調暗的方式。這個 API 只有在強制深色模式設為 FORCE_DARK_ON 或 FORCE_DARK_AUTO 時，才適用。

透過 API，應用程式可以使用網頁主題調暗或使用者代理程式 調暗：

  • 網路主題調暗：網頁開發人員可能適用 @media (prefers-color-scheme: dark) 可用於控制 深色模式WebView 會根據這些設定顯示內容。如要進一步瞭解 以網路主題變暗，請參閱 規格。
  • User-agent 調暗：WebView 會自動反轉網頁的顏色 頁面。如果使用使用者代理程式調暗， @media (prefers-color-scheme: dark) 查詢評估為 false。

如要選擇其中一種策略，請使用下列 API：

Kotlin

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) {
    WebSettingsCompat.setForceDarkStrategy(...)
}

Java

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) {
    WebSettingsCompat.setForceDarkStrategy(...);
}

支援的策略選項如下：

  • DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING： 這是預設選項。雖然大多數瀏覽器會將 <meta name="color-scheme" content="dark light"> 標記為選用標記，Android WebView 的預設模式需要中繼標記來遵循網頁的 prefers-color-scheme 媒體查詢。您可以透過以下裝置使用 WebView： DARK_STRATEGY_WEB_THEME_DARKENING_ONLY 模式，此時 WebView 一律會套用媒體查詢，即使標記 省略。

    不過，我們建議網頁程式開發人員 在網站上加入 <meta name="color-scheme" content="dark light"> 標記， 使用 預設設定。

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY： 稱之為「使用者代理程式調暗」WebView 會忽略任何降低網頁變暗情形， 套用自動調暗功能

如果應用程式會顯示您透過 prefers-color-scheme 個媒體查詢，建議採用 DARK_STRATEGY_WEB_THEME_DARKENING_ONLY 確保 WebView 使用自訂主題。

如需套用深色主題的範例，請參閱 GitHub 上的 WebView 示範