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

אם האפליקציה לא משתמשת ב-Force Dark, האופן שבו האפליקציה מציינת מתי לאפשר את ההכהה האלגוריתמית ב-WebView תלוי ברמת ה-API לטירגוט של האפליקציה. בקטע הבא מפורט מידע נוסף על אפליקציות שמטרגטות את Android מגרסה 13 ואילך ועל אפליקציות שמטרגטות את Android מגרסה 12 ומטה.

איך מאפשרים כהה אלגוריתמית של תוכן אינטרנט באמצעות הפעלה ידנית של מצב כהה

אם האפליקציה שלכם משתמשת באפשרות Force Dark ברמת האפליקציה, מערכת 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.

מצב כהה מאולץ מיועד בעיקר לתאימות לאחור באפליקציות שלא מציעות עיצוב כהה משלה. אם האפליקציה משתמשת באילוץ כהה, מומלץ להוסיף תמיכה לעיצוב כהה.

מתן הרשאה להכהיה אלגוריתמית (אפליקציות שמטרגטות ל-Android 13 ואילך)

באפליקציות שלא משתמשות ב-Force Dark ברמת האפליקציה ומטרגטות ל-Android 13 (רמת API 33) ואילך, צריך להשתמש בשיטה setAlgorithmicDarkeningAllowed() של AndroidX ולהעביר את הערך true כדי לציין ש-WebView צריך לאפשר הכהיה אלגוריתמית. השיטה הזו תואמת לגרסאות קודמות של Android.

לאחר מכן, WebView מחיל האפלה אלגוריתמית אם מתקיימים התנאים הבאים:

• תוכן האינטרנט לא משתמש ב-prefers-color-scheme.
• יוצר תוכן האינטרנט לא משבית את ההכהיה באופן מפורש.

מתן הרשאה להכהיה אלגוריתמית (אפליקציות שמטרגטות ל-Android מגרסה 12 ומטה)

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

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

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

דוגמה לעיצוב כהה שהוחל זמינה בהדגמה של WebView ב-GitHub.