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 einer AppWidgetHost
Quellcode für den Android-Startbildschirm ansehen
LauncherAppWidgetHost
Hier ist ein Überblick über die wichtigsten Klassen und Konzepte, die bei der Implementierung eines
Benutzerdefiniert AppWidgetHost
:
App-Widget-Host:
AppWidgetHost
stellt die Interaktion mit dem AppWidget-Dienst für Apps, die Widgets in ihre Benutzeroberfläche einbetten. EinAppWidgetHost
muss eine ID haben, die im eigenen Paket des Hosts eindeutig ist. Diese ID bleibt erhalten für alle Nutzungsarten des Hosts. Die ID ist normalerweise ein hartcodierter Wert, 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()
Weitere Informationen finden Sie im folgenden Abschnitt Widgets verknüpfen. Die -Host erhält die eindeutige ID mithilfe vonallocateAppWidgetId()
Diese ID bleibt für die gesamte Lebensdauer des Widgets bestehen, bis sie aus dem Host. 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 einemAppWidgetHostView
verknüpft sind, wenn das Widget durch den Host.- Standardmäßig erstellt das System eine
AppWidgetHostView
, aber der Host kann Erstellen Sie eine eigene abgeleitete Klasse vonAppWidgetHostView
, indem Sie sie erweitern. - Ab Android 12 (API-Level 31) führt
AppWidgetHostView
das neue diesetColorResources()
undresetColorResources()
Methoden zum Umgang mit dynamisch überladenen Farben. Der Organisator ist die Farben für diese Methoden bereitstellen.
- Standardmäßig erstellt das System eine
Optionsset:
AppWidgetHost
verwendet das Options-Bundle, um Informationen an dieAppWidgetProvider
wie das Widget angezeigt wird, zum Beispiel Liste der Größenbereiche das Widget auf dem Sperrbildschirm oder dem Startbildschirm zu sehen ist. Mit diesen Informationen kann dasAppWidgetProvider
passt den Inhalt und das Design des Widgets an, je nachdem, wie und wo es angezeigt wird. Sie könnenupdateAppWidgetOptions()
undupdateAppWidgetSize()
um das Bundle eines Widgets zu ändern. Beide Methoden lösen das EreignisonAppWidgetOptionsChanged()
Callback desAppWidgetProvider
.
Widgets binden
Wenn ein Nutzer einem Host ein Widget hinzufügt, findet ein Vorgang namens Bindung statt. Bindung
die Verknüpfung einer bestimmten App-Widget-ID mit einem bestimmten Host
bestimmte AppWidgetProvider
.
Bindungs-APIs ermöglichen es einem Host auch, eine benutzerdefinierte Benutzeroberfläche für
Bindung. Um diesen Prozess zu verwenden, muss Ihre App die
BIND_APPWIDGET
Berechtigung im Manifest des Hosts:
<uses-permission android:name="android.permission.BIND_APPWIDGET" />
Aber das ist nur der erste Schritt. Zur Laufzeit muss der Nutzer explizit
Berechtigung für Ihre App, damit sie dem Host ein Widget hinzufügen kann. Um zu testen, ob Ihre
zum Hinzufügen des Widgets berechtigt ist, verwenden Sie die
bindAppWidgetIdIfAllowed()
. Wenn bindAppWidgetIdIfAllowed()
false
zurückgibt, muss in deiner App ein
Dialogfeld, in dem der Nutzer aufgefordert wird, die Berechtigung zu gewähren: „Zulassen“ für das aktuelle Widget
oder „immer erlauben“, um alle zukünftigen Widget-Ergänzungen abzudecken.
Dieses Snippet zeigt ein Beispiel, wie das Dialogfeld angezeigt wird:
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 das Konfigurieren von Apps ermöglichen Widgets.
Verantwortlichkeiten des Organisators
Sie können eine Reihe von Konfigurationseinstellungen für Widgets mithilfe der
AppWidgetProviderInfo
-Metadaten.
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 wird das Widget vom Host entfernt, rufen Sie
deleteAppWidgetId()
um die Zuweisung der Widget-ID aufzuheben.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
undreconfigurable
. 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 der
AppWidgetProviderInfo
an Metadaten. Diese Werte werden in Zellen definiert, beginnend mit Android 12, wenntargetCellWidth
undtargetCellHeight
sind angegeben oder „dps“, wenn nurminWidth
undminHeight
angegeben sind. Weitere Informationen finden Sie unter Widget-Größenattribute:Stellen Sie sicher, dass das Widget mit mindestens dieser Anzahl von dps angeordnet ist. 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
undminHeight
erfüllen.
Zusätzlich zu den im vorherigen Abschnitt aufgeführten Anforderungen müssen Plattformversionen neue Funktionen aufführen, die neue Verantwortlichkeiten Host.
Bestimme deinen Ansatz basierend auf der gewünschten Android-Version
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 angegebenen Größen hängt von der Hostimplementierung ab. In der Regel Moderatoren
stehen Ihnen zwei Größen für Smartphones (Hoch- und Querformat) und vier Größen zur Verfügung.
für faltbare Geräte.
Es gibt ein Limit von MAX_INIT_VIEW_COUNT
(16) für die Anzahl
RemoteViews
, die ein AppWidgetProvider
bereitstellen kann
RemoteViews
Da AppWidgetProvider
-Objekte ein RemoteViews
-Objekt jeder Größe in der
List<SizeF>
, geben Sie nicht mehr als MAX_INIT_VIEW_COUNT
Größen an.
Mit Android 12 werden außerdem die
maxResizeWidth
und
maxResizeHeight
Attribute in dps. Wir empfehlen ein Widget, das mindestens eines dieser
die durch die Attribute angegebene Größe nicht überschreitet.
Weitere Informationen
- Weitere Informationen finden Sie in der Referenzdokumentation zu
Glance
.