ปรับเนื้อหาเว็บให้มืดใน 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 จะแสดงผลเนื้อหาด้วยการจัดรูปแบบเริ่มต้นที่กำหนดโดย ผู้เขียนเนื้อหา
แอปกำลังใช้ บังคับใช้โหมดมืด ถึง ใช้ธีมมืดตามอัลกอริทึม ไปยังแอป 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 เพื่อใช้อัลกอริทึม ธีมของเนื้อหาเว็บที่แสดงผล

หากแอปกำลังใช้ระดับแอป บังคับใช้โหมดมืดโดยใช้อัลกอริทึม ใช้ธีมมืดกับแอป โปรดดูส่วนต่อไปนี้ซึ่งอธิบายถึงวิธีการ อนุญาตการปรับให้มืดตามอัลกอริทึมสำหรับเนื้อหาเว็บด้วย Force Dark

หากแอปไม่ได้ใช้ฟีเจอร์บังคับใช้โหมดมืด วิธีที่แอประบุว่าควรอนุญาตเมื่อใด การปรับให้มืดลงแบบอัลกอริทึมใน WebView จะขึ้นอยู่กับ ระดับ API เป้าหมาย ดูส่วนต่อไปนี้สำหรับแอปที่กำหนดเป้าหมายเป็น Android 13 ขึ้นไป และ ดูรายละเอียดแอปที่กำหนดเป้าหมายเป็น Android 12 หรือต่ำกว่า

อนุญาตการปรับให้มืดตามอัลกอริทึมสำหรับเนื้อหาเว็บโดยใช้ฟีเจอร์บังคับมืด

หากแอปกำลังใช้ระดับแอป บังคับใช้ธีมมืด ใช้ WebView การปรับให้มืดลงตามอัลกอริทึมสำหรับเนื้อหาเว็บหากเป็นไปตามเงื่อนไขต่อไปนี้

  • WebView และองค์ประกอบระดับบนสุดอนุญาตให้บังคับใช้โหมดมืดได้
  • ธีมกิจกรรมปัจจุบันทำเครื่องหมายเป็นสว่างด้วย ตั้งค่า isLightTheme เป็น true
  • ผู้เขียนเนื้อหาเว็บไม่ได้ปิดใช้การปรับแสงอย่างชัดแจ้ง
  • สําหรับแอปที่กำหนดเป้าหมายเป็น Android 13 (API ระดับ 33) ขึ้นไป เนื้อหาเว็บ ไม่ได้ใช้ prefers-color-scheme
  • สำหรับแอปที่กำหนดเป้าหมายเป็น Android 12 (API ระดับ 32) หรือต่ำกว่า: แอปได้ตั้งค่าไว้ การตั้งค่า forceDarkMode ของ WebView ถึง FORCE_DARK_AUTO และตั้งค่ากลยุทธ์ Force Dark เป็น DARK_STRATEGY_USER_AGENT_DARKENING_ONLY

WebView และทุกแอประดับบนสุดอนุญาตให้บังคับใช้โหมดมืดได้โดยใช้ View.setForceDarkAllowed() ค่าเริ่มต้นจะนำมาจากแอตทริบิวต์ setForceDarkAllowed() ของ ธีม Android ซึ่งต้องตั้งค่าเป็น true ด้วย

โหมดบังคับใช้โหมดมืดมีไว้สำหรับการใช้งานแบบย้อนหลังในแอปที่เป็นหลัก ไม่ต้องระบุธีมมืดของตัวเอง หากแอปใช้ Force Dark เราขอแนะนำ การเพิ่มการรองรับธีมมืด

อนุญาตการปรับให้มืดลงแบบอัลกอริทึม (แอปที่กำหนดเป้าหมายเป็น Android 13 ขึ้นไป)

สำหรับแอปที่ไม่ได้ใช้ Force Dark ระดับแอปและกำหนดเป้าหมายเป็น Android 13 (ระดับ API 33) ขึ้นไป ให้ใช้ AndroidX setAlgorithmicDarkeningAllowed() และส่งใน true เพื่อระบุว่า WebView ควรอนุญาตอัลกอริทึม ปรับให้มืดลง วิธีนี้มีความเข้ากันได้แบบย้อนหลังกับ Android เวอร์ชันก่อนหน้า เวอร์ชันต่างๆ

จากนั้น WebView จะใช้การปรับให้มืดตามอัลกอริทึมหากเป็นไปตามเงื่อนไขต่อไปนี้

  • เนื้อหาเว็บไม่ได้ใช้ prefers-color-scheme
  • ผู้เขียนเนื้อหาเว็บไม่ได้ปิดใช้การปรับแสงอย่างชัดแจ้ง

อนุญาตการปรับให้มืดลงแบบอัลกอริทึม (แอปที่กำหนดเป้าหมายเป็น Android 12 หรือต่ำกว่า)

สำหรับแอปที่ไม่ได้ใช้ Force Dark ระดับแอปและกำหนดเป้าหมายเป็น 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 ใน AndroidX เพื่อควบคุมวิธีปรับให้มืดลงใน WebView ที่ระบุ API นี้ ใช้ได้เฉพาะเมื่อตั้งค่าโหมดบังคับให้มืดเป็น FORCE_DARK_ON หรือ FORCE_DARK_AUTO

เมื่อใช้ API แอปของคุณจะใช้การปรับธีมมืดสำหรับธีมเว็บหรือ User Agent ได้ ปรับให้เข้ม:

  • การปรับธีมเว็บให้มืดลง: นักพัฒนาเว็บอาจนำไปใช้ @media (prefers-color-scheme: dark) เพื่อควบคุมลักษณะที่ปรากฏของหน้าเว็บ โหมดมืด WebView จะแสดงเนื้อหาตามการตั้งค่าเหล่านี้ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ ทำให้ธีมเว็บมืดลง โปรดดู ข้อกำหนด
  • การปรับแสง User Agent: WebView จะกลับสีในเว็บโดยอัตโนมัติ หากคุณใช้การปรับให้มืดของ User Agent การค้นหา @media (prefers-color-scheme: dark) ประเมินได้เป็น false

หากต้องการเลือกระหว่าง 2 กลยุทธ์ ให้ใช้ 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"> ติดแท็กไปยังเว็บไซต์ของตนเพื่อ ตรวจสอบว่าเนื้อหาแสดงผลอย่างถูกต้องใน WebView โดยใช้ การกำหนดค่าเริ่มต้น

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY เรียกว่า "การปรับแสง User Agent" WebView จะละเว้นการทำให้หน้าเว็บมืดลง ใช้การปรับให้มืดโดยอัตโนมัติ

หากแอปแสดงเนื้อหาเว็บบุคคลที่หนึ่งซึ่งคุณปรับแต่งด้วย คำค้นหาสื่อ prefers-color-scheme รายการ เราขอแนะนำ วันที่ DARK_STRATEGY_WEB_THEME_DARKENING_ONLY เพื่อให้แน่ใจว่า WebView ใช้ธีมที่กำหนดเอง

ดูตัวอย่างการใช้ธีมมืดได้ที่ การสาธิต WebView บน GitHub