Sammlungs-Widgets sind darauf spezialisiert, viele Elemente desselben Typs anzuzeigen, z. B. Bildersammlungen aus einer Galerie-App, Artikel aus einer Nachrichten-App oder Nachrichten aus einer Kommunikations-App. Sammlungs-Widgets konzentrieren sich in der Regel auf zwei Anwendungsfälle: das Durchsuchen der Sammlung und das Öffnen eines Elements der Sammlung für die Detailansicht. Sammlungs-Widgets können vertikal scrollen.
In diesen Widgets wird RemoteViewsService verwendet, um Sammlungen anzuzeigen, die durch Remotedaten gestützt werden, z. B. von einem Contentanbieter. Im Widget werden die Daten in einem der folgenden Ansichtstypen dargestellt, die als Sammlungsansichten bezeichnet werden:
ListView- Eine Ansicht, in der Elemente in einer vertikal scrollbaren Liste zu sehen sind.
GridView- Eine Ansicht, in der Elemente in einem zweidimensionalen Scrollraster angezeigt werden.
StackView- Eine gestapelte Kartenansicht – ähnlich wie ein Roolodex –, bei der der Nutzer die vordere Karte nach oben oder unten bewegt, um die vorherige bzw. die nächste Karte zu sehen.
AdapterViewFlipper- Ein auf einem Adapter basierendes einfaches
ViewAnimator, das zwischen zwei oder mehr Ansichten animiert. Es wird jeweils nur ein Kind angezeigt.
Da in diesen Sammlungsansichten Sammlungen angezeigt werden, die von Remotedaten unterstützt werden, verwenden sie ein Adapter, um die Benutzeroberfläche an ihre Daten zu binden. Ein Adapter bindet einzelne Elemente aus einem Datensatz an einzelne View-Objekte.
Da diese Sammlungsansichten von Adaptern unterstützt werden, muss das Android-Framework eine zusätzliche Architektur enthalten, um die Verwendung in Widgets zu unterstützen. Im Kontext eines Widgets wird Adapter durch RemoteViewsFactory ersetzt, bei dem es sich um einen dünnen Wrapper um die Adapter-Schnittstelle handelt. Bei Anfrage für ein bestimmtes Element in der Sammlung erstellt RemoteViewsFactory das Element für die Sammlung und gibt es als RemoteViews-Objekt zurück. Wenn Sie eine Sammlungsansicht in Ihr Widget aufnehmen möchten, implementieren Sie RemoteViewsService und RemoteViewsFactory.
RemoteViewsService ist ein Dienst, mit dem ein Remote-Adapter RemoteViews-Objekte anfordern kann. RemoteViewsFactory ist eine Schnittstelle für einen Adapter zwischen einer Sammlungsansicht (z. B. ListView, GridView und StackView) und den zugrunde liegenden Daten für diese Ansicht. Im StackWidget-Beispiel sehen Sie ein Beispiel für den Boilerplate-Code zur Implementierung dieses Dienstes und dieser Schnittstelle:
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.
}
Beispielanwendung
Die Codeauszüge in diesem Abschnitt stammen ebenfalls aus dem StackWidget-Beispiel:
StackWidget.Dieses Beispiel besteht aus einem Stapel von zehn Ansichten, in denen die Werte von null bis neun angezeigt werden. Das Beispiel-Widget hat folgende Hauptfunktionen:
Der Nutzer kann die Draufsicht im Widget vertikal schieben, um die nächste oder vorherige Ansicht aufzurufen. Dies ist ein integriertes
StackView-Verhalten.Ohne Interaktion durch den Nutzer geht das Widget wie bei einer Bildschirmpräsentation automatisch nacheinander durch die Ansichten. Dies liegt an der Einstellung
android:autoAdvanceViewId="@id/stack_view"in der Dateires/xml/stackwidgetinfo.xml. Diese Einstellung gilt für die Ansichts-ID, in diesem Fall die Ansichts-ID der Stackansicht.Wenn der Nutzer die Draufsicht berührt, zeigt das Widget die Meldung
Toast„Berührte Ansicht n“ an, wobei n der Index (Position) der berührten Ansicht ist. Weitere Informationen zum Implementieren von Verhaltensweisen finden Sie im Abschnitt Verhalten zu einzelnen Elementen hinzufügen.
Widgets mit Sammlungen implementieren
Wenn Sie ein Widget mit Sammlungen implementieren möchten, folgen Sie der Anleitung zum Implementieren eines beliebigen Widgets. Führen Sie anschließend einige zusätzliche Schritte aus: Ändern Sie das Manifest, fügen Sie dem Widget-Layout eine Sammlungsansicht hinzu und ändern Sie die abgeleitete AppWidgetProvider-Klasse.
Manifest für Widgets mit Sammlungen
Zusätzlich zu den unter Widget im Manifest deklarieren aufgeführten Anforderungen müssen Sie dafür sorgen, dass Widgets mit Sammlungen an Ihre RemoteViewsService gebunden werden können. Deklarieren Sie dazu den Dienst in der Manifestdatei mit der Berechtigung BIND_REMOTEVIEWS.
Dadurch wird verhindert, dass andere Anwendungen ungehindert auf die Daten deines Widgets zugreifen.
Wenn Sie beispielsweise ein Widget erstellen, das mit RemoteViewsService eine Sammlungsansicht füllt, könnte der Manifesteintrag so aussehen:
<service android:name="MyWidgetService"
android:permission="android.permission.BIND_REMOTEVIEWS" />
In diesem Beispiel bezieht sich android:name="MyWidgetService" auf Ihre abgeleitete Klasse von RemoteViewsService.
Layout für Widgets mit Sammlungen
Die Hauptanforderung für die XML-Datei für das Widget-Layout besteht darin, dass sie eine der Sammlungsansichten enthält: ListView, GridView, StackView oder AdapterViewFlipper. Hier ist die Datei widget_layout.xml für das StackWidget-Beispiel:
<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>
Leere Ansichten müssen der Sammlungsansicht gleichgeordnet sein, deren leere Ansicht für den leeren Status steht.
Erstellen Sie zusätzlich zur Layoutdatei für das gesamte Widget eine weitere Layoutdatei, die das Layout für jedes Element in der Sammlung definiert, z. B. ein Layout für jedes Buch in einer Büchersammlung. Das Beispiel StackWidget enthält nur eine Layoutdatei für Elemente, widget_item.xml, da alle Elemente dasselbe Layout verwenden.
AppWidgetProvider-Klasse für Widgets mit Sammlungen
Wie bei normalen Widgets wird der Großteil des Codes in Ihrer AppWidgetProvider-Unterklasse normalerweise in onUpdate() eingefügt.
Der Hauptunterschied bei der Implementierung von onUpdate() beim Erstellen eines Widgets mit Sammlungen besteht darin, dass Sie setRemoteAdapter() aufrufen müssen. Dadurch weiß die Sammlungsansicht, wo ihre Daten abgerufen werden können.
Das RemoteViewsService kann dann Ihre Implementierung von RemoteViewsFactory zurückgeben und das Widget kann die entsprechenden Daten bereitstellen. Wenn Sie diese Methode aufrufen, übergeben Sie einen Intent, der auf Ihre Implementierung von RemoteViewsService und die Widget-ID verweist, die das zu aktualisierende Widget angibt.
So wird im StackWidget-Beispiel z. B. die Callback-Methode onUpdate() implementiert, um RemoteViewsService als Remote-Adapter für die Widget-Sammlung festzulegen:
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);
}
Daten beibehalten
Wie auf dieser Seite beschrieben, stellt die abgeleitete RemoteViewsService-Klasse das RemoteViewsFactory bereit, das zum Ausfüllen der Remote-Sammlungsansicht verwendet wird.
Führen Sie insbesondere die folgenden Schritte aus:
Abgeleitete Klasse
RemoteViewsService.RemoteViewsServiceist der Dienst, über den ein Remote-AdapterRemoteViewsanfordern kann.Fügen Sie in die abgeleitete
RemoteViewsService-Klasse eine Klasse ein, die dieRemoteViewsFactory-Schnittstelle implementiert.RemoteViewsFactoryist eine Schnittstelle für einen Adapter zwischen einer Remote-Sammlungsansicht (z. B.ListView,GridView,StackView) und den zugrunde liegenden Daten für diese Ansicht. Ihre Implementierung ist dafür verantwortlich, einRemoteViews-Objekt für jedes Element im Dataset zu erstellen. Diese Schnittstelle ist ein dünner Wrapper umAdapter.
Sie können sich nicht darauf verlassen, dass eine einzelne Instanz Ihres Dienstes oder die darin enthaltenen Daten dauerhaft bestehen. Speichern Sie keine Daten in Ihrem RemoteViewsService, es sei denn, sie sind statisch. Wenn die Daten Ihres Widgets erhalten bleiben sollen, verwenden Sie am besten eine ContentProvider, deren Daten über den Prozesslebenszyklus hinaus bestehen bleiben. Beispielsweise kann ein Lebensmittelgeschäfts-Widget den Status jedes Einkaufslistenartikels an einem nichtflüchtigen Speicherort wie einer SQL-Datenbank speichern.
Der Hauptinhalt der RemoteViewsService-Implementierung ist RemoteViewsFactory, der im folgenden Abschnitt beschrieben wird.
RemoteViewsFactory-Schnittstelle
Ihre benutzerdefinierte Klasse, die die RemoteViewsFactory-Schnittstelle implementiert, stellt dem Widget die Daten für die Elemente in der Sammlung bereit. Dazu wird die XML-Layoutdatei für Widget-Elemente mit einer Datenquelle kombiniert. Diese Datenquelle kann von einer Datenbank bis hin zu einem einfachen Array reichen. Im Beispiel StackWidget ist die Datenquelle ein Array von WidgetItems. RemoteViewsFactory dient als Adapter, um die Daten mit der Remote-Sammlungsansicht zu verknüpfen.
Die beiden wichtigsten Methoden, die Sie für Ihre abgeleitete RemoteViewsFactory-Klasse implementieren müssen, sind onCreate() und getViewAt().
Das System ruft onCreate() auf, wenn Ihre Fabrik zum ersten Mal erstellt wird.
Hier richten Sie alle Verbindungen oder Cursors zu Ihrer Datenquelle ein. Im Beispiel StackWidget wird beispielsweise onCreate() verwendet, um ein Array von WidgetItem-Objekten zu initialisieren. Wenn das Widget aktiv ist, greift das System anhand ihrer Indexposition im Array auf diese Objekte zu und zeigt den darin enthaltenen Text an.
Hier ist ein Auszug aus der RemoteViewsFactory-Implementierung des StackWidget-Beispiels, der Teile der onCreate()-Methode zeigt:
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 + "!"));
}
...
}
...
Die RemoteViewsFactory-Methode getViewAt() gibt ein RemoteViews-Objekt zurück, das den Daten unter position im Dataset entspricht. Hier ist ein Auszug aus der RemoteViewsFactory-Implementierung des StackWidget-Beispiels:
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;
}
Verhalten einzelner Elemente hinzufügen
In den vorherigen Abschnitten wird beschrieben, wie Sie Ihre Daten mit Ihrer Widget-Sammlung verknüpfen. Aber was ist, wenn Sie den einzelnen Elementen in der Sammlungsansicht dynamisches Verhalten hinzufügen möchten?
Wie unter Ereignisse mit der onUpdate()-Klasse beschrieben, verwenden Sie normalerweise setOnClickPendingIntent(), um das Klickverhalten eines Objekts festzulegen, z. B. um eine Schaltfläche zum Starten einer Activity zu veranlassen. Dieser Ansatz ist jedoch nicht für untergeordnete Ansichten in einem einzelnen Sammlungselement zulässig.
Sie können beispielsweise setOnClickPendingIntent() verwenden, um im Gmail-Widget eine globale Schaltfläche einzurichten, die beispielsweise die App startet, aber nicht für die einzelnen Listenelemente.
Wenn Sie einzelnen Elementen in einer Sammlung ein Klickverhalten hinzufügen möchten, verwenden Sie stattdessen setOnClickFillInIntent(). Dazu müssen Sie eine Vorlage für ausstehende Intents für die Sammlungsansicht einrichten und dann über Ihre RemoteViewsFactory einen Füll-Intent für jedes Element in der Sammlung festlegen.
In diesem Abschnitt wird anhand des Beispiels StackWidget beschrieben, wie einzelnen Elementen das Verhalten hinzugefügt wird. Wenn der Nutzer im Beispiel StackWidget die Draufsicht berührt, zeigt das Widget die Toast-Meldung „Berührte Ansicht n“ an, wobei n der Index (Position) der berührten Ansicht ist. So funktioniert's:
Von der
StackWidgetProvider– einer Unterklasse vom TypAppWidgetProvider– wird ein ausstehender Intent mit einer benutzerdefinierten Aktion namensTOAST_ACTIONerstellt.Wenn der Nutzer eine Ansicht berührt, wird der Intent ausgelöst und es wird
TOAST_ACTIONgesendet.Diese Übertragung wird von der Methode
onReceive()derStackWidgetProvider-Klasse abgefangen und das Widget zeigt die NachrichtToastfür die berührte Ansicht an. Die Daten für die Sammlungselemente werden vomRemoteViewsFactoryüber denRemoteViewsServicebereitgestellt.
Vorlage für ausstehende Intents einrichten
Die abgeleitete Klasse StackWidgetProvider (AppWidgetProvider) richtet einen ausstehenden Intent ein. Für einzelne Elemente einer Sammlung können keine eigenen ausstehenden Intents eingerichtet werden. Stattdessen richtet die Sammlung als Ganzes eine Vorlage für ausstehende Intents ein und die einzelnen Elemente legen einen Füll-Intent fest, um für jedes Element ein eindeutiges Verhalten zu erzeugen.
Diese Klasse empfängt auch den Broadcast, der gesendet wird, wenn der Nutzer eine Ansicht berührt. Dieses Ereignis wird in der Methode onReceive() verarbeitet. Wenn die Aktion des Intents TOAST_ACTION ist, zeigt das Widget eine Toast-Meldung für die aktuelle Ansicht an.
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);
}
}
Fill-in-Intent festlegen
Ihr RemoteViewsFactory muss für jedes Element in der Sammlung einen Füll-Intent festlegen. So kann die einzelne Klickaktion eines bestimmten Elements unterschieden werden. Der Eingabe-Intent wird dann mit der Vorlage PendingIntent kombiniert, um den endgültigen Intent zu bestimmen, der ausgeführt wird, wenn auf das Element getippt wird.
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;
}
...
}
Sammlungsdaten aktuell halten
Abbildung 2 veranschaulicht den Aktualisierungsablauf in einem Widget, das Sammlungen verwendet. Sie sehen, wie der Widgetcode mit dem RemoteViewsFactory interagiert und wie Sie Aktualisierungen auslösen können:
RemoteViewsFactory während Updates.Widgets, die Sammlungen verwenden, können Nutzern aktuelle Inhalte bieten. Über das Gmail-Widget erhalten Nutzer beispielsweise einen Überblick über ihren Posteingang. Dazu müssen Sie RemoteViewsFactory und die Sammlungsansicht auslösen, um neue Daten abzurufen und anzuzeigen.
Verwende dazu AppWidgetManager, um notifyAppWidgetViewDataChanged() aufzurufen. Dieser Aufruf führt zu einem Callback der Methode onDataSetChanged() des RemoteViewsFactory-Objekts, mit der Sie neue Daten abrufen können.
Sie können Verarbeitungsintensive Vorgänge synchron im onDataSetChanged()-Callback ausführen. Dieser Aufruf wird garantiert abgeschlossen, bevor die Metadaten oder Ansichtsdaten vom RemoteViewsFactory abgerufen werden. Sie können auch verarbeitungsintensive Vorgänge innerhalb der Methode getViewAt() ausführen. Wenn dieser Aufruf lange dauert, wird die durch die Methode getLoadingView() des RemoteViewsFactory-Objekts festgelegte Ladeansicht an der entsprechenden Position der Sammlungsansicht angezeigt, bis sie zurückgegeben wird.
Verwenden Sie RemoteCollectionItems, um eine Sammlung direkt zu übergeben.
In Android 12 (API-Level 31) wird die Methode setRemoteAdapter(int viewId,
RemoteViews.RemoteCollectionItems
items) hinzugefügt, mit der deine App eine Sammlung direkt übergeben kann, wenn sie eine Sammlungsansicht füllt. Wenn Sie den Adapter mit dieser Methode einrichten, müssen Sie keinen RemoteViewsFactory implementieren und nicht notifyAppWidgetViewDataChanged() aufrufen.
Mit diesem Ansatz wird nicht nur das Ausfüllen des Adapters vereinfacht, sondern auch die Latenz beim Ausfüllen neuer Elemente reduziert, wenn Nutzer in der Liste nach unten scrollen, um ein neues Element zu sehen. Dieser Ansatz zum Festlegen des Adapters ist zu bevorzugen, wenn Ihre Gruppe von Sammlungselementen relativ klein ist. Dieser Ansatz funktioniert jedoch beispielsweise nicht gut, wenn Ihre Sammlung zahlreiche Bitmaps enthält, die an setImageViewBitmap übergeben werden.
Wenn die Sammlung keinen konstanten Satz von Layouts verwendet – wenn also einige Elemente nur gelegentlich vorhanden sind –, verwenden Sie setViewTypeCount, um die maximale Anzahl eindeutiger Layouts anzugeben, die die Sammlung enthalten kann. Dadurch kann der Adapter für alle Updates deines App-Widgets wiederverwendet werden.
Hier ein Beispiel für die Implementierung vereinfachter RemoteViews-Sammlungen.
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()
);