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

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

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

다음 표에서는 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와 함께 사용합니다.

이 기능이 지원되는지 확인하려면 Activity.onCreate와 같이 WebView 객체를 구성할 때마다 다음 코드 줄을 추가합니다.

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가 웹페이지의 색상을 자동으로 반전합니다. 사용자 에이전트를 어둡게 하는 경우 @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는 태그가 생략된 경우에도 항상 미디어 쿼리를 적용합니다.

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

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: '사용자 에이전트 어둡게 하기'라고 하는 WebView는 웹페이지를 어둡게 하는 것을 무시하고 자동 어둡게 하기를 적용합니다.

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

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