שימוש בווידג'טים של אוספים

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

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

ListView
תצוגה שבה הפריטים מוצגים ברשימה שגלולת אנכית.
GridView
תצוגה שבה הפריטים מוצגים ברשת דו-מימדית שניתן לגלול בה.
StackView
תצוגת כרטיסים מוערמים – בדומה לאוסף כרטיסים – שבה המשתמש יכול להקיש על הכרטיס הקדמי למעלה או למטה כדי לראות את הכרטיס הקודם או הבא, בהתאמה.
AdapterViewFlipper
ViewAnimator פשוט שמבוסס על מתאם, שמציג אנימציה בין שתי תצוגות או יותר. רק ילד אחד מוצג בכל פעם.

מאחר שבטבלאות הקולקציות האלה מוצגות קולקציות שמגובות בנתונים מרוחקים, הן משתמשות ב-Adapter כדי לקשר את ממשק המשתמש שלהן לנתונים. Adapter מקשר בין פריטים ספציפיים מקבוצת נתונים לבין אובייקטים ספציפיים של View.

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

RemoteViewsService הוא שירות שמאפשר למתאם מרוחק לבקש אובייקטים מסוג RemoteViews. RemoteViewsFactory הוא ממשק למתאם בין תצוגת אוסף – כמו ListView,‏ GridView ו-StackView – לבין הנתונים הבסיסיים של התצוגה הזו. מהדוגמה StackWidget, הנה דוגמה לקוד הסטנדרטי להטמעת השירות והממשק:

Kotlin

class StackWidgetService : RemoteViewsService() {

    override fun onGetViewFactory(intent: Intent): RemoteViewsFactory {
        return StackRemoteViewsFactory(this.applicationContext, intent)
    }
}

class StackRemoteViewsFactory(
        private val context: Context,
        intent: Intent
) : RemoteViewsService.RemoteViewsFactory {

// See the RemoteViewsFactory API reference for the full list of methods to
// implement.

}

Java

public class StackWidgetService extends RemoteViewsService {
    @Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {

// See the RemoteViewsFactory API reference for the full list of methods to
// implement.

}

אפליקציה לדוגמה

קטעי הקוד בקטע הזה לקוחים גם מהדוגמה StackWidget:

איור 1. StackWidget

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

  • המשתמש יכול לגרור את התצוגה העליונה בווידג'ט באופן אנכי כדי להציג את התצוגה הבאה או הקודמת. זוהי התנהגות מובנית של StackView.

  • ללא אינטראקציה של המשתמש, הווידג'ט עובר באופן אוטומטי בין התצוגות שלו ברצף, כמו שקופיות. הסיבה לכך היא ההגדרה android:autoAdvanceViewId="@id/stack_view" בקובץ res/xml/stackwidgetinfo.xml. ההגדרה הזו חלה על מזהה התצוגה, שהוא במקרה הזה מזהה התצוגה של תצוגת הערימות.

  • אם המשתמש נוגע בתצוגה העליונה, בווידג'ט תוצג ההודעה Toast "Touched view n", כאשר n הוא האינדקס (המיקום) של התצוגה שנגעו בה. מידע נוסף על הטמעת התנהגויות זמין בקטע הוספת התנהגות לפריטים ספציפיים.

הטמעת ווידג'טים עם אוספים

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

מניפסט לווידג'טים עם אוספים

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

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

<service android:name="MyWidgetService"
    android:permission="android.permission.BIND_REMOTEVIEWS" />

בדוגמה הזו, android:name="MyWidgetService" מתייחס לקבוצת המשנה של RemoteViewsService.

פריסה של ווידג'טים עם אוספים

הדרישה העיקרית לקובץ ה-XML של פריסת הווידג'ט היא שהוא צריך לכלול את אחת מתצוגות האוסף: ListView,‏ GridView,‏ StackView או AdapterViewFlipper. זהו קובץ ה-widget_layout.xml של הדוגמה StackWidget:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <StackView
        android:id="@+id/stack_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:loopViews="true" />
    <TextView
        android:id="@+id/empty_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:background="@drawable/widget_item_background"
        android:textColor="#ffffff"
        android:textStyle="bold"
        android:text="@string/empty_view_text"
        android:textSize="20sp" />
</FrameLayout>

לתשומת ליבכם: תצוגות ריקות חייבות להיות אחיות של תצוגת הקולקציה שבה התצוגה הריקה מייצגת מצב ריק.

בנוסף לקובץ הפריסה של הווידג'ט כולו, יוצרים קובץ פריסה נוסף שמגדיר את הפריסה של כל פריט באוסף – לדוגמה, פריסה לכל ספר באוסף ספרים. לדוגמה StackWidget יש רק קובץ אחד של פריסה של פריט, widget_item.xml, כי לכל הפריטים יש את אותה פריסה.

הכיתה AppWidgetProvider לווידג'טים עם אוספים

בדומה לווידג'טים רגילים, רוב הקוד בתת-הסוג AppWidgetProvider נמצא בדרך כלל ב-onUpdate(). ההבדל העיקרי בהטמעה של onUpdate() כשיוצרים ווידג'ט עם אוספים הוא שצריך לבצע קריאה ל-setRemoteAdapter(). כך תציינו לתצוגת האוסף מאיפה לקבל את הנתונים. לאחר מכן, ה-RemoteViewsService יוכל להחזיר את ההטמעה של RemoteViewsFactory, והווידג'ט יוכל להציג את הנתונים המתאימים. כשקוראים לשיטה הזו, מעבירים כוונה (intent) שמצביעה על ההטמעה של RemoteViewsService ועל מזהה הווידג'ט שמציין את הווידג'ט שרוצים לעדכן.

לדוגמה, כך מיושמת השיטה onUpdate() בקוד לדוגמה StackWidget כדי להגדיר את RemoteViewsService כמתאם המרוחק של אוסף הווידג'טים:

Kotlin

override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
) {
    // Update each of the widgets with the remote adapter.
    appWidgetIds.forEach { appWidgetId ->

        // Set up the intent that starts the StackViewService, which
        // provides the views for this collection.
        val intent = Intent(context, StackWidgetService::class.java).apply {
            // Add the widget ID to the intent extras.
            putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
            data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))
        }
        // Instantiate the RemoteViews object for the widget layout.
        val views = RemoteViews(context.packageName, R.layout.widget_layout).apply {
            // Set up the RemoteViews object to use a RemoteViews adapter.
            // This adapter connects to a RemoteViewsService through the
            // specified intent.
            // This is how you populate the data.
            setRemoteAdapter(R.id.stack_view, intent)

            // The empty view is displayed when the collection has no items.
            // It must be in the same layout used to instantiate the
            // RemoteViews object.
            setEmptyView(R.id.stack_view, R.id.empty_view)
        }

        // Do additional processing specific to this widget.

        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds)
}

Java

public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
    // Update each of the widgets with the remote adapter.
    for (int i = 0; i < appWidgetIds.length; ++i) {

        // Set up the intent that starts the StackViewService, which
        // provides the views for this collection.
        Intent intent = new Intent(context, StackWidgetService.class);
        // Add the widget ID to the intent extras.
        intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
        intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
        // Instantiate the RemoteViews object for the widget layout.
        RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
        // Set up the RemoteViews object to use a RemoteViews adapter.
        // This adapter connects to a RemoteViewsService through the specified
        // intent.
        // This is how you populate the data.
        views.setRemoteAdapter(R.id.stack_view, intent);

        // The empty view is displayed when the collection has no items.
        // It must be in the same layout used to instantiate the RemoteViews
        // object.
        views.setEmptyView(R.id.stack_view, R.id.empty_view);

        // Do additional processing specific to this widget.

        appWidgetManager.updateAppWidget(appWidgetIds[i], views);
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds);
}

שמירת נתונים

כפי שמתואר בדף הזה, תת-הסוג RemoteViewsService מספק את RemoteViewsFactory שמשמש לאכלוס תצוגת הקולקציה המרוחקת.

באופן ספציפי, מבצעים את השלבים הבאים:

  1. מחלקה משנית RemoteViewsService. RemoteViewsService הוא השירות שבו מתאם מרוחק יכול לבקש את RemoteViews.

  2. בתת-המחלקה RemoteViewsService, צריך לכלול מחלקה שמטמיעה את הממשק RemoteViewsFactory. RemoteViewsFactory הוא ממשק למתאם בין תצוגת אוסף מרחוק – כמו ListView,‏ GridView, ‏ StackView – לבין הנתונים הבסיסיים של התצוגה הזו. ההטמעה שלכם אחראית ליצירת אובייקט RemoteViews לכל פריט במערך הנתונים. הממשק הזה הוא מעטפת דקה של Adapter.

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

התוכן העיקרי של הטמעת RemoteViewsService הוא RemoteViewsFactory שלה, שמתואר בקטע הבא.

ממשק RemoteViewsFactory

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

שתי השיטות החשובות ביותר שצריך להטמיע בתת-הסוג של RemoteViewsFactory הן onCreate() ו-getViewAt().

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

לפניכם קטע מההטמעה של RemoteViewsFactory בדוגמה StackWidget, שבו מוצגים חלקים מהשיטה onCreate():

Kotlin

private const val REMOTE_VIEW_COUNT: Int = 10

class StackRemoteViewsFactory(
        private val context: Context
) : RemoteViewsService.RemoteViewsFactory {

    private lateinit var widgetItems: List<WidgetItem>

    override fun onCreate() {
        // In onCreate(), set up any connections or cursors to your data
        // source. Heavy lifting, such as downloading or creating content,
        // must be deferred to onDataSetChanged() or getViewAt(). Taking
        // more than 20 seconds on this call results in an ANR.
        widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") }
        ...
    }
    ...
}

Java

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {
    private static final int REMOTE_VIEW_COUNT = 10;
    private List<WidgetItem> widgetItems = new ArrayList<WidgetItem>();

    public void onCreate() {
        // In onCreate(), setup any connections or cursors to your data
        // source. Heavy lifting, such as downloading or creating content,
        // must be deferred to onDataSetChanged() or getViewAt(). Taking
        // more than 20 seconds on this call results in an ANR.
        for (int i = 0; i < REMOTE_VIEW_COUNT; i++) {
            widgetItems.add(new WidgetItem(i + "!"));
        }
        ...
    }
...

השיטה RemoteViewsFactory‏ getViewAt() מחזירה אובייקט RemoteViews שתואם לנתונים ב-position שצוין בקבוצת הנתונים. הנה קטע מההטמעה של RemoteViewsFactory בדוגמה StackWidget:

Kotlin

override fun getViewAt(position: Int): RemoteViews {
    // Construct a remote views item based on the widget item XML file
    // and set the text based on the position.
    return RemoteViews(context.packageName, R.layout.widget_item).apply {
        setTextViewText(R.id.widget_item, widgetItems[position].text)
    }
}

Java

public RemoteViews getViewAt(int position) {
    // Construct a remote views item based on the widget item XML file
    // and set the text based on the position.
    RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_item);
    views.setTextViewText(R.id.widget_item, widgetItems.get(position).text);
    return views;
}

הוספת התנהגות לפריטים ספציפיים

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

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

במקום זאת, כדי להוסיף התנהגות קליקים לפריטים ספציפיים באוסף, משתמשים ב-setOnClickFillInIntent(). לשם כך, צריך להגדיר תבנית של כוונה בהמתנה לתצוגת האוסף, ואז להגדיר כוונה להשלמה לכל פריט באוסף באמצעות RemoteViewsFactory.

בקטע הזה נעזר בדוגמה StackWidget כדי להסביר איך מוסיפים התנהגות לפריטים ספציפיים. בדוגמה StackWidget, אם המשתמש נוגע בתצוגה העליונה, בווידג'ט תוצג ההודעה Toast "Touched view n", כאשר n הוא המדד (המיקום) של התצוגה שנגעו בה. כך זה עובד:

  • המחלקה StackWidgetProvider – תת-מחלקה של AppWidgetProvider – יוצרת כוונת רכישה בהמתנה עם פעולה בהתאמה אישית שנקראת TOAST_ACTION.

  • כשהמשתמש נוגע בתצוגה, ה-Intent מופעל ומשודר TOAST_ACTION.

  • השידור הזה נתפס על ידי השיטה onReceive() של הכיתה StackWidgetProvider, והווידג'ט מציג את ההודעה Toast לתצוגה שנגעו בה. הנתונים של פריטי האוסף מסופקים על ידי ה-RemoteViewsFactory דרך ה-RemoteViewsService.

הגדרת התבנית של כוונה בהמתנה

המשתנה StackWidgetProvider (תת-סוג של AppWidgetProvider) מגדיר PendingIntent. אי אפשר להגדיר כוונות בהמתנה לכל פריט בנפרד באוסף. במקום זאת, האוסף כולו מגדיר תבנית של כוונה בהמתנה, והפריטים הנפרדים מגדירים כוונה למלא כדי ליצור התנהגות ייחודית לכל פריט בנפרד.

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

Kotlin

const val TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION"
const val EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM"

class StackWidgetProvider : AppWidgetProvider() {

    ...

    // Called when the BroadcastReceiver receives an Intent broadcast.
    // Checks whether the intent's action is TOAST_ACTION. If it is, the
    // widget displays a Toast message for the current item.
    override fun onReceive(context: Context, intent: Intent) {
        val mgr: AppWidgetManager = AppWidgetManager.getInstance(context)
        if (intent.action == TOAST_ACTION) {
            val appWidgetId: Int = intent.getIntExtra(
                    AppWidgetManager.EXTRA_APPWIDGET_ID,
                    AppWidgetManager.INVALID_APPWIDGET_ID
            )
            // EXTRA_ITEM represents a custom value provided by the Intent
            // passed to the setOnClickFillInIntent() method to indicate the
            // position of the clicked item. See StackRemoteViewsFactory in
            // Set the fill-in Intent for details.
            val viewIndex: Int = intent.getIntExtra(EXTRA_ITEM, 0)
            Toast.makeText(context, "Touched view $viewIndex", Toast.LENGTH_SHORT).show()
        }
        super.onReceive(context, intent)
    }

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Update each of the widgets with the remote adapter.
        appWidgetIds.forEach { appWidgetId ->

            // Sets up the intent that points to the StackViewService that
            // provides the views for this collection.
            val intent = Intent(context, StackWidgetService::class.java).apply {
                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
                // When intents are compared, the extras are ignored, so embed
                // the extra sinto the data so that the extras are not ignored.
                data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))
            }
            val rv = RemoteViews(context.packageName, R.layout.widget_layout).apply {
                setRemoteAdapter(R.id.stack_view, intent)

                // The empty view is displayed when the collection has no items.
                // It must be a sibling of the collection view.
                setEmptyView(R.id.stack_view, R.id.empty_view)
            }

            // This section makes it possible for items to have individualized
            // behavior. It does this by setting up a pending intent template.
            // Individuals items of a collection can't set up their own pending
            // intents. Instead, the collection as a whole sets up a pending
            // intent template, and the individual items set a fillInIntent
            // to create unique behavior on an item-by-item basis.
            val toastPendingIntent: PendingIntent = Intent(
                    context,
                    StackWidgetProvider::class.java
            ).run {
                // Set the action for the intent.
                // When the user touches a particular view, it has the effect of
                // broadcasting TOAST_ACTION.
                action = TOAST_ACTION
                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
                data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))

                PendingIntent.getBroadcast(context, 0, this, PendingIntent.FLAG_UPDATE_CURRENT)
            }
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent)

            appWidgetManager.updateAppWidget(appWidgetId, rv)
        }
        super.onUpdate(context, appWidgetManager, appWidgetIds)
    }
}

Java

public class StackWidgetProvider extends AppWidgetProvider {
    public static final String TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION";
    public static final String EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM";

    ...

    // Called when the BroadcastReceiver receives an Intent broadcast.
    // Checks whether the intent's action is TOAST_ACTION. If it is, the
    // widget displays a Toast message for the current item.
    @Override
    public void onReceive(Context context, Intent intent) {
        AppWidgetManager mgr = AppWidgetManager.getInstance(context);
        if (intent.getAction().equals(TOAST_ACTION)) {
            int appWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
            // EXTRA_ITEM represents a custom value provided by the Intent
            // passed to the setOnClickFillInIntent() method to indicate the
            // position of the clicked item. See StackRemoteViewsFactory in
            // Set the fill-in Intent for details.
            int viewIndex = intent.getIntExtra(EXTRA_ITEM, 0);
            Toast.makeText(context, "Touched view " + viewIndex, Toast.LENGTH_SHORT).show();
        }
        super.onReceive(context, intent);
    }

    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Update each of the widgets with the remote adapter.
        for (int i = 0; i < appWidgetIds.length; ++i) {

            // Sets up the intent that points to the StackViewService that
            // provides the views for this collection.
            Intent intent = new Intent(context, StackWidgetService.class);
            intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            // When intents are compared, the extras are ignored, so embed
            // the extras into the data so that the extras are not
            // ignored.
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
            rv.setRemoteAdapter(appWidgetIds[i], R.id.stack_view, intent);

            // The empty view is displayed when the collection has no items. It
            // must be a sibling of the collection view.
            rv.setEmptyView(R.id.stack_view, R.id.empty_view);

            // This section makes it possible for items to have individualized
            // behavior. It does this by setting up a pending intent template.
            // Individuals items of a collection can't set up their own pending
            // intents. Instead, the collection as a whole sets up a pending
            // intent template, and the individual items set a fillInIntent
            // to create unique behavior on an item-by-item basis.
            Intent toastIntent = new Intent(context, StackWidgetProvider.class);
            // Set the action for the intent.
            // When the user touches a particular view, it has the effect of
            // broadcasting TOAST_ACTION.
            toastIntent.setAction(StackWidgetProvider.TOAST_ACTION);
            toastIntent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            PendingIntent toastPendingIntent = PendingIntent.getBroadcast(context, 0, toastIntent,
                PendingIntent.FLAG_UPDATE_CURRENT);
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent);

            appWidgetManager.updateAppWidget(appWidgetIds[i], rv);
        }
        super.onUpdate(context, appWidgetManager, appWidgetIds);
    }
}

הגדרת הכוונה למלא את השדה

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

Kotlin

private const val REMOTE_VIEW_COUNT: Int = 10

class StackRemoteViewsFactory(
        private val context: Context,
        intent: Intent
) : RemoteViewsService.RemoteViewsFactory {

    private lateinit var widgetItems: List<WidgetItem>
    private val appWidgetId: Int = intent.getIntExtra(
            AppWidgetManager.EXTRA_APPWIDGET_ID,
            AppWidgetManager.INVALID_APPWIDGET_ID
    )

    override fun onCreate() {
        // In onCreate(), set up any connections or cursors to your data source.
        // Heavy lifting, such as downloading or creating content, must be
        // deferred to onDataSetChanged() or getViewAt(). Taking more than 20
        // seconds on this call results in an ANR.
        widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") }
        ...
    }
    ...

    override fun getViewAt(position: Int): RemoteViews {
        // Construct a remote views item based on the widget item XML file
        // and set the text based on the position.
        return RemoteViews(context.packageName, R.layout.widget_item).apply {
            setTextViewText(R.id.widget_item, widgetItems[position].text)

            // Set a fill-intent to fill in the pending intent template.
            // that is set on the collection view in StackWidgetProvider.
            val fillInIntent = Intent().apply {
                Bundle().also { extras ->
                    extras.putInt(EXTRA_ITEM, position)
                    putExtras(extras)
                }
            }
            // Make it possible to distinguish the individual on-click
            // action of a given item.
            setOnClickFillInIntent(R.id.widget_item, fillInIntent)
            ...
        }
    }
    ...
}

Java

public class StackWidgetService extends RemoteViewsService {
    @Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {
    private static final int count = 10;
    private List<WidgetItem> widgetItems = new ArrayList<WidgetItem>();
    private Context context;
    private int appWidgetId;

    public StackRemoteViewsFactory(Context context, Intent intent) {
        this.context = context;
        appWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
    }

    // Initialize the data set.
    public void onCreate() {
        // In onCreate(), set up any connections or cursors to your data
        // source. Heavy lifting, such as downloading or creating
        // content, must be deferred to onDataSetChanged() or
        // getViewAt(). Taking more than 20 seconds on this call results
        // in an ANR.
        for (int i = 0; i < count; i++) {
            widgetItems.add(new WidgetItem(i + "!"));
        }
        ...
    }

    // Given the position (index) of a WidgetItem in the array, use the
    // item's text value in combination with the widget item XML file to
    // construct a RemoteViews object.
    public RemoteViews getViewAt(int position) {
        // Position always ranges from 0 to getCount() - 1.

        // Construct a RemoteViews item based on the widget item XML
        // file and set the text based on the position.
        RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_item);
        rv.setTextViewText(R.id.widget_item, widgetItems.get(position).text);

        // Set a fill-intent to fill in the pending
        // intent template that is set on the collection view in
        // StackWidgetProvider.
        Bundle extras = new Bundle();
        extras.putInt(StackWidgetProvider.EXTRA_ITEM, position);
        Intent fillInIntent = new Intent();
        fillInIntent.putExtras(extras);
        // Make it possible to distinguish the individual on-click
        // action of a given item.
        rv.setOnClickFillInIntent(R.id.widget_item, fillInIntent);

        // Return the RemoteViews object.
        return rv;
    }
    ...
}

שמירה על עדכניות הנתונים של האוסף

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

איור 2. אינטראקציה עם RemoteViewsFactory במהלך עדכונים.

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

כדי לעשות זאת, משתמשים בפקודה AppWidgetManager כדי לקרוא לפונקציה notifyAppWidgetViewDataChanged(). הקריאה הזו מובילה לקריאה חוזרת (callback) ל-method‏ onDataSetChanged() של אובייקט RemoteViewsFactory, שמאפשרת לאחזר נתונים חדשים.

אפשר לבצע פעולות עיבוד עתירות בזמן סינכרוני בתוך הפונקציה החוזרת onDataSetChanged(). אפשר להבטיח שהקריאה הזו תושלם לפני שהמטא-נתונים או נתוני התצוגה יאוחזרו מה-RemoteViewsFactory. אפשר גם לבצע פעולות עיבוד עתירות בתוך השיטה getViewAt(). אם הקריאה הזו נמשכת זמן רב, תצוגת הטעינה – שצוינה על ידי השיטה getLoadingView() של האובייקט RemoteViewsFactory – תוצג במיקום המתאים בתצוגת האוסף עד שהיא תוחזר.

שימוש ב-RemoteCollectionItems כדי להעביר אוסף ישירות

ב-Android 12 (רמת API 31) נוספה השיטה setRemoteAdapter(int viewId, RemoteViews.RemoteCollectionItems items), שמאפשרת לאפליקציה להעביר אוסף ישירות כשמאכלסים תצוגת אוסף. אם מגדירים את המתאם באמצעות השיטה הזו, אין צורך להטמיע RemoteViewsFactory ואין צורך לבצע קריאה ל-notifyAppWidgetViewDataChanged().

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

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

דוגמה להטמעה של אוספים פשוטים של RemoteViews:

Kotlin

val itemLayouts = listOf(
        R.layout.item_type_1,
        R.layout.item_type_2,
        ...
)

remoteView.setRemoteAdapter(
        R.id.list_view,
        RemoteViews.RemoteCollectionItems.Builder()
            .addItem(/* id= */ ID_1, RemoteViews(context.packageName, R.layout.item_type_1))
            .addItem(/* id= */ ID_2, RemoteViews(context.packageName, R.layout.item_type_2))
            ...
            .setViewTypeCount(itemLayouts.count())
            .build()
)

Java

List<Integer> itemLayouts = Arrays.asList(
    R.layout.item_type_1,
    R.layout.item_type_2,
    ...
);

remoteView.setRemoteAdapter(
    R.id.list_view,
    new RemoteViews.RemoteCollectionItems.Builder()
        .addItem(/* id= */ ID_1, new RemoteViews(context.getPackageName(), R.layout.item_type_1))
        .addItem(/* id= */ ID_2, new RemoteViews(context.getPackageName(), R.layout.item_type_2))
        ...
        .setViewTypeCount(itemLayouts.size())
        .build()
);