Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

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 du einen Ersatz für den Startbildschirm oder eine ähnliche App entwickelst, kannst du Nutzern auch erlauben, Widgets einzubetten, indem du AppWidgetHost implementierst. Die meisten Apps müssen das nicht tun. Wenn Sie jedoch einen eigenen Host erstellen, ist es wichtig, die vertraglichen Verpflichtungen zu verstehen, denen ein Host implizit zustimmt.

Auf dieser Seite geht es um die Verantwortlichkeiten bei der Implementierung eines benutzerdefinierten AppWidgetHost. Ein konkretes Beispiel für die Implementierung eines AppWidgetHost finden Sie im Quellcode für den Android-Startbildschirm LauncherAppWidgetHost.

Hier finden Sie eine Übersicht über die wichtigsten Klassen und Konzepte, die für die Implementierung eines benutzerdefinierten AppWidgetHost erforderlich sind:

App-Widget-Host: 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 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: Jeder Widget-Instanz wird beim Binden eine eindeutige ID zugewiesen. Weitere Informationen finden Sie unter bindAppWidgetIdIfAllowed() und im Abschnitt Widgets binden unten. Der Host erhält die eindeutige ID über allocateAppWidgetId(). Diese ID bleibt während der gesamten Lebensdauer des Widgets erhalten, bis es vom Host gelöscht wird. Alle hostspezifischen Zustände, z. B. die Größe und Position des Widgets, müssen vom Hosting-Paket beibehalten und mit der App-Widget-ID verknüpft werden.
App-Widget-Hostansicht: AppWidgetHostView ist ein Rahmen, in den das Widget eingebunden wird, wenn es angezeigt werden soll. Ein Widget wird jedes Mal mit einer AppWidgetHostView verknüpft, wenn es vom Host aufgebläht wird.
- Standardmäßig erstellt das System ein AppWidgetHostView, aber der Host kann 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() für den Umgang mit dynamisch überladenen Farben eingeführt. Der Host ist dafür verantwortlich, die Farben für diese Methoden bereitzustellen.
Options-Bundle: Der AppWidgetHost verwendet das Options-Bundle, um dem AppWidgetProvider Informationen darüber 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. Anhand dieser Informationen kann die AppWidgetProvider den Inhalt 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. Beide Methoden lösen den Callback onAppWidgetOptionsChanged() für AppWidgetProvider aus.

Widgets binden

Wenn ein Nutzer einem Host ein Widget hinzufügt, wird ein Prozess namens Bindung ausgeführt. Die 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 UI für die Bindung bereitstellen. Wenn Sie diesen Prozess verwenden möchten, muss Ihre App die Berechtigung BIND_APPWIDGET 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 Ihrer App 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() den Wert false zurückgibt, muss Ihre App ein Dialogfeld anzeigen, in dem der Nutzer aufgefordert wird, die Berechtigung zu erteilen: „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.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)Host.kt

Der Host muss prüfen, ob das Widget, das ein Nutzer hinzufügt, konfiguriert werden muss. Weitere Informationen finden Sie unter Nutzern die Konfiguration von App-Widgets ermöglichen.

Verantwortlichkeiten des Hosts

Sie können eine Reihe von Konfigurationseinstellungen für Widgets mit den AppWidgetProviderInfo-Metadaten angeben. Diese Konfigurationsoptionen, die in den folgenden Abschnitten ausführlicher beschrieben werden, können Sie über das AppWidgetProviderInfo-Objekt abrufen, das mit einem Widget-Anbieter verknüpft ist.

Alle Gastgeber haben die folgenden Verantwortlichkeiten:

Wenn Sie ein Widget hinzufügen, weisen Sie die Widget-ID wie oben beschrieben zu. Wenn ein Widget vom Host entfernt wird, rufen Sie deleteAppWidgetId() auf, um die Widget-ID freizugeben.
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, sofern sie vorhanden ist und nicht durch Angabe der Flags configuration_optional und reconfigurable als optional gekennzeichnet ist. Weitere Informationen findest du unter Widget über die Konfigurationsaktivität aktualisieren. Dies ist für viele Widgets erforderlich, damit sie angezeigt werden können.

Hinweis: Behandle unregelmäßige Fälle, in denen die Konfigurationsaktivität nicht zurückgegeben wird oder mit Fehlern endet.
In den AppWidgetProviderInfo-Metadaten wird eine Standardbreite und -höhe für Widgets 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. Siehe Attribute für die Widget-Größe.

Achten Sie darauf, dass das Widget mindestens diese Anzahl von dps hat. Viele Hosts richten beispielsweise Symbole und Widgets 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.

Tipps für Ihre Herangehensweise

Zusätzlich zu den im vorherigen Abschnitt aufgeführten Anforderungen sollten Sie die folgenden Tipps beachten:

Das Options-Bundle kann ein List<SizeF> enthalten, das die Liste der möglichen Größen in dps enthält, die eine Widget-Instanz annehmen kann. Die Anzahl der bereitgestellten Größen hängt von der Hostimplementierung ab. Hosts stellen in der Regel zwei Größen für Smartphones (Hoch- und Querformat) und vier Größen für faltbare Geräte 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 jeder Größe in der List<SizeF> ein RemoteViews-Objekt zuordnen, sollten Sie nicht mehr als MAX_INIT_VIEW_COUNT Größen angeben.

Wenn Widgets die Attribute maxResizeWidth und maxResizeHeight in dps angeben, empfehlen wir, 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.