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 eine App entwickeln, die den Startbildschirm ersetzt, oder eine ähnliche App, können Sie dem Nutzer auch erlauben, Widgets einzubetten, indem Sie AppWidgetHost implementieren. Das ist für die meisten Apps nicht erforderlich. Wenn Sie jedoch einen eigenen Host erstellen, ist es wichtig, die vertraglichen Verpflichtungen zu kennen, denen ein Host implizit zustimmt.

Auf dieser Seite geht es um die Verantwortlichkeiten, die mit der Implementierung eines 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 eine Übersicht über die wichtigsten Klassen und Konzepte, die bei der Implementierung eines benutzerdefinierten AppWidgetHost eine Rolle spielen:

• App-Widget-Host: Der AppWidgetHost bietet 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 hartcodierter Wert, den Sie in Ihrer App zuweisen.

• App-Widget-ID: Jeder Widget-Instanz wird zum Zeitpunkt der Bindung eine eindeutige ID zugewiesen. Weitere Informationen finden Sie 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 der App-Widget-ID zugeordnet werden.

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

  • 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() zum Verarbeiten dynamisch überladener Farben eingeführt. Der Host ist dafür verantwortlich, die Farben für diese Methoden bereitzustellen.

• Optionsbundle: Das AppWidgetHost verwendet das Optionsbundle, um Informationen an das AppWidgetProvider zu senden, z. B. wie das Widget angezeigt wird (z. B. die Liste der Größenbereiche) und ob sich das Widget auf einem Sperrbildschirm oder dem Startbildschirm befindet. Anhand dieser Informationen kann AppWidgetProvider die Inhalte und das Erscheinungsbild des Widgets anpassen, je nachdem, wie und wo es angezeigt wird. Mit updateAppWidgetOptions() und updateAppWidgetSize() können Sie das Bundle eines Widgets ändern. Bei beiden Methoden wird der onAppWidgetOptionsChanged()-Callback für die AppWidgetProvider ausgelöst.

Widgets binden

Wenn ein Nutzer einem Host ein Widget hinzufügt, wird ein Prozess namens Binding ausgeführt. Mit „Binden“ ist das Verknüpfen einer bestimmten App-Widget-ID mit einem bestimmten Host und einem bestimmten AppWidgetProvider gemeint.

Über Binding-APIs kann ein Host auch eine benutzerdefinierte Benutzeroberfläche für das Binden bereitstellen. Damit Sie dieses Verfahren verwenden können, muss in der Manifestdatei der Host-App die Berechtigung BIND_APPWIDGET deklariert werden:

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

Das ist aber nur der erste Schritt. Zur Laufzeit muss der Nutzer Ihrer App explizit die Berechtigung erteilen, dem Host ein Widget hinzuzufügen. Mit der Methode bindAppWidgetIdIfAllowed() können Sie testen, ob Ihre App die Berechtigung zum Hinzufügen des Widgets hat. Wenn bindAppWidgetIdIfAllowed() false zurückgibt, muss in Ihrer App ein Dialogfeld angezeigt werden, 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-Ergänzungen.

Dieses Snippet zeigt ein Beispiel dafür, wie das Dialogfeld angezeigt wird:

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 Widget, das ein Nutzer hinzufügt, konfiguriert werden muss. Weitere Informationen finden Sie unter Nutzern ermöglichen, App-Widgets zu konfigurieren.

Verantwortlichkeiten des Hosts

Sie können eine Reihe von Konfigurationseinstellungen für Widgets mit den AppWidgetProviderInfo-Metadaten angeben. Sie können diese Konfigurationsoptionen, die in den folgenden Abschnitten genauer beschrieben werden, aus dem AppWidgetProviderInfo-Objekt abrufen, das einem Widget-Anbieter zugeordnet ist.

Unabhängig von der Android-Version, die Sie als Zielgruppe festlegen, 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, rufen Sie deleteAppWidgetId() auf, um die Widget-ID freizugeben.

• 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 sie vorhanden ist und nicht als optional gekennzeichnet ist. Dazu müssen sowohl die Flags configuration_optional als auch 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.

• Widgets geben in den AppWidgetProviderInfo-Metadaten eine Standardbreite und ‑höhe an. 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 Widget-Größe.

  Das Widget muss mindestens so viele DPs breit sein. Viele Hosts richten Symbole und Widgets beispielsweise in einem Raster aus. In diesem Szenario fügt der Host standardmäßig ein 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 neue Verantwortlichkeiten für den Host mit sich bringen.

Ansatz basierend auf der Ziel-Android-Version festlegen

Android 12

Android 12 (API-Level 31) enthält ein zusätzliches List<SizeF>, das die Liste der möglichen Größen in dps enthält, die eine Widget-Instanz im Options-Bundle annehmen kann. Die Anzahl der bereitgestellten Größen hängt von der Hostimplementierung ab. In der Regel stellen Hosts zwei Größen für Smartphones (Hoch- und Querformat) und vier Größen für Falt-Smartphones bereit.

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 im List<SizeF> zuordnen, dürfen Sie nicht mehr als MAX_INIT_VIEW_COUNT Größen angeben.

In Android 12 werden auch die Attribute maxResizeWidth und maxResizeHeight in dps eingeführt. 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 finden Sie in der Referenzdokumentation zu Glance.