Widgethost erstellen

Mit dem Android-Startbildschirm, der auf den meisten Android-Geräten verfügbar ist, Nutzer App-Widgets (oder Widgets) für schnell auf Inhalte zugreifen können. Wenn Sie einen Ersatz-Startbildschirm oder eine ähnlichen Apps suchen, können Sie dem Nutzer auch erlauben, Widgets einzubetten, indem Sie AppWidgetHost Das ist nicht Das müssen die meisten Apps. Wenn Sie jedoch Ihren eigenen Host erstellen, Es ist wichtig, die vertraglichen Verpflichtungen zu verstehen, denen ein Host implizit zustimmt.

Diese Seite konzentriert sich auf die Verantwortlichkeiten, die mit der Implementierung einer benutzerdefinierten AppWidgetHost Ein konkretes Beispiel für die Implementierung eines 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: Jeder Widget-Instanz wird zu diesem Zeitpunkt eine eindeutige ID zugewiesen Bindung. Weitere Informationen finden Sie unter bindAppWidgetIdIfAllowed() und im folgenden Abschnitt Widgets binden. Die -Host erhält die eindeutige ID mithilfe von allocateAppWidgetId() Diese ID bleibt während der gesamten Lebensdauer des Widgets bestehen, bis es vom Host gelöscht wird. Jeder hostspezifische Status, z. B. die Größe und der Speicherort des Widget – muss vom Hosting-Paket beibehalten und mit dem App-Widget-ID.

  • Host-Ansicht des App-Widgets: Denken Sie an AppWidgetHostView als Frame dass das Widget immer dann umschlossen ist, wenn es angezeigt werden soll. Ein Widget ist die mit einem AppWidgetHostView verknüpft sind, wenn das Widget durch den Host.

    • 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 Organisator ist die Farben für diese Methoden bereitstellen.

  • Optionsset: AppWidgetHost verwendet das Options-Bundle, um Informationen an die AppWidgetProvider wie das Widget angezeigt wird, zum Beispiel Liste der Größenbereiche das Widget auf dem Sperrbildschirm oder dem Startbildschirm zu sehen ist. Anhand dieser Informationen kann AppWidgetProvider den Inhalt und das Erscheinungsbild des Widgets an die Art und Weise anpassen, wie und wo es angezeigt wird. Sie können updateAppWidgetOptions() und updateAppWidgetSize() 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, findet ein Vorgang namens Bindung statt. 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. Um diesen Prozess zu verwenden, muss Ihre App die BIND_APPWIDGET Berechtigung im Manifest des Hosts:

<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:

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 vom Nutzer hinzugefügte Widget konfiguriert werden muss. Für Weitere Informationen finden Sie unter Nutzern erlauben, die App zu konfigurieren Widgets.

Verantwortlichkeiten des Organisators

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

Alle Hosts haben unabhängig von der Android-Version, auf die Sie abzielen, die Verantwortlichkeiten:

  • Weisen Sie beim Hinzufügen eines Widgets die Widget-ID wie zuvor 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 eingeführt. In der Regel muss der Host die Konfiguration des Widgets starten Aktivität, wenn vorhanden und nicht als optional markiert ist, indem Sie sowohl das Attribut Die Flags configuration_optional und reconfigurable. 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 eine Standardbreite und -höhe in der AppWidgetProviderInfo an Metadaten. Diese Werte werden in Zellen definiert, beginnend mit Android 12, wenn targetCellWidth und targetCellHeight sind angegeben oder „dps“, wenn nur minWidth und minHeight angegeben sind. Weitere Informationen finden Sie unter Widget-Größenattribute:

    Das Widget muss mindestens diese Größe haben. Für Viele Hosts richten z. B. Symbole und Widgets in einem Raster aus. In diesem Szenario können wir fügt der Host das Widget mit der Mindestanzahl von Zellen hinzu, 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 eine zusätzliche List<SizeF>, die die Liste enthält der möglichen 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 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 außerdem die maxResizeWidth und maxResizeHeight Attribute in dps. 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.