App-Widget mit Glance erstellen

In den folgenden Abschnitten wird beschrieben, wie Sie mit Glance ein einfaches App-Widget erstellen.

AppWidget im Manifest deklarieren

Nachdem Sie die Einrichtungsschritte ausgeführt haben, deklarieren Sie das AppWidget und seine Metadaten in Ihrer App.

1. Erweitern Sie den AppWidget-Empfänger von GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
       override val glanceAppWidget: GlanceAppWidget = TODO("Create GlanceAppWidget")
   }
   GlanceSnippets.kt

2. Registrieren Sie den Anbieter des App-Widgets in der Datei AndroidManifest.xml und der zugehörigen Metadatendatei:

       <receiver android:name=".glance.MyReceiver"
       android:exported="true">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/my_app_widget_info" />
   </receiver>
   AndroidManifest.xml
   

AppWidgetProviderInfo-Metadaten hinzufügen

Folgen Sie als Nächstes der Anleitung zum Erstellen eines Widgets, um die App -Widget-Informationen in der @xml/my_app_widget_info Datei zu erstellen und zu definieren.

Der einzige Unterschied bei Glance besteht darin, dass es kein initialLayout-XML gibt, das Sie aber definieren müssen. Sie können das vordefinierte Ladelayout verwenden, das in der Bibliothek bereitgestellt wird:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout">
</appwidget-provider>
my_app_widget_info.xml

`AppWidgetProviderInfo`-XML deklarieren

Das AppWidgetProviderInfo-Objekt definiert die wesentlichen Eigenschaften Ihres Widgets. Definieren Sie AppWidgetProviderInfo in der XML-Metadatenressourcendatei (res/xml/my_app_widget_info.xml) in einem <appwidget-provider> Element:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Attribute für die Widgetgröße

Die Standardpositionen für Widgets auf dem Startbildschirm werden in einem Fenster basierend auf einem Raster aus Zellen mit einer definierten Höhe und Breite festgelegt. Auf den meisten Startbildschirmen können Widgets nur Größen annehmen, die ganzzahlige Vielfache der Rasterzellen sind, z. B. zwei Zellen horizontal und drei Zellen vertikal.

Mit den Attributen für die Widgetgröße können Sie eine Standardgröße für Ihr Widget angeben und untere und obere Grenzwerte für die Größe des Widgets festlegen. In diesem Zusammenhang ist die Standardgröße eines Widgets die Größe, die das Widget annimmt, wenn es zum ersten Mal dem Startbildschirm hinzugefügt wird.

In der folgenden Tabelle werden die <appwidget-provider> Attribute beschrieben, die sich auf die Widgetgröße beziehen:

Beispiel

Um zu veranschaulichen, wie sich die Attribute in der vorherigen Tabelle auf die Widgetgröße auswirken, nehmen wir die folgenden Spezifikationen an:

• Eine Rasterzelle ist 30 dp breit und 50 dp hoch.
• Die folgende Attributspezifikation wird bereitgestellt:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

Ab Android 12 :

Verwenden Sie die Attribute targetCellWidth und targetCellHeight als Standardgröße des Widgets.

Die Standardgröße des Widgets ist 2 × 2. Die Größe des Widgets kann auf 2 × 1 verkleinert oder auf 4 × 3 vergrößert werden.

Android 11 und niedriger :

Verwenden Sie die Attribute minWidth und minHeight, um die Standardgröße des Widgets zu berechnen.

Standardbreite = Math.ceil(80 / 30) = 3

Standardhöhe = Math.ceil(80 / 50) = 2

Die Standardgröße des Widgets ist 3 × 2. Die Größe des Widgets kann auf 2 × 1 verkleinert oder auf Vollbildgröße vergrößert werden.

Zusätzliche Widgetattribute

In der folgenden Tabelle werden die <appwidget-provider> Attribute beschrieben, die sich auf andere Eigenschaften als die Widgetgröße beziehen.

GlanceAppWidget definieren

1. Erstellen Sie eine neue Klasse, die von GlanceAppWidget abgeleitet wird, und überschreibt die provideGlance Methode. Mit dieser Methode können Sie Daten laden, die zum Rendern Ihres Widgets erforderlich sind:

   finden Sie unter Coroutinen für die Hauptthread-Sicherheit verwenden.

   class MyAppWidget : GlanceAppWidget() {
   
       override suspend fun provideGlance(context: Context, id: GlanceId) {
   
           // In this method, load data needed to render the AppWidget.
           // Use `withContext` to switch to another thread for long running
           // operations.
   
           provideContent {
               // create your AppWidget here
               Text("Hello World")
           }
       }
   }
   GlanceSnippets.kt

2. Instanziieren Sie sie in glanceAppWidget in Ihrem GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
   
       // Let MyAppWidgetReceiver know which GlanceAppWidget to use
       override val glanceAppWidget: GlanceAppWidget = MyAppWidget()
   }
   GlanceSnippets.kt

Sie haben jetzt ein AppWidget mit Glance konfiguriert.

Klasse „GlanceAppWidgetReceiver“ zum Verarbeiten von Widget-Broadcasts verwenden

Der GlanceAppWidgetReceiver koordiniert Widget-Broadcasts und Plattformstatus aktualisierungen, indem er den zugrunde liegenden AppWidgetProvider erweitert. Er empfängt Plattformereignisse, wenn Ihr Widget aktualisiert, gelöscht, aktiviert oder deaktiviert wird, und übersetzt sie in Compose-Lebenszyklusanfragen.

Widget im Manifest deklarieren

Deklarieren Sie die Unterklasse GlanceAppWidgetReceiver als Broadcast-Empfänger in der Datei AndroidManifest.xml:

<receiver android:name="ExampleAppWidgetReceiver"
          android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/my_app_widget_info" />
</receiver>

Das <receiver> Element erfordert das android:name Attribut, das die Empfängerklasse angibt. Der Empfänger muss die ACTION_APPWIDGET_UPDATE Broadcast-Aktion im <intent-filter> akzeptieren.

Das <meta-data> Element muss als Name android.appwidget.provider angeben und das android:resource Attribut muss auf Ihre XML-Metadatenressource AppWidgetProviderInfo (@xml/my_app_widget_info) verweisen.

Klasse „GlanceAppWidgetReceiver“ implementieren

In Glance erweitern Sie GlanceAppWidgetReceiver anstelle von AppWidgetProvider direkt. Implementieren Sie es, indem Sie Ihren Empfänger mit Ihrer GlanceAppWidget-Instanz verknüpfen. Die primären Callbacks, die in GlanceAppWidgetReceiver verfügbar sind, funktionieren so:

• onUpdate(): Wird automatisch von Glance überschrieben, um Kompositionsaktualisierungen auszuführen. Wenn Sie onUpdate manuell überschreiben, müssen Sie super.onUpdate aufrufen, damit Glance Kompositionsthreads erfolgreich starten kann.
• onAppWidgetOptionsChanged(): Wird aufgerufen, wenn das Widget zum ersten Mal platziert oder in der Größe geändert wird. Glance liest Options-Bundle-Elemente im Hintergrund, sodass Ihr Layout nahtlos an die Laufzeitdimensionen angepasst wird.
• onDeleted(Context, IntArray): Wird aufgerufen, wenn eine bestimmte Widget-Instanz vom Nutzer gelöscht wird.
• onEnabled(Context): Wird ausgelöst, wenn die erste Instanz Ihres Widgets erfolgreich erstellt wurde. Ideal für die Ausführung globaler Migrationen.
• onDisabled(Context): Wird aufgerufen, wenn die letzte aktive Instanz des Anbieters entfernt wird.
• onReceive(Context, Intent): Fängt jeden Plattform-Broadcast vor bestimmten Callback-Methoden ab. Sie müssen sicherstellen, dass jede benutzerdefinierte Empfängerlogik die Sie schreiben, super.onReceive(context, intent) aufruft und niemals selbst goAsync aufruft, da Glance die Arbeit automatisch asynchron weiterleitet.

Widget-Broadcast-Intents empfangen

Im Hintergrund filtert und verarbeitet GlanceAppWidgetReceiver die folgenden grundlegenden Widget-Broadcast-Intents der Plattform:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

UI erstellen

Das folgende Snippet zeigt, wie Sie die UI erstellen:

/* Import Glance Composables
 In the event there is a name clash with the Compose classes of the same name,
 you may rename the imports per https://kotlinlang.org/docs/packages.html#imports
 using the `as` keyword.

import androidx.glance.Button
import androidx.glance.layout.Column
import androidx.glance.layout.Row
import androidx.glance.text.Text
*/
class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // Load data needed to render the AppWidget.
        // Use `withContext` to switch to another thread for long running
        // operations.

        provideContent {
            // create your AppWidget here
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize(),
            verticalAlignment = Alignment.Top,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button(
                    text = "Home",
                    onClick = actionStartActivity<MyActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MyActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

Das vorherige Codebeispiel führt folgende Schritte aus:

• In der obersten Ebene Column werden Elemente vertikal nacheinander platziert.
• Die Column wird so erweitert, dass sie dem verfügbaren Platz entspricht (über die GlanceModifier), und der Inhalt wird oben (verticalAlignment) und horizontal zentriert (horizontalAlignment) ausgerichtet.
• Der Inhalt der Column wird mit der Lambda-Funktion definiert. Die Reihenfolge ist wichtig.
  • Das erste Element in der Column ist eine Text-Komponente mit einem Abstand von 12.dp.
  • Das zweite Element ist eine Row, in der Elemente horizontal nacheinander platziert werden, mit zwei Buttons, die horizontal zentriert sind (horizontalAlignment). Die endgültige Anzeige hängt vom verfügbaren Platz ab. Die folgende Abbildung zeigt ein Beispiel dafür, wie das aussehen kann:

Sie können die Ausrichtungswerte ändern oder verschiedene Modifikatorwerte (z. B. Abstand) anwenden, um die Platzierung und Größe der Komponenten zu ändern. Eine vollständige Liste der Komponenten, Parameter und verfügbaren Modifikatoren für jede Klasse finden Sie in der Referenz dokumentation.

Abgerundete Ecken implementieren

In Android 12 werden Systemparameter eingeführt, mit denen Sie die Eckradien Ihrer App-Widgets dynamisch anpassen können:

• system_app_widget_background_radius: Gibt den Eckradius des Widget-Hintergrundcontainers an (nie größer als 28 dp).
• Innenradius:Um zu verhindern, dass Inhalte abgeschnitten werden, berechnen Sie einen proportionalen Radius für Ihre internen Inhalte basierend auf der Systemhintergrundkontur: systemRadiusValue - widgetPadding

In Glance können Sie Eigenschaften für die Eckradiusgröße dynamisch in der Komposition mit GlanceModifier.cornerRadius(android.R.dimen.system_app_widget_background_radius) anwenden.

Für die Abwärtskompatibilität auf Geräten mit Android 11 (API-Level 30) oder niedriger implementieren Sie benutzerdefinierte Attribute und Fallbacks für benutzerdefinierte Designressourcen:

• /values/attrs.xml

  <resources>
  <attr name="backgroundRadius" format="dimension" />
  </resources>
  

• /values/styles.xml

  <resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
  </resources>
  

• /values-31/styles.xml

  <resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
  </resources>
  

• /drawable/my_widget_background.xml

  <shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  </shape>