איך להכהות תוכן מהאינטרנט ב-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, במקרה הצורך, להחיל אלגוריתם כהה לעיצוב של תוכן האינטרנט שהוא מעבד.

אם האפליקציה משתמשת ברמת האפליקציה אילוץ כהה לשימוש באלגוריתם להחיל עיצוב כהה על האפליקציה, בקטע הבא מוסבר איך הפעלת כהה אלגוריתמיות של תוכן באינטרנט באמצעות אילוץ כהה.

אם באפליקציה לא נעשה שימוש באילוץ כהה, כיצד האפליקציה מציינת מתי לאפשר מערכת כהה אלגוריתמית ב-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 והם הגדירו את אסטרטגיית 'כוח כהה' שלהם 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 אם האפליקציה מספקת שיטה משלה למעבר בין עיצוב בהיר לעיצוב כהה, כמו רכיב שניתן להחליף מצב בממשק המשתמש או בחירה אוטומטית מבוססת זמן.

כדי לבדוק אם התכונה נתמכת, צריך להוסיף את שורות הקוד הבאות בכל מקום שבו מגדירים את אובייקט ה-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, האפליקציה שלך יכולה להשתמש בהכהת עיצוב האתר או בסוכן משתמש כהה:

• עיצוב כהה של אינטרנט: מפתחים של אתרים עשויים להחיל @media (prefers-color-scheme: dark) כדי לקבוע את ההופעה של דף אינטרנט ב: מצב כהה. מערכת WebView מעבדת תוכן בהתאם להגדרות האלה. מידע נוסף על נושא האינטרנט מחשיך, מפרט.
• הכהה של סוכן משתמש: ה-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"> Tag לאתרים שלהם כדי לוודא שהתוכן יעובד כראוי ברכיבי WebView עם הגדרות ברירת המחדל.

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: נקרא "user-agentinging," ה-WebView מתעלם מכל החשכה של דפי אינטרנט מפעילה כהה באופן אוטומטי.

אם האפליקציה מציגה תוכן אינטרנט מאינטראקציה ישירה (First-Party) שהתאמת אישית באמצעות שאילתת מדיה אחת (prefers-color-scheme), מומלץ DARK_STRATEGY_WEB_THEME_DARKENING_ONLY כדי להבטיח שה-WebView ישתמש בעיצוב מותאם אישית.

כדי לראות דוגמה לעיצוב כהה שהוחל, אפשר לעיין ב הדגמה של WebView ב-GitHub