Widgethost erstellen

Auf dem Android-Startbildschirm, der auf den meisten Android-Geräten verfügbar ist, können Nutzer App-Widgets (oder Widgets) einbetten, um schnell auf Inhalte zuzugreifen. Wenn Sie einen Ersatz für den Startbildschirm oder eine ähnliche App entwickeln, können Sie Nutzern auch erlauben, Widgets einzubetten, indem Sie AppWidgetHost implementieren. Das ist für die meisten Apps nicht erforderlich. Wenn Sie jedoch Ihren eigenen Host erstellen, ist es wichtig, die vertraglichen Verpflichtungen zu kennen, denen ein Host implizit zustimmt.

Auf dieser Seite geht es um die Aufgaben, die mit der Implementierung einer benutzerdefinierten AppWidgetHost verbunden sind. Ein konkretes Beispiel für die Implementierung einer AppWidgetHost finden Sie im Quellcode für den Android-Startbildschirm LauncherAppWidgetHost.

Hier finden Sie einen Überblick über die wichtigsten Klassen und Konzepte, die bei der Implementierung einer 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. Eine AppWidgetHost muss eine ID haben, die innerhalb des eigenen Pakets des Hosts eindeutig ist. Diese ID bleibt bei allen Verwendungen des Hosts erhalten. Die ID ist in der Regel ein hartcodierter Wert, den Sie in Ihrer App zuweisen.

• App-Widget-ID: Jede Widget-Instanz erhält bei der Bindung eine eindeutige ID. Weitere Informationen finden Sie unter bindAppWidgetIdIfAllowed() und im folgenden Abschnitt Widgets binden. Der Host erhält die eindeutige ID über allocateAppWidgetId(). Diese ID bleibt während der gesamten Lebensdauer des Widgets bestehen, bis sie vom Host gelöscht wird. Alle hostspezifischen Status, z. B. Größe und Position des Widgets, müssen vom Hosting-Paket gespeichert und mit der App-Widget-ID verknüpft werden.

• App-Widget-Host-Ansicht: Betrachten Sie AppWidgetHostView als Frame, in dem das Widget eingewickelt wird, wenn es angezeigt werden muss. Jedes Mal, wenn das Widget vom Host maximiert wird, wird ihm ein AppWidgetHostView zugewiesen.

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

• Options-Bundle: Die AppWidgetHost verwendet das Options-Bundle, um Informationen zur Darstellung des Widgets an die AppWidgetProvider zu senden, z. B. die Liste der Größenbereiche und ob sich das Widget auf dem Sperr- oder dem Startbildschirm befindet. Anhand dieser Informationen kann AppWidgetProvider den Inhalt und die Darstellung des Widgets an die Art und Weise anpassen, wie und wo es angezeigt wird. Sie können updateAppWidgetOptions() und updateAppWidgetSize() verwenden, um das Bundle eines Widgets zu ändern. Beide Methoden lösen den Callback onAppWidgetOptionsChanged() an die AppWidgetProvider aus.

Widgets binden

Wenn ein Nutzer einem Host ein Widget hinzufügt, wird ein Vorgang namens Bindung ausgeführt. Eine Bindung bezieht sich auf die Verknüpfung einer bestimmten App-Widget-ID mit einem bestimmten Host und einer bestimmten AppWidgetProvider.

Mit Bindungs-APIs kann ein Host auch eine benutzerdefinierte Benutzeroberfläche für die Bindung bereitstellen. Damit Sie diesen Prozess verwenden können, muss Ihre App die Berechtigung BIND_APPWIDGET im Manifest des Hosts angeben:

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

Das ist aber erst der erste Schritt. Der Nutzer muss Ihrer App bei der Laufzeit explizit die Berechtigung erteilen, dem Host ein Widget hinzuzufügen. Mit der Methode bindAppWidgetIdIfAllowed() können Sie prüfen, ob Ihre App die Berechtigung zum Hinzufügen des Widgets hat. Wenn bindAppWidgetIdIfAllowed() false zurückgibt, muss Ihre App einen Dialog anzeigen, in dem der Nutzer aufgefordert wird, die Berechtigung zu gewähren: „Zulassen“ für das aktuelle Widget oder „Immer zulassen“ für alle zukünftigen Widgets.

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

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)

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 von einem Nutzer hinzugefügte Widget konfiguriert werden muss. Weitere Informationen finden Sie unter Nutzern das Konfigurieren von App-Widgets ermöglichen.

Verantwortlichkeiten des Hosts

Mithilfe der AppWidgetProviderInfo-Metadaten können Sie eine Reihe von Konfigurationseinstellungen für Widgets angeben. Diese Konfigurationsoptionen, die in den folgenden Abschnitten näher beschrieben werden, können Sie aus dem AppWidgetProviderInfo-Objekt abrufen, das mit einem Widget-Anbieter verknüpft ist.

Unabhängig von der Android-Version, auf die Sie Ihre App ausrichten, haben alle Hosts die folgenden Aufgaben:

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

• Prüfen Sie beim Hinzufügen eines Widgets, ob die Konfigurationsaktivität gestartet werden muss. Normalerweise muss der Host die Konfigurationsaktivität des Widgets starten, wenn es vorhanden ist und nicht als optional gekennzeichnet ist. Dazu müssen sowohl das Flag configuration_optional als auch das Flag reconfigurable angegeben werden. Weitere Informationen finden Sie unter Widget über die Konfigurationsaktivität aktualisieren. Dies ist für viele Widgets ein notwendiger Schritt, bevor sie angezeigt werden können.

• Für Widgets werden in den AppWidgetProviderInfo-Metadaten eine Standardbreite und -höhe angegeben. Diese Werte werden in Zellen definiert – ab Android 12, wenn targetCellWidth und targetCellHeight angegeben sind, oder in dps, wenn nur minWidth und minHeight angegeben sind. Weitere Informationen finden Sie unter Attribute für die Größe von Widgets.

  Das Widget muss mindestens diese Größe haben. Viele Hosts richten Symbole und Widgets beispielsweise in einem Raster aus. In diesem Szenario fügt der Host standardmäßig das Widget mit der Mindestanzahl von Zellen hinzu, die die Einschränkungen minWidth und minHeight erfüllen.

Zusätzlich zu den im vorherigen Abschnitt aufgeführten Anforderungen werden mit bestimmten Plattformversionen Funktionen eingeführt, die dem Host neue Aufgaben auferlegen.

Ansatz anhand der anvisierten Android-Version festlegen

Android 12

Android 12 (API-Level 31) enthält ein zusätzliches List<SizeF> mit einer Liste der möglichen Größen in dps, die eine Widget-Instanz im Options-Bundle haben kann. Die Anzahl der bereitgestellten Größen hängt von der Hostimplementierung ab. Hosts stellen in der Regel zwei Größen für Smartphones bereit – 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 jeder Größe in der List<SizeF> ein RemoteViews-Objekt zuordnen, sollten Sie nicht mehr als MAX_INIT_VIEW_COUNT Größen angeben.

Mit Android 12 werden in den dynamischen Preisvergleichsportalen auch die Attribute maxResizeWidth und maxResizeHeight eingeführt. Wir empfehlen, dass ein Widget, das mindestens eines dieser Attribute verwendet, die durch die Attribute angegebene Größe nicht überschreitet.

Weitere Informationen

• Weitere Informationen finden Sie in der Referenzdokumentation zu Glance.