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 erstellst, kannst du dem Nutzer auch erlauben, Widgets einzubetten. Dazu musst du AppWidgetHost implementieren. Die meisten Anwendungen müssen dies nicht tun. Wenn Sie jedoch Ihren eigenen Host erstellen, ist es wichtig, die vertraglichen Verpflichtungen zu verstehen, denen ein Host implizit zustimmt.

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

Hier finden Sie eine Übersicht über die wichtigsten Klassen und Konzepte der Implementierung einer benutzerdefinierten AppWidgetHost:

• App-Widget-Host: AppWidgetHost ermöglicht die Interaktion mit dem AppWidget-Dienst für Apps, die Widgets in ihre UI einbetten. Ein AppWidgetHost muss eine ID haben, die im eigenen Paket des Hosts eindeutig ist. Diese ID bleibt für alle Verwendungen des Hosts bestehen. Die ID ist normalerweise 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 Bindungs-Widgets. Der Host ruft die eindeutige ID über allocateAppWidgetId() ab. Diese ID bleibt über die Lebensdauer des Widgets bestehen, bis sie vom Host gelöscht wird. Jeder hostspezifische Status, z. B. die Größe und der Speicherort des Widgets, muss vom Hostingpaket beibehalten und der App-Widget-ID zugeordnet werden.

• Hostansicht des App-Widgets: Stellen Sie sich AppWidgetHostView wie einen Frame vor, in den das Widget umschlossen wird, wenn es angezeigt werden soll. Jedes Mal, wenn das Widget vom Host überhöht wird, wird ein Widget mit einem AppWidgetHostView verknüpft.

  • Standardmäßig erstellt das System eine AppWidgetHostView, aber der Host kann durch Erweitern eine eigene abgeleitete Klasse von AppWidgetHostView erstellen.
  • Ab Android 12 (API-Level 31) führt AppWidgetHostView die Methoden setColorResources() und resetColorResources() für die Verarbeitung dynamisch überladener Farben ein. Der Host ist für die Bereitstellung der Farben für diese Methoden verantwortlich.

• Options-Bundle: 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 auf dem Startbildschirm befindet. Mit diesen Informationen kann das AppWidgetProvider den Inhalt und die Darstellung des Widgets daran anpassen, wie und wo es angezeigt wird. Mit updateAppWidgetOptions() und updateAppWidgetSize() können Sie das Bundle eines Widgets ändern. Beide Methoden lösen den onAppWidgetOptionsChanged()-Callback an AppWidgetProvider aus.

Widgets binden

Wenn ein Nutzer einem Host ein Widget hinzufügt, findet ein Vorgang namens Bindung statt. Bindung bezieht sich auf das Verknüpfen einer bestimmten App-Widget-ID mit einem bestimmten Host und einer bestimmten AppWidgetProvider.

Bindungs-APIs ermöglichen es einem Host auch, eine benutzerdefinierte UI für die Bindung bereitzustellen. Damit Sie diesen Vorgang verwenden können, muss Ihre App die Berechtigung BIND_APPWIDGET im Manifest des Hosts deklarieren:

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

Aber das ist nur der erste Schritt. Zur Laufzeit muss der Nutzer Ihrer App explizit die Berechtigung erteilen, dem Host ein Widget hinzufügen zu können. Mit der Methode bindAppWidgetIdIfAllowed() können Sie testen, ob Ihre App die Berechtigung zum Hinzufügen des Widgets hat. Wenn bindAppWidgetIdIfAllowed() den Wert false zurückgibt, muss in deiner App ein Dialogfeld angezeigt werden, in dem der Nutzer aufgefordert wird, die Berechtigung zu erteilen: „Zulassen“ für das aktuelle Widget-Hinzufügen oder „Immer zulassen“, um alle zukünftigen Widget-Ergänzungen abzudecken.

Dieses Snippet zeigt ein Beispiel, 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 vom Nutzer hinzugefügte Widget konfiguriert werden muss. Weitere Informationen finden Sie unter Nutzern das Konfigurieren von App-Widgets ermöglichen.

Verantwortlichkeiten des Organisators

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

Unabhängig von der ausgewählten Android-Version haben alle Hosts die folgenden Verantwortlichkeiten:

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

• 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, sofern vorhanden und nicht als optional gekennzeichnet ist. Dazu werden die Flags configuration_optional und reconfigurable angegeben. Weitere Informationen finden Sie unter Widget über die Konfigurationsaktivität aktualisieren. Dieser Schritt ist bei vielen Widgets erforderlich, bevor sie angezeigt werden können.

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

  Stellen Sie sicher, dass das Widget mit mindestens dieser Anzahl von dps angeordnet ist. Viele Hosts richten beispielsweise Symbole und Widgets in einem Raster aus. In diesem Szenario fügt der Host das Widget standardmäßig 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 in bestimmten Plattformversionen Funktionen eingeführt, die neue Verantwortlichkeiten für den Host auferlegen.

Bestimme deinen Ansatz basierend auf der gewünschten Android-Version

Android 12

Android 12 (API-Level 31) bündelt 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 angegebenen Größen hängt von der Hostimplementierung ab. Hosts bieten normalerweise zwei Größen für Smartphones – Hoch- und Querformat – und vier Größen für faltbare Geräte.

Es gibt ein Limit von MAX_INIT_VIEW_COUNT (16) für die Anzahl der verschiedenen RemoteViews, die ein AppWidgetProvider für RemoteViews bereitstellen kann. Da AppWidgetProvider-Objekte jeder Größe im List<SizeF> ein RemoteViews-Objekt zuordnen, sollten Sie nicht mehr als MAX_INIT_VIEW_COUNT Größen angeben.

In Android 12 werden außerdem die Attribute maxResizeWidth und maxResizeHeight in dps eingeführt. Ein Widget, das mindestens eines dieser Attribute verwendet, sollte die durch die Attribute angegebene Größe nicht überschreiten.

Zusätzliche Ressourcen

• Weitere Informationen finden Sie in der Referenzdokumentation zu Glance.