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

שיפור הווידג'ט

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

שימוש בצבעים דינמיים

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

יש שתי דרכים ליצור צבעים דינמיים:

משתמשים בעיצוב ברירת המחדל של המערכת (@android:style/Theme.DeviceDefault.DayNight) בפריסה ברמה הבסיסית.
משתמשים בעיצוב Material 3‏ (Theme.Material3.DynamicColors.DayNight) מהספרייה Material Components for Android, שזמינה החל מ-Material Components for Android גרסה 1.6.0.

אחרי שהעיצוב מוגדר בפריסה ברמה הבסיסית, אפשר להשתמש במאפייני צבע נפוצים ברמה הבסיסית (root) או בכל אחד מהצאצאים שלו כדי לבחור את הצבעים הדינמיים.

דוגמאות למאפייני צבע שאפשר להשתמש בהם:

?attr/primary
?attr/primaryContainer
?attr/onPrimary
?attr/onPrimaryContainer

בדוגמה הבאה, שבה נעשה שימוש בעיצוב Material 3, צבע העיצוב של המכשיר הוא 'סגול'. צבע ההדגשה ורקע הווידג'ט מותאמים למצבים הבהיר והכהה, כפי שמוצג בתמונות 1 ו-2.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>

הווידג'ט בעיצוב של מצב בהיר — **איור 1.** הווידג'ט בעיצוב בהיר.

ווידג'טים בעיצוב כהה — **איור 2.** ווידג'ט בעיצוב כהה.

תאימות לאחור לצבעים דינמיים

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

דוגמה לשימוש בעיצוב Material 3:

`/values/styles.xml`

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

`/values-v31/styles.xml`

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

`/layout/my_widget_layout.xml`

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

הפעלת תמיכה קולית

פעולות באפליקציה מאפשרות ל-Google Assistant להציג ווידג'טים בתגובה לפקודות קוליות רלוונטיות של המשתמשים. אם תגדירו את הווידג'ט כך שישיב לכוונות מובנות (BIIs), האפליקציה תוכל להציג וידג'טים באופן יזום בממשקי Assistant, כמו Android ו-Android Auto. המשתמשים יכולים להצמיד לווידג'טים שמוצגים על ידי Assistant למרכז האפליקציות, כדי לעודד אינטראקציה עתידית.

לדוגמה, אתם יכולים להגדיר את הווידג'ט לסיכום אימוני הכושר באפליקציית האימון כדי לבצע את הפקודות הקוליות של המשתמשים שמפעילות את ה-BII GET_EXERCISE_OBSERVATION. Assistant מציגה את הווידג'ט באופן יזום כשמשתמשים מפעילים את ה-BII הזה על ידי שליחת בקשות כמו "Ok Google, how many miles did I run this week on ExampleApp?‎"

יש עשרות ממשקי BII שמכסים כמה קטגוריות של אינטראקציה עם משתמשים, ומאפשרים לכל אפליקציה ל-Android לשפר את הווידג'טים שלה לשימוש קולי. למידע נוסף, קראו את המאמר שילוב פעולות באפליקציות עם ווידג'טים של Android.

ב-Android 12 אפשר להוסיף תצוגות מקדימות מותאמות לווידג'טים ותיאורי ווידג'טים. ב-Android 15 אפשר לשפר את חוויית הבחירה של הווידג'טים באפליקציה באמצעות תצוגות מקדימות של הווידג'טים שנוצרו.

כדי לשפר את חוויית השימוש בבורר הווידג'טים של האפליקציה, כדאי לספק תצוגה מקדימה של הווידג'ט שנוצר במכשירי Android 15 ואילך, תצוגה מקדימה של הווידג'ט עם שינוי קנה המידה (על ידי ציון previewLayout) במכשירי Android 12 עד Android 14, ו-previewImage לגרסאות קודמות.

כדי שאפשר יהיה לספק את RemoteViews לבורר הווידג'טים במכשירי Android בגרסה 15 ואילך, האפליקציות צריכות להגדיר את הערך של compileSdk ל-35 ואילך בקובץ build.gradle של המודול. פירוש הדבר הוא שאפליקציות יכולות לעדכן את התוכן בבורר כך שייצג בצורה טובה יותר את מה שהמשתמש רואה.

אפליקציות יכולות להשתמש בשיטות AppWidgetManager, setWidgetPreview ו-getWidgetPreview כדי לעדכן את המראה של הווידג'טים שלהן במידע עדכני ומותאם אישית.

יצירת תצוגה מקדימה מעודכנת באמצעות Jetpack Glance

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

בדוגמה הבאה נעשה שימוש ב-Jetpack Glance כדי ליצור תצוגה מקדימה מעודכנת. כדי ש-setWidgetPreview יוצג כשיטה בקטע הקוד הזה, צריך להגדיר את compileSdk ל-35 ואילך.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)
AppWidgetSnippets.kt

יצירת תצוגה מקדימה מעודכנת בלי Jetpack Glance

אפשר להשתמש ב-RemoteViews בלי Glance. בדוגמה הבאה נטען משאב של פריסה של ווידג'ט בפורמט XML, והוא מוגדר כקטע המקדים. כדי ש-setWidgetPreview יופיע כ-method בקטע הקוד הזה, נדרשת הגדרת build של compileSdk של 35 ואילך.

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)AppWidgetSnippets.kt

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

כדי להטמיע תצוגות מקדימות של ווידג'טים שניתן לשנות, השתמשו במאפיין previewLayout של הרכיב appwidget-provider כדי לספק פריסת XML:

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

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

מומלץ לציין גם את המאפיינים previewLayout וגם את המאפיינים previewImage, כדי שהאפליקציה תוכל לעבור לשימוש ב-previewImage אם המכשיר של המשתמש לא תומך ב-previewLayout. המאפיין previewLayout מקבל קדימות על פני המאפיין previewImage.

גישות מומלצות ליצירת תצוגות מקדימות מדויקות

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

תמונה שמוצגת בה תצוגה מקדימה של ווידג'ט — **איור 3.** תצוגה מקדימה של ווידג'ט שמופיעה כברירת מחדל באזור 3x3, אבל יכולה להתאים לאזור 3x1 בגלל הפריסה של קוד ה-XML.

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

הגדרת android:text="@string/my_widget_item_fake_1" לרכיבי TextView.

הערה: ערכים שהוגדרו באמצעות התג tools, כמו tools:text="@string/my_wdiget_item_fake_1", לא מוצגים בתצוגה המקדימה.
הגדרת תמונה או סמל ברירת מחדל או placeholder, כמו android:src="@drawable/my_widget_icon", לרכיבי ImageView.

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

לקבלת פרטים על גישות מומלצות לתצוגות מקדימות מורכבות יותר שמכילות את השדות ListView,‏ GridView או StackView, אפשר לעיין במאמר יצירת תצוגות מקדימות מדויקות שכוללות פריטים דינמיים.

תאימות לאחור עם תצוגות מקדימות של ווידג'טים שניתן לשנות

כדי לאפשר לכלי לבחירת ווידג'טים ב-Android 11 (רמת API 30) ואילך להציג תצוגות מקדימות של הווידג'ט, צריך לציין את המאפיין previewImage.

אם משנים את המראה של הווידג'ט, צריך לעדכן את תמונת התצוגה המקדימה.

לווידג'טים צריך להיות שם ייחודי כשהם מוצגים בבורר הווידג'טים.

שמות של ווידג'טים נטענים מהמאפיין label של האלמנט receiver של הווידג'ט בקובץ AndroidManifest.xml.

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

החל מ-Android 12, צריך לספק תיאור לווידג'ט שיוצג בבורר הווידג'טים.

תמונה של הכלי לבחירת ווידג'ט שמציג את הווידג'ט ואת התיאור שלו — **איור 4.** בורר ווידג'טים לדוגמה שבו מוצג ווידג'ט עם התיאור שלו.

מספקים תיאור לווידג'ט באמצעות המאפיין description של האלמנט <appwidget-provider>:

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

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

הפעלת מעברים חלקים יותר

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

כדי להפעיל את המעבר המשופר הזה, צריך להשתמש ב-@android:id/background או ב-android.R.id.background לזיהוי רכיב הרקע:

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

באפליקציה שלכם אפשר להשתמש ב-@android:id/background בגרסאות קודמות של Android בלי לגרום לשיבושים, אבל המערכת תתעלם ממנו.

שימוש בשינוי של RemoteViews בסביבת זמן הריצה

החל מ-Android 12, אפשר להשתמש בכמה שיטות של RemoteViews שמאפשרות לשנות את המאפיינים של RemoteViews בסביבת זמן הריצה. הרשימה המלאה של השיטות שנוספו מפורטת במסמכי העזרה של API RemoteViews.

הקוד לדוגמה הבא מראה איך להשתמש בכמה מהשיטות האלה.

Kotlin

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

Java

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);