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 dem Nutzer auch Widgets einbetten lassen, indem du AppWidgetHost implementierst. In den meisten Anwendungen ist dies nicht erforderlich. Wenn Sie jedoch einen eigenen Host erstellen, ist es wichtig, die vertraglichen Verpflichtungen zu verstehen, denen ein Host implizit zustimmt.

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

Im Folgenden finden Sie eine Übersicht über die wichtigsten Klassen und Konzepte, die zum Implementieren einer benutzerdefinierten AppWidgetHost erforderlich sind:

  • App-Widget-Host: AppWidgetHost stellt die Interaktion mit dem AppWidget-Dienst für Apps bereit, die Widgets in ihre UI 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 normalerweise ein hartcodierter Wert, den Sie in Ihrer Anwendung zuweisen.

  • App-Widget-ID: Jeder Widget-Instanz wird bei der Bindung eine eindeutige ID zugewiesen. Weitere Informationen finden Sie unter bindAppWidgetIdIfAllowed() und weiter unten im Abschnitt Bindungs-Widgets. Der Host erhält die eindeutige ID mithilfe von allocateAppWidgetId(). Diese ID bleibt über die Lebensdauer des Widgets bestehen, bis es vom Host gelöscht wird. Jeder hostspezifische Status – z. B. Größe und Standort des Widgets – muss im Hostingpaket beibehalten und der App-Widget-ID zugeordnet werden.

  • Host-Ansicht des App-Widgets: Stellen Sie sich AppWidgetHostView als Frame vor, in den das Widget eingebunden ist, wenn es angezeigt werden muss. Ein Widget wird immer dann mit einem AppWidgetHostView verknüpft, wenn der Host das Widget aufgebläht hat.

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

  • Options-Bundle: Das AppWidgetHost verwendet das Options-Bundle, um der AppWidgetProvider Informationen dazu zu geben, wie das Widget angezeigt wird (z. B. eine Liste der Größenbereiche) und ob sich das Widget auf einem Sperr- oder Startbildschirm befindet. Anhand dieser Informationen kann AppWidgetProvider Inhalt und Darstellung des Widgets daran 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 onAppWidgetOptionsChanged()-Callback an AppWidgetProvider aus.

Bindungs-Widgets

Wenn ein Nutzer einem Host ein Widget hinzufügt, wird ein Vorgang als Bindung bezeichnet. Als Bindung wird eine bestimmte App-Widget-ID mit einem bestimmten Host und einer bestimmten AppWidgetProvider verknüpft.

Mit Bindungs-APIs kann ein Host auch eine benutzerdefinierte UI für die Bindung bereitstellen. 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 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 Widget-Hinzufügen oder „Immer erlauben“, um alle zukünftigen Widget-Hinzufügungen abzudecken.

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 von einem Nutzer hinzugefügte Widget eine Konfiguration erfordert. Weitere Informationen finden Sie unter Nutzern erlauben, App-Widgets zu konfigurieren.

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 genauer beschrieben werden, über das Objekt AppWidgetProviderInfo abrufen, das mit einem Widget-Anbieter verknüpft ist.

Unabhängig von der anvisierten Android-Version haben alle Hosts die folgenden Pflichten:

  • 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 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. Dazu müssen die Flags configuration_optional und reconfigurable angegeben werden. 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 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 Widget-Größenattribute.

    Achten Sie darauf, dass das Widget mit mindestens dieser Anzahl von DPS angeordnet ist. Beispielsweise richten viele Hosts 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.

Zusätzlich zu den im vorherigen Abschnitt aufgeführten Anforderungen führen bestimmte Plattformversionen Funktionen ein, die dem Host neue Verantwortlichkeiten auferlegen.

Ansatz basierend auf der gewünschten Android-Version festlegen

Android 12

Android 12 (API-Level 31) enthält eine zusätzliche List<SizeF> mit der Liste möglicher Größen in dps, die eine Widget-Instanz im Options-Bundle annehmen kann. Die Anzahl der bereitgestellten Größen hängt von der Hostimplementierung ab. Hosts bieten in der Regel zwei Größen für Smartphones – Hochformat und Querformat – und vier Größen für faltbare Smartphones an.

Die Anzahl der verschiedenen RemoteViews, die ein AppWidgetProvider für RemoteViews bereitstellen kann, ist auf MAX_INIT_VIEW_COUNT (16) beschränkt. 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.

Android 12 führt auch die Attribute maxResizeWidth und maxResizeHeight in dps ein. Ein Widget, das mindestens eines dieser Attribute verwendet, sollte die durch die Attribute angegebene Größe nicht überschreiten.

Weitere Informationen

  • Weitere Informationen finden Sie in der Referenzdokumentation zu Glance.