Widgethost erstellen

Auf dem Android-Startbildschirm, der auf den meisten Android-Geräten verfügbar ist, können Nutzer App-Widgets (Widgets) einbetten, um schnell auf Inhalte zuzugreifen. Wenn du eine App entwickelst, die den Startbildschirm ersetzt oder eine ähnliche Funktion hat, kannst du Nutzern auch das Einbetten von Widgets ermöglichen, indem du AppWidgetHost implementierst. Das ist für die meisten Apps nicht erforderlich. Wenn du jedoch einen eigenen Host erstellst, musst du die vertraglichen Verpflichtungen kennen, denen ein Host implizit zustimmt.

Auf dieser Seite werden die Verantwortlichkeiten beschrieben, die mit der Implementierung eines benutzerdefinierten AppWidgetHost verbunden sind. Ein konkretes Beispiel für die Implementierung eines AppWidgetHost, findest du im Quellcode für den Android-Startbildschirm LauncherAppWidgetHost.

Hier ist eine Übersicht der wichtigsten Klassen und Konzepte, die bei der Implementierung eines benutzerdefinierten AppWidgetHost eine Rolle spielen:

  • App-Widget-Host: Der AppWidgetHost ermöglicht die Interaktion mit dem AppWidget-Dienst für Apps, die Widgets in ihre Benutzeroberfläche einbetten. Ein AppWidgetHost muss eine ID haben, die innerhalb des eigenen Pakets des Hosts eindeutig ist. Diese ID bleibt bei allen Verwendungen des Hosts bestehen. Die ID ist in der Regel ein fest codierter Wert, den du in deiner App zuweist.

  • App-Widget-ID: Jeder Widget-Instanz wird zum Zeitpunkt der Bindung eine eindeutige ID zugewiesen. Weitere Informationen findest du unter bindAppWidgetIdIfAllowed() und im folgenden Abschnitt Widgets binden. Der Host ruft die eindeutige ID mit allocateAppWidgetId() ab. Diese ID bleibt während der gesamten Lebensdauer des Widgets bestehen, bis es vom Host gelöscht wird. Alle hostspezifischen Status, z. B. Größe und Position des Widgets, müssen vom Hosting-Paket beibehalten und mit der App-Widget-ID verknüpft werden.

  • App-Widget-Hostansicht: Stelle dir AppWidgetHostView als einen Rahmen vor in den das Widget eingebettet wird, wenn es angezeigt werden muss. Ein Widget wird jedes Mal mit einem AppWidgetHostView verknüpft, wenn es vom Host aufgeblasen wird.

    • Standardmäßig erstellt das System ein AppWidgetHostView. Der Host kann jedoch eine eigene abgeleitete Klasse von AppWidgetHostView erstellen, indem er sie erweitert.
    • Ab Android 12 (API-Level 31) werden in AppWidgetHostView die Methoden setColorResources() und resetColorResources() eingeführt, um dynamisch überladene Farben zu verarbeiten. Der Host ist dafür verantwortlich, die Farben für diese Methoden bereitzustellen.

  • Options-Bundle: Der AppWidgetHost verwendet das Options-Bundle, um Informationen an den AppWidgetProvider zu senden, wie das Widget angezeigt wird, z. B. die Liste der Größenbereiche—und ob sich das Widget auf einem Sperrbildschirm oder dem Startbildschirm befindet. Mit diesen Informationen kann der AppWidgetProvider die Inhalte und das Erscheinungsbild des Widgets anpassen, je nachdem, wie und wo es angezeigt wird. Mit updateAppWidgetOptions() und updateAppWidgetSize() kannst du das Bundle eines Widgets ändern. Beide Methoden lösen den onAppWidgetOptionsChanged() Callback für den AppWidgetProvider aus.

Widgets binden

Wenn ein Nutzer einem Host ein Widget hinzufügt, findet ein Prozess statt, der als Bindung bezeichnet wird. Bei der Bindung wird eine bestimmte App-Widget-ID mit einem bestimmten Host und einem bestimmten AppWidgetProvider verknüpft.

Mit den Binding-APIs kann ein Host auch eine benutzerdefinierte Benutzeroberfläche für die Bindung bereitstellen. Damit dieser Prozess verwendet werden kann, muss deine App die BIND_APPWIDGET Berechtigung im Manifest des Hosts deklarieren:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

Allerdings ist das nur der erste Schritt. Zur Laufzeit muss der Nutzer deiner App explizit die Berechtigung erteilen, ein Widget zum Host hinzuzufügen. Mit der Methode bindAppWidgetIdIfAllowed() kannst du testen, ob deine App die Berechtigung zum Hinzufügen des Widgets hat. Wenn bindAppWidgetIdIfAllowed() false zurückgibt, muss deine App ein Dialogfeld anzeigen, in dem der Nutzer aufgefordert wird, die Berechtigung zu erteilen: „Zulassen“ für das aktuelle Hinzufügen des Widgets oder „Immer zulassen“ für alle zukünftigen Widget-Hinzufügungen.

Dieses Snippet zeigt ein Beispiel für die Anzeige des Dialogfelds:

Kotlin

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)

Java

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

Der Host muss prüfen, ob das Widget, das ein Nutzer hinzufügt, konfiguriert werden muss. Weitere Informationen findest du unter Nutzern das Konfigurieren von App Widgets.

Verantwortlichkeiten des Hosts

Mit den Metadaten AppWidgetProviderInfo kannst du eine Reihe von Konfigurationseinstellungen für Widgets festlegen. Diese Konfigurationsoptionen, die in den folgenden Abschnitten ausführlicher behandelt werden, kannst du aus dem AppWidgetProviderInfo Objekt abrufen, das mit einem Widget-Anbieter verknüpft ist.

Unabhängig von der Android-Version, auf die du abzielst, haben alle Hosts die folgenden Verantwortlichkeiten:

  • Weise beim Hinzufügen eines Widgets die Widget-ID wie oben beschrieben zu. Wenn ein Widget vom Host entfernt wird, rufe deleteAppWidgetId() auf, um die Zuweisung der Widget-ID aufzuheben.

  • Prüfe beim Hinzufügen eines Widgets, ob die Konfigurationsaktivität gestartet werden muss. In der Regel muss der Host die Konfigurationsaktivität des Widgets starten, wenn sie vorhanden ist und nicht als optional gekennzeichnet ist, indem sowohl das Flag configuration_optional als auch das Flag reconfigurable angegeben wird. Weitere Informationen findest du unter Widget über die Konfigurationsaktivität aktualisieren. Dieser Schritt ist für viele Widgets erforderlich, bevor sie angezeigt werden können.

  • In den Metadaten AppWidgetProviderInfo wird eine Standardbreite und ‑höhe für Widgets angegeben. Diese Werte werden in Zellen definiert. Ab Android 12 werden targetCellWidth und targetCellHeight angegeben. Wenn nur minWidth und minHeight angegeben sind, werden die Werte in dp definiert. Weitere Informationen findest du unter Attribute für die Widget-Größe.

    Das Widget muss mindestens so viele dp haben. Viele Hosts richten beispielsweise Symbole und Widgets in einem Raster aus. In diesem Fall fügt der Host standardmäßig ein Widget mit der Mindestanzahl an Zellen hinzu, die die Einschränkungen minWidth und minHeight erfüllen.

Zusätzlich zu den Anforderungen im vorherigen Abschnitt führen bestimmte Plattformversionen Funktionen ein, die neue Verantwortlichkeiten für den Host mit sich bringen.

Ansatz anhand der Ziel-Android-Version bestimmen

Android 12

Android 12 (API-Level 31) enthält eine zusätzliche List<SizeF>, die die Liste der möglichen Größen in dp enthält, die eine Widget-Instanz im Options-Bundle annehmen kann. Die Anzahl der bereitgestellten Größen hängt von der Host-Implementierung ab. Hosts bieten in der Regel zwei Größen für Smartphones (Hoch- und Querformat) und vier Größen für faltbare Geräte.

Die Anzahl der verschiedenen RemoteViews, die ein AppWidgetProvider für RemoteViews bereitstellen kann, ist auf MAX_INIT_VIEW_COUNT (16) begrenzt. Da AppWidgetProvider-Objekte ein RemoteViews-Objekt jeder Größe in der List<SizeF> zuordnen, solltest du nicht mehr als MAX_INIT_VIEW_COUNT Größen angeben.

Android 12 führt auch die maxResizeWidth und maxResizeHeight Attribute in dp ein. Wir empfehlen, dass ein Widget, das mindestens eines dieser Attribute verwendet, die durch die Attribute angegebene Größe nicht überschreitet.

Zusätzliche Ressourcen

  • Weitere Informationen findest du in der Glance Referenzdokumentation.