Sammlungs-Widgets sind auf die Darstellung vieler Elemente desselben Typs spezialisiert, 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 in der Detailansicht. Sammlungs-Widgets können vertikal scrollen.
Diese Widgets verwenden RemoteViewsService, um Sammlungen anzuzeigen, die durch Remotedaten gestützt werden, z. B. von einem Contentanbieter. Das Widget präsentiert die Daten mithilfe eines der folgenden Ansichtstypen, die als Sammlungsansichten bezeichnet werden:
ListView- Eine Ansicht, in der Elemente in einer vertikal scrollbaren Liste angezeigt werden.
GridView- Eine Ansicht, in der Elemente in einem zweidimensionalen Scrollraster angezeigt werden.
StackView- Eine gestapelte Kartenansicht – vergleichbar wie bei einem Rolodex –, bei der der Nutzer die vordere Karte nach oben oder unten streichen kann, um die vorherige oder die nächste Karte aufzurufen.
AdapterViewFlipper- Ein adaptergestütztes einfaches
ViewAnimator, das zwischen zwei oder mehr Ansichten animiert. Es wird jeweils nur ein Kind angezeigt.
Da diese Sammlungsansichten Sammlungen anzeigen, die auf Remotedaten basieren, verwenden sie ein Adapter, um die Benutzeroberfläche an die Daten zu binden. Ein Adapter bindet einzelne Elemente aus einem Datensatz an einzelne View-Objekte.
Da diese Sammlungsansichten von Adaptern gestützt werden, muss das Android-Framework eine zusätzliche Architektur enthalten, die ihre Verwendung in Widgets unterstützt. Im Kontext eines Widgets wird Adapter durch RemoteViewsFactory ersetzt, bei dem es sich um einen Thin Wrapper um die Adapter-Schnittstelle handelt. Wenn ein bestimmtes Element in der Sammlung angefordert wird, erstellt das RemoteViewsFactory das Element für die Sammlung als RemoteViews-Objekt und gibt es zurück. Wenn Sie dem Widget eine Sammlungsansicht hinzufügen möchten, müssen Sie RemoteViewsService und RemoteViewsFactory implementieren.
RemoteViewsService ist ein Dienst, mit dem ein Remote-Adapter RemoteViews-Objekte anfordern kann. RemoteViewsFactory ist eine Schnittstelle für einen Adapter zwischen einer Sammlungsansicht wie ListView, GridView und StackView und den zugrunde liegenden Daten für diese Ansicht. Hier ein Beispiel für den Boilerplate-Code aus dem Beispiel StackWidget zum Implementieren 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 null bis neun angezeigt werden. Das Beispiel-Widget hat folgende primäre Verhaltensweisen:
Der Nutzer kann über die Draufsicht im Widget vertikal schwenken, um die nächste oder vorherige Ansicht aufzurufen. Dies ist ein integriertes
StackView-Verhalten.Ohne Nutzerinteraktion geht das Widget wie in einer Bildschirmpräsentation automatisch der Reihe nach durch die Ansichten. Das 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 Stapelansicht.Wenn der Nutzer die Draufsicht berührt, zeigt das Widget die
Toast-Meldung „Berührte Ansicht n“ an, wobei n der Index (Position) der Berührungsansicht 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 Widgets. Danach sind einige zusätzliche Schritte erforderlich: Ä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 Widgets mit Sammlungen an Ihre RemoteViewsService gebunden werden können. Dazu deklarieren Sie den Dienst in der Manifestdatei mit der Berechtigung BIND_REMOTEVIEWS.
Dadurch wird verhindert, dass andere Anwendungen ungehindert auf die Daten Ihres Widgets zugreifen.
Wenn Sie beispielsweise ein Widget erstellen, das RemoteViewsService zum Ausfüllen einer Sammlungsansicht verwendet, 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 an deine Widget-Layout-XML-Datei besteht darin, dass sie eine der folgenden 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, bei der die leere Ansicht einen leeren Zustand darstellt.
Erstellen Sie zusätzlich zur Layoutdatei für Ihr gesamtes 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 Element-Layoutdatei, widget_item.xml, da alle Elemente dasselbe Layout verwenden.
AppWidgetProvider-Klasse für Widgets mit Sammlungen
Wie bei normalen Widgets besteht der Großteil des Codes in der abgeleiteten AppWidgetProvider-Klasse normalerweise in onUpdate().
Der Hauptunterschied bei der Implementierung von onUpdate() beim Erstellen eines Widgets mit Sammlungen besteht darin, dass setRemoteAdapter() aufgerufen werden muss. So erfahren Sie, wo die Daten der Sammlung abgerufen werden können.
RemoteViewsService kann dann deine Implementierung von RemoteViewsFactory zurückgeben und das Widget kann die entsprechenden Daten bereitstellen. Übergeben Sie beim Aufrufen dieser Methode einen Intent, der auf Ihre Implementierung von RemoteViewsService und die Widget-ID verweist, die das zu aktualisierende Widget angibt.
Im Beispiel StackWidget wird beispielsweise die Callback-Methode onUpdate() implementiert, um RemoteViewsService als Remoteadapter 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 Klasse RemoteViewsService den RemoteViewsFactory bereit, der zum Ausfüllen der Remote-Sammlungsansicht verwendet wird.
Führen Sie insbesondere folgende 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, für jedes Element im Dataset einRemoteViews-Objekt zu erstellen. Diese Schnittstelle ist ein Thin Wrapper umAdapter.
Sie können sich nicht darauf verlassen, dass eine einzelne Instanz Ihres Dienstes oder die darin enthaltenen Daten bestehen bleiben. Speichere keine Daten in deinem RemoteViewsService, es sei denn, sie sind statisch. Wenn die Daten Ihres Widgets bestehen bleiben sollen, verwenden Sie am besten einen ContentProvider, dessen Daten über den Prozesslebenszyklus hinaus erhalten bleiben. Ein Lebensmittelgeschäft-Widget kann beispielsweise den Status jedes Einkaufslistenelements an einem nichtflüchtigen Speicherort wie einer SQL-Datenbank speichern.
Der Hauptinhalt der RemoteViewsService-Implementierung ist ihr RemoteViewsFactory, wie im folgenden Abschnitt beschrieben.
RemoteViewsFactory-Schnittstelle
Ihre benutzerdefinierte Klasse, die die RemoteViewsFactory-Schnittstelle implementiert, liefert dem Widget die Daten für die Elemente in der Sammlung. Dazu wird die XML-Layoutdatei des Widget-Elements mit einer Datenquelle kombiniert. Bei dieser Datenquelle kann es sich um eine Datenbank oder ein einfaches Array handeln. Im Beispiel StackWidget ist die Datenquelle ein Array von WidgetItems. RemoteViewsFactory fungiert als Adapter, mit dem die Daten mit der Remote-Sammlungsansicht verknüpft werden.
Die beiden wichtigsten Methoden, die Sie für Ihre abgeleitete RemoteViewsFactory-Klasse implementieren müssen, sind onCreate() und getViewAt().
Beim erstmaligen Erstellen Ihrer Factory ruft das System onCreate() auf.
Hier richten Sie alle Verbindungen oder Cursors zur 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 Methode onCreate() 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 am angegebenen 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 für einzelne Elemente hinzufügen
In den vorherigen Abschnitten wird gezeigt, wie Sie Ihre Daten an Ihre Widget-Sammlung binden. Aber was ist, wenn Sie den einzelnen Elementen in der Sammlungsansicht dynamisches Verhalten hinzufügen möchten?
Wie im Abschnitt Ereignisse mit der Klasse onUpdate() verarbeiten beschrieben, verwenden Sie normalerweise setOnClickPendingIntent(), um das Klickverhalten eines Objekts festzulegen, z. B. um eine Schaltfläche zum Starten eines Activity zu starten. Dieser Ansatz ist jedoch für untergeordnete Ansichten in einem einzelnen Sammlungselement nicht zulässig.
Sie können beispielsweise setOnClickPendingIntent() verwenden, um eine globale Schaltfläche im Gmail-Widget einzurichten, über die die App beispielsweise gestartet wird, aber nicht für die einzelnen Listenelemente.
Wenn Sie ein Klickverhalten für einzelne Elemente in einer Sammlung hinzufügen möchten, verwenden Sie stattdessen setOnClickFillInIntent(). Dazu müssen Sie eine ausstehende Intent-Vorlage für die Sammlungsansicht einrichten und dann über RemoteViewsFactory einen Fill-In-Intent für jedes Element in der Sammlung festlegen.
In diesem Abschnitt wird anhand des StackWidget-Beispiels beschrieben, wie Sie einzelnen Elementen Verhalten hinzufügen. 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ührungsansicht ist. So funktioniert's:
StackWidgetProvider– eine abgeleiteteAppWidgetProvider-Klasse – erstellt einen ausstehenden Intent mit einer benutzerdefinierten Aktion namensTOAST_ACTION.Wenn der Nutzer eine Ansicht berührt, wird der Intent ausgelöst und es wird
TOAST_ACTIONgesendet.Diese Übertragung wird von der Methode
onReceive()der KlasseStackWidgetProviderabgefangen und das Widget zeigt die NachrichtToastfür die berührte Ansicht an. Die Daten für die Sammlungselemente werden vonRemoteViewsFactoryüberRemoteViewsServicebereitgestellt.
Ausstehende Intent-Vorlage einrichten
StackWidgetProvider (eine abgeleitete AppWidgetProvider-Klasse) richtet einen ausstehenden Intent ein. Einzelne Elemente einer Sammlung können keine eigenen ausstehenden Intents einrichten. Stattdessen richtet die Sammlung als Ganzes eine ausstehende Intent-Vorlage ein und die einzelnen Elemente legen einen Ausführungs-Intent fest, um ein individuelles Verhalten auf Elementbasis zu erzeugen.
Diese Klasse empfängt auch die Übertragung, die gesendet wird, wenn der Nutzer eine Ansicht berührt. Dieses Ereignis wird in der Methode onReceive() verarbeitet. Wenn die Aktion des Intents TOAST_ACTION lautet, 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
Mit RemoteViewsFactory muss für jedes Element in der Sammlung ein Fill-in-Intent festgelegt werden. So lässt sich die einzelne Klickaktion eines bestimmten Elements unterscheiden. Der Intent für das Ausfüllen wird dann mit der Vorlage PendingIntent kombiniert, um den endgültigen Intent zu ermitteln, 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 zeigt den Aktualisierungsfluss in einem Widget, das Sammlungen verwendet. Es wird gezeigt, 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 liefern. Das Gmail-Widget zeigt Nutzern beispielsweise eine Momentaufnahme ihres Posteingangs. Dazu lösen Sie die RemoteViewsFactory- und Sammlungsansicht aus, um neue Daten abzurufen und anzuzeigen.
Verwenden Sie dazu den 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.
Verarbeitungsintensive Vorgänge lassen sich synchron innerhalb des onDataSetChanged()-Callbacks ausführen. Dieser Aufruf wird garantiert abgeschlossen, bevor die Metadaten oder Ansichtsdaten aus RemoteViewsFactory abgerufen werden. Verarbeitungsintensive Vorgänge lassen sich auch innerhalb der Methode getViewAt() ausführen. Wenn dieser Aufruf lange dauert, wird die durch die Methode getLoadingView() des RemoteViewsFactory-Objekts angegebene Ladeansicht an der entsprechenden Position der Sammlungsansicht angezeigt, bis sie zurückgegeben wird.
Mit RemoteCollectionItems eine Sammlung direkt übergeben
Unter Android 12 (API-Level 31) wird die Methode setRemoteAdapter(int viewId,
RemoteViews.RemoteCollectionItems
items) hinzugefügt, mit der Ihre App eine Sammlung direkt übergeben kann, wenn eine Sammlungsansicht gefüllt wird. Wenn Sie den Adapter mit dieser Methode festlegen, müssen Sie kein RemoteViewsFactory implementieren und notifyAppWidgetViewDataChanged() nicht aufrufen.
Dieser Ansatz erleichtert nicht nur das Füllen des Adapters, sondern verringert auch die Latenz beim Ausfüllen neuer Elemente, wenn Nutzer in der Liste nach unten scrollen, um ein neues Element zu sehen. Diese Methode zum Einstellen des Adapters ist zu empfehlen, solange die Sammlung relativ klein ist. Dieser Ansatz funktioniert jedoch nicht gut, wenn Ihre Sammlung zahlreiche Bitmaps enthält, die an setImageViewBitmap übergeben werden.
Wenn die Sammlung keinen festen Satz von Layouts verwendet, also einige Elemente nur manchmal vorhanden sind, verwenden Sie setViewTypeCount, um die maximale Anzahl eindeutiger Layouts anzugeben, die die Sammlung enthalten kann. So kann der Adapter bei Updates deines App-Widgets wiederverwendet werden.
Hier ein Beispiel für die Implementierung von vereinfachten 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()
);