איך להכהות תוכן מהאינטרנט ב-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 והאלמנטים הראשיים שלו מאפשרים הפעלה ידנית של מצב כהה.
• העיצוב הנוכחי של הפעילות מסומן כבהיר עם הערך true של isLightTheme.
• יוצר התוכן באינטרנט לא משבית במפורש את ההכהייה.
• באפליקציות שמטרגטות ל-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) ומעלה, צריך להשתמש בשיטה Jetpack Webkit‏ 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 בספריית Jetpack כדי לשלוט באופן ההחמרה של מצב כהה ב-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 נדרש תג meta כדי לכבד את שאילתות המדיה של דף האינטרנט prefers-color-scheme. אפשר להשתמש ב-WebViews עם מצב DARK_STRATEGY_WEB_THEME_DARKENING_ONLY, ובמקרה כזה WebView תמיד יחיל שאילתות מדיה גם אם התג הושמט.

  עם זאת, מומלץ למפתחי אתרים להוסיף תג <meta name="color-scheme" content="dark light"> לאתרים שלהם כדי לוודא שהתוכן מוצג בצורה תקינה בתצוגות WebView עם הגדרת ברירת המחדל.

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: ה-WebView מתעלם מהחשכה של דף אינטרנט ומחיל החשכה אוטומטית. התהליך הזה נקרא 'החשכה של סוכן משתמש'.

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

דוגמה לעיצוב כהה מופיעה בהדגמה של WebView ב-GitHub