דף זה תורגם על ידי Cloud Translation API.

יצירת פריסות ווידג'ט גמישות

בדף הזה מתוארים שיפורים לשינוי הגודל של הווידג'טים וגמישות רבה יותר. הושקו ב-Android 12 (רמת API 31). הוא גם מפרט קובעים את גודל הווידג'ט.

החל מ-Android 12 (רמת API 31), אפשר לספק מאפייני גודל ותצוגות גמישות משופרים יותר. לשם כך, מבצעים את הפעולות הבאות, כפי שמתואר בסעיפים הבאים:

ציון אילוצים נוספים לגבי גודל הווידג'ט
שימוש בפריסות רספונסיביות או מדויקות פריסות.

בגרסאות קודמות של Android, אפשר לקבל טווחי גדלים של באמצעות OPTION_APPWIDGET_MIN_WIDTH, OPTION_APPWIDGET_MIN_HEIGHT, OPTION_APPWIDGET_MAX_WIDTH, וגם OPTION_APPWIDGET_MAX_HEIGHT ואז להעריך את גודל הווידג'ט, אבל הלוגיקה הזו לא עובדת במצבים מסוימים. בווידג'טים שמטרגטים ל-Android 12 ואילך, מומלץ לספק פריסות רספונסיביות או פריסות מדויקות.

ב-Android 12 נוספים ממשקי API שמאפשרים לוודא שהווידג'ט בגודל מהימן יותר במכשירים שונים עם מסכים בגדלים שונים.

בנוסף לדומיין minWidth הקיים, minHeight, minResizeWidth, וגם minResizeHeight השתמשו במאפיינים החדשים הבאים appwidget-provider:

targetCellWidth וגם targetCellHeight: להגדיר את גודל היעד של הווידג'ט במונחים של תאי רשת של מרכז האפליקציות. אם המיקום מוגדר, המאפיינים האלה משמשים במקום minWidth או minHeight.
maxResizeWidth וגם maxResizeHeight: להגדיר את הגודל המקסימלי שבו מרכז האפליקציות מאפשר למשתמש לשנות את גודל הווידג'ט.

קוד ה-XML הבא מראה איך להשתמש במאפייני הגודל.

<appwidget-provider
  ...
  android:targetCellWidth="3"
  android:targetCellHeight="2"
  android:maxResizeWidth="250dp"
  android:maxResizeHeight="110dp">
</appwidget-provider>

שימוש בפריסות רספונסיביות

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

התכונה הזו מאפשרת התאמה לעומס (scaling) בצורה חלקה יותר ומערכת טובה יותר באופן כללי תקינות, כי המערכת לא צריכה להוציא את האפליקציה ממצב שינה בכל פעם והווידג'ט מוצג בגודל שונה.

הקוד לדוגמה הבא מראה איך לספק רשימת פריסות.

Kotlin

override fun onUpdate(...) {
    val smallView = ...
    val tallView = ...
    val wideView = ...

    val viewMapping: Map<SizeF, RemoteViews> = mapOf(
            SizeF(150f, 100f) to smallView,
            SizeF(150f, 200f) to tallView,
            SizeF(215f, 100f) to wideView
    )
    val remoteViews = RemoteViews(viewMapping)

    appWidgetManager.updateAppWidget(id, remoteViews)
}

Java

@Override
public void onUpdate(...) {
    RemoteViews smallView = ...;
    RemoteViews tallView = ...;
    RemoteViews wideView = ...;

    Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
    viewMapping.put(new SizeF(150f, 100f), smallView);
    viewMapping.put(new SizeF(150f, 200f), tallView);
    viewMapping.put(new SizeF(215f, 100f), wideView);
    RemoteViews remoteViews = new RemoteViews(viewMapping);

    appWidgetManager.updateAppWidget(id, remoteViews);
}

נניח שלווידג'ט יש את המאפיינים הבאים:

<appwidget-provider
    android:minResizeWidth="160dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="200dp">
</appwidget-provider>

המשמעות של קטע הקוד שלמעלה היא:

תמיכה ב-smallView החל מ-160dp (minResizeWidth) × 110dp (minResizeHeight) ל-160dp × 199dp (נקודת הסף הבאה – 1dp).
tallView תומך ב-160dp × 200dp עד 214dp (נקודת הסף הבאה - 1) × 200dp
wideView תומך בגדלים של 215dp × 110dp (minResizeHeight) עד 250dp (maxResizeWidth) × 200dp (maxResizeHeight).

הערה: יכול להיות שהגודל של הווידג'ט יהיה גדול יותר מ- maxResizeWidth × maxResizeHeight. פרטים נוספים זמינים במאמר מאפייני שינוי הגודל של ווידג'טים.

הווידג'ט חייב לתמוך בטווח גדלים החל מ- minResizeWidth × minResizeHeight עד maxResizeWidth × maxResizeHeight. בטווח הזה, תוכלו לקבוע את נקודת הסף להחלפת הפריסות.

לספק פריסות מדויקות

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

כדי להטמיע את הפתרון הזה, האפליקציה צריכה לבצע את השלבים הבאים:

עומס יתר AppWidgetProvider.onAppWidgetOptionsChanged(), שנקרא כשקבוצת הגדלים משתנה.
קוראים ל-AppWidgetManager.getAppWidgetOptions(), שמחזירה Bundle שמכיל את הגדלים.
ניגשים למקש AppWidgetManager.OPTION_APPWIDGET_SIZES מהמקש Bundle.

בדוגמה הבאה מוסבר איך לספק פריסות מדויקות.

Kotlin

override fun onAppWidgetOptionsChanged(
        context: Context,
        appWidgetManager: AppWidgetManager,
        id: Int,
        newOptions: Bundle?
) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, id, newOptions)
    // Get the new sizes.
    val sizes = newOptions?.getParcelableArrayList<SizeF>(
            AppWidgetManager.OPTION_APPWIDGET_SIZES
    )
    // Check that the list of sizes is provided by the launcher.
    if (sizes.isNullOrEmpty()) {
        return
    }
    // Map the sizes to the RemoteViews that you want.
    val remoteViews = RemoteViews(sizes.associateWith(::createRemoteViews))
    appWidgetManager.updateAppWidget(id, remoteViews)
}

// Create the RemoteViews for the given size.
private fun createRemoteViews(size: SizeF): RemoteViews { }

Java

@Override
public void onAppWidgetOptionsChanged(
    Context context, AppWidgetManager appWidgetManager, int appWidgetId, Bundle newOptions) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, appWidgetId, newOptions);
    // Get the new sizes.
    ArrayList<SizeF> sizes =
        newOptions.getParcelableArrayList(AppWidgetManager.OPTION_APPWIDGET_SIZES);
    // Check that the list of sizes is provided by the launcher.
    if (sizes == null || sizes.isEmpty()) {
      return;
    }
    // Map the sizes to the RemoteViews that you want.
    Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
    for (SizeF size : sizes) {
        viewMapping.put(size, createRemoteViews(size));
    }
    RemoteViews remoteViews = new RemoteViews(viewMapping);
    appWidgetManager.updateAppWidget(id, remoteViews);
}

// Create the RemoteViews for the given size.
private RemoteViews createRemoteViews(SizeF size) { }

קביעת הגודל של הווידג'ט

כל ווידג'ט חייב להגדיר את הערכים targetCellWidth ו-targetCellHeight למכשירים עם Android מגרסה 12 ואילך, או את הערכים minWidth ו-minHeight לכל הגרסאות של Android, כדי לציין את נפח האחסון המינימלי שהוא תופס כברירת מחדל. עם זאת, כשמשתמשים מוסיפים ווידג'ט למסך הבית, הוא בדרך כלל תופס יותר מהרוחב והגובה המינימליים שציינתם.

מסכי הבית של Android מציעים למשתמשים רשת של מרחבים זמינים שבהם הם יכולים להציב ווידג'טים וסמלים. התצוגה יכולה להשתנות בהתאם למכשיר. לדוגמה, במכשירי טלפון רבים התצוגה היא 5x4, ובטאבלטים התצוגה יכולה להיות גדולה יותר. כשהווידג'ט מתווסף, הוא מתרחב כדי לתפוס את מספר התאים המינימלי, אופקית וזקופה, שנדרש כדי לעמוד באילוצים של targetCellWidth ו-targetCellHeight במכשירים עם Android מגרסה 12 ואילך, או באילוצים של minWidth ו-minHeight במכשירים עם Android מגרסה 11 (רמת API 30) וגרסאות קודמות.

רוחב וגובה התא וגודל השוליים האוטומטיים שחלים על ווידג'טים עשויים להשתנות בין מכשירים. אפשר להשתמש בטבלה הבאה כדי לקבל אומדן משוער את המידות המינימליות של הווידג'ט בטלפון רשת רגיל בגודל 5x4, בהינתן מספר תאי הרשת הפנויים שרוצים:

מספר התאים (רוחב x גובה)	גודל זמין בפריסה לאורך (dp)	גודל זמין בפריסה לרוחב (dp)
1x1	57x102dp	127x51dp
2x1	130x102dp	269x51dp
3x1	203x102dp	412x51dp
4x1	276x102dp	554x51dp
5x1	349x102dp	697x51dp
5x2	349x220dp	697x117dp
5x3	349x337dp	697x184dp
5x4	349x455dp	697x250dp
...	...	...
n x m	(73n - 16) x (118m - 16)	(142n - 15) x (66m - 15)

להשתמש בגדלים של התאים בפריסה לאורך כדי לציין את הערכים שמציינים המאפיינים minWidth, minResizeWidth ו-maxResizeWidth. באופן דומה, אפשר להשתמש בגדלי התאים במצב לרוחב כדי לקבוע את הערכים שצריך לספק למאפיינים minHeight, minResizeHeight ו-maxResizeHeight.

הסיבה לכך היא שרוחב התא בדרך כלל קטן יותר בפריסה לאורך מאשר בפריסה לרוחב, ובאופן דומה, גובה התא בדרך כלל קטן יותר בפריסה לרוחב מאשר בפריסה לאורך.

לדוגמה, אם רוצים שאפשר יהיה לשנות את רוחב הווידג'ט עד לתא אחד ב-Google Pixel 4, צריך להגדיר את minResizeWidth ל-56dp לכל היותר כדי לוודא שהערך של המאפיין minResizeWidth קטן מ-57dp, כי רוחב התא הוא לפחות 57dp במצב לאורך. באופן דומה, אם רוצים שניתן יהיה לשנות את גובה הווידג'ט בתא אחד באותו מכשיר, צריך להגדיר את minResizeHeight ל-50dp לכל היותר כדי לוודא ערך המאפיין minResizeHeight קטן מ- 51dp - כיוון שתא אחד הוא בגובה של לפחות 51dp בפריסה לרוחב.

אפשר לשנות את הגודל של כל ווידג'ט בטווח הגדלים שבין המאפיינים minResizeWidth/minResizeHeight לבין המאפיינים maxResizeWidth/maxResizeHeight, כלומר הוא צריך להתאים לכל טווח גדלים בטווח הזה.

לדוגמה, כדי להגדיר את גודל ברירת המחדל של הווידג'ט במיקום, אפשר להגדיר את המאפיינים הבאים:

<appwidget-provider
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    android:minWidth="180dp"
    android:minHeight="110dp">
</appwidget-provider>

כלומר, גודל ברירת המחדל של הווידג'ט הוא 3x2 תאים, כפי שצוין במאפיינים targetCellWidth ו-targetCellHeight, או 180x110dp, כפי שצוין במאפיינים minWidth ו-minHeight במכשירים עם Android מגרסה 11 ומטה. במקרה השני, הגודל של התאים עשוי להשתנות בהתאם למכשיר.

בנוסף, כדי להגדיר את טווחי הגדלים הנתמכים של הווידג'ט, אפשר להגדיר את הערכים הבאים :

<appwidget-provider
    android:minResizeWidth="180dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="530dp"
    android:maxResizeHeight="450dp">
</appwidget-provider>

כפי שצוין במאפיינים הקודמים, רוחב הווידג'ט הוא ניתן לשנות את גודלו מ-180dp עד 530dp, וניתן לשנות את הגובה שלו מ-110dp עד 450dp. לאחר מכן תוכלו לשנות את הגודל של הווידג'ט מ-3x2 לתאים של 5x2, כל עוד מתקיימים התנאים הבאים:

המכשיר מציג רשת של 5x4.
המיפוי בין מספר התאים לגודל הזמין ב-dps עוקב אחר הטבלה שמציגה אומדן של מינימום מאפיינים בדף הזה.
הווידג'ט מתאים את עצמו לטווח הגדלים הזה.

Kotlin

val smallView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_small)
val mediumView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_medium)
val largeView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_large)

val viewMapping: Map<SizeF, RemoteViews> = mapOf(
        SizeF(180f, 110f) to smallView,
        SizeF(270f, 110f) to mediumView,
        SizeF(270f, 280f) to largeView
)

appWidgetManager.updateAppWidget(appWidgetId, RemoteViews(viewMapping))

Java

RemoteViews smallView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_small);
RemoteViews mediumView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_medium);
RemoteViews largeView = 
    new RemoteViews(context.getPackageName(), R.layout.widget_weather_forecast_large);

Map<SizeF, RemoteViews> viewMapping = new ArrayMap<>();
viewMapping.put(new SizeF(180f, 110f), smallView);
viewMapping.put(new SizeF(270f, 110f), mediumView);
viewMapping.put(new SizeF(270f, 280f), largeView);
RemoteViews remoteViews = new RemoteViews(viewMapping);

appWidgetManager.updateAppWidget(id, remoteViews);

נניח שהווידג'ט משתמש בפריסות הרספונסיביות שמוגדרות בקטעי הקוד הקודמים. כלומר, הפריסה שצוינה בתור R.layout.widget_weather_forecast_small תוצג בגדלים הבאים: 180dp (minResizeWidth) x‏ 110dp (minResizeHeight) עד 269x279dp (נקודות החיתוך הבאות פחות 1). באופן דומה, הגודל של R.layout.widget_weather_forecast_medium הוא 270x110dp עד 270x279dp. ו-R.layout.widget_weather_forecast_large משמש מ-270x280dp עד 530dp (maxResizeWidth) x 450dp (maxResizeHeight).

כשהמשתמש משנה את הגודל של הווידג'ט, המראה שלו משתנה בהתאם לכל גודל בתאים, כפי שמוצג בדוגמאות הבאות.

דוגמה לווידג'ט מזג אוויר בגודל התצוגה הקטן ביותר של רשת 3x2. בממשק המשתמש מוצג
שם המיקום (טוקיו), טמפרטורה (14°) וסמל שמציין
מעונן חלקית. — **איור 2.** 3x2 `R.layout.widget_weather_forecast_small`.

דוגמה לווידג'ט של מזג אוויר בגודל 'בינוני' בגודל 4x2 גודל. שינוי הגודל של הווידג'ט בדרך הזו מבוסס על כל ממשק המשתמש של גודל הווידג'ט הקודם, ומוסיף את התווית 'בהיר חלקית' ותחזית של הטמפרטורות מ-16:00 עד 19:00. — **איור 3.** 4x2 `R.layout.widget_weather_forecast_medium`.

דוגמה לווידג'ט של מזג אוויר בגודל 'בינוני' בגודל 5x2 גודל. שינוי גודל הווידג'ט
כך שיתקבלו אותו ממשק משתמש כמו הגודל הקודם,
נמתח על ידי תא אחד כדי לתפוס יותר מקום אופקי. — **איור 4.** 5x2 `R.layout.widget_weather_forecast_medium`.

דוגמה לווידג'ט של מזג האוויר בגודל 'גדול' 5x3. שינוי גודל הווידג'ט
ככה הוא מבוסס על כל ממשק המשתמש מהגדלים הקודמים של הווידג'טים,
ולהוסיף תצוגה בתוך הווידג'ט שמכיל תחזית של מזג האוויר
בימים שלישי ורביעי. סמלים שמציינים מזג אוויר שמשי או גשום
ובטמפרטורות גבוהות ונמוכות בכל יום. — **איור 5.** 5x3 `R.layout.widget_weather_forecast_large`.

דוגמה לווידג'ט של מזג האוויר בגודל 'גדול' 5x4. שינוי הגודל של הווידג'ט בדרך הזו מבוסס על כל ממשק המשתמש של הגדלים הקודמים של הווידג'ט, ומוסיף את יום חמישי ויום שישי (ואת הסמלים המתאימים שלהם שמציינים את סוג מזג האוויר ואת הטמפרטורה הגבוהה והנמוכה בכל יום). — **איור 6.** 5x4 `R.layout.widget_weather_forecast_large`.

יצירת פריסות ווידג'ט גמישות

שימוש בממשקי API משופרים לגדלים ולפריסות של ווידג'טים

ציון מגבלות נוספות של גודל הווידג'ט

שימוש בפריסות רספונסיביות

Kotlin

Java

לספק פריסות מדויקות

Kotlin

Java

קביעת הגודל של הווידג'ט

Kotlin

Java