WebView에서 웹 콘텐츠 어둡게 하기

Android 10 이상에서는 앱이 어두운 테마를 지원하고 시스템 테마에 따라 밝은 테마와 어두운 테마 앱 간에 자동으로 변경할 수 있습니다. 현재 앱 테마와 일치하도록 WebView의 웹 콘텐츠에서 밝은 스타일, 어두운 스타일 또는 기본 스타일을 사용할 수도 있습니다.

WebView의 동작은 prefers-color-scheme 및 color-scheme 웹 표준과 상호 운용됩니다. 가능하면 앱에서 WebView에 표시할 웹 콘텐츠를 작성하는 경우 웹사이트의 어두운 테마를 정의하고 WebView가 웹 콘텐츠의 테마를 앱의 테마에 일치시킬 수 있도록 prefers-color-scheme를 구현해야 합니다.

다음 표에서는 웹 콘텐츠의 스타일과 앱 조건에 따라 WebView가 앱에서 웹 콘텐츠를 렌더링하는 방법을 설명합니다.

콘텐츠 작성자 스타일 지정

앱의 isLightTheme 속성은 앱의 테마가 밝은 테마인지 어두운 테마인지 나타냅니다. WebView는 항상 isLightTheme에 따라 prefers-color-scheme을 설정합니다. 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()를 사용하여 강제 어둡게 표시를 허용할 수 있습니다. 기본값은 Android 테마의 setForceDarkAllowed() 속성에서 가져옵니다. 이 속성도 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를 사용하여 알고리즘 방식의 어둡게 하기를 허용합니다.

앱에서 UI의 전환 가능한 요소나 자동 시간 기반 선택과 같이 밝은 테마와 어두운 테마 간에 전환하는 자체 메서드를 제공하는 경우 FORCE_DARK_ON를 FORCE_DARK_OFF와 함께 사용합니다.

이 기능이 지원되는지 확인하려면 WebView 객체를 구성하는 모든 위치(예: Activity.onCreate)에 다음 코드 줄을 추가합니다.

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

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

앱이 시스템 환경설정 변경 감지를 사용하는 경우 앱은 테마 변경사항을 명시적으로 수신 대기하고 FORCE_DARK_ON 및 FORCE_DARK_OFF 상태를 사용하여 WebView에 적용해야 합니다.

다음 코드 스니펫은 테마 형식을 변경하는 방법을 보여줍니다.

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 -> {
            //
        }
    }
}

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;
    }
}

어두운 테마 처리 맞춤설정

AndroidX의 ForceDarkStrategy API를 사용하여 지정된 WebView에 어둡게 처리가 적용되는 방식을 제어할 수도 있습니다. 이 API는 강제로 어둡게 설정을 FORCE_DARK_ON 또는 FORCE_DARK_AUTO로 설정한 경우에만 적용됩니다.

이 API를 사용하면 앱에서 웹 테마 어둡게 하기 또는 사용자 에이전트 어둡게 하기를 사용할 수 있습니다.

• 웹 테마 어둡게 하기: 웹 개발자는 @media (prefers-color-scheme: dark)를 적용하여 어두운 모드에서 웹페이지 모양을 제어할 수 있습니다. WebView는 이러한 설정에 따라 콘텐츠를 렌더링합니다. 웹 테마 어둡게 하기에 관한 자세한 내용은 사양을 참고하세요.
• 사용자 에이전트 어둡게 하기: WebView가 웹페이지의 색상을 자동으로 반전시킵니다. user-agent 어둡게 처리를 사용하면 @media (prefers-color-scheme: dark) 쿼리가 false로 평가됩니다.

두 전략 중에서 선택하려면 다음 API를 사용하세요.

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

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는 항상 미디어 쿼리를 적용합니다.

  그러나 웹 개발자는 기본 구성으로 WebView에서 콘텐츠가 올바르게 렌더링되도록 웹사이트에 <meta name="color-scheme" content="dark light"> 태그를 추가하는 것이 좋습니다.

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: 'user-agent 어둡게 하기'라고 하는 WebView는 웹페이지 어둡게 하기를 무시하고 자동 어둡게 하기를 적용합니다.

앱에서 prefers-color-scheme 미디어 쿼리로 맞춤설정한 퍼스트 파티 웹 콘텐츠를 표시하는 경우 WebView에서 맞춤 테마를 사용하도록 DARK_STRATEGY_WEB_THEME_DARKENING_ONLY 설정하는 것이 좋습니다.

적용된 어두운 테마의 예는 GitHub의 WebView 데모를 참고하세요.