Créer un widget simple

Les widgets d'application sont des vues d'application miniatures que vous pouvez intégrer dans d'autres telles que l'écran d'accueil, et recevoir régulièrement des mises à jour. Ces Les vues sont appelées widgets dans l'interface utilisateur, et vous pouvez publier une avec un fournisseur de widgets d'application (ou un fournisseur de widgets). Composant d'application qui contenant d'autres widgets est appelé hôte de widget d'application (ou hôte de widget). Figure 1 affiche un exemple de widget musical:

Ce document explique comment publier un widget à l'aide d'un fournisseur de widgets. Pour des détails sur la création de votre propre AppWidgetHost pour des widgets d'application hôte, consultez la section Créer un hôte de widget.

Pour en savoir plus sur la conception de votre widget, consultez Présentation des widgets d'application.

Composants du widget

Pour créer un widget, vous avez besoin des composants de base suivants:

Objet AppWidgetProviderInfo

Décrit les métadonnées d'un widget, telles que sa mise en page, sa mise à jour la fréquence et la classe AppWidgetProvider. AppWidgetProviderInfo est défini en XML, comme suit : décrites dans ce document.

Classe AppWidgetProvider

Définit les méthodes de base qui vous permettent d'interagir de manière programmatique avec la . Grâce à lui, vous recevez des annonces lorsque le widget est mis à jour, activées, désactivées ou supprimées. Vous déclarez AppWidgetProvider dans manifeste, puis l'implémentez, décrites dans ce document.

Afficher la mise en page

Définit la mise en page initiale du widget. La mise en page est définie XML, comme décrit dans ce document.

La figure 2 montre comment ces composants s'intègrent dans le traitement global des widgets d'application. le flux de travail.

Si votre widget nécessite une configuration utilisateur, implémentez la configuration du widget d'application. activité. Cette activité permet aux utilisateurs de modifier les paramètres des widgets, par exemple, le fuseau horaire d'un widget d'horloge.

• À partir d'Android 12 (niveau d'API 31), vous pouvez fournir un et permettre aux utilisateurs de reconfigurer le widget ultérieurement. Reportez-vous à la section Utiliser le la configuration par défaut du widget et Activer aux utilisateurs de reconfigurer les widgets qu'ils ont placés pour en savoir plus.
• Sur Android 11 (niveau d'API 30) ou version antérieure, cette activité est lancée à chaque fois l'utilisateur ajoute le widget à son écran d'accueil.

Nous recommandons également les améliorations suivantes: mises en page de widgets flexibles, différentes améliorations, widgets avancés, widgets de collection et création de widgets. d'hébergement.

Déclarer le fichier XML AppWidgetProviderInfo

L'objet AppWidgetProviderInfo définit les qualités essentielles d'un widget. Définissez l'objet AppWidgetProviderInfo dans un fichier de ressources XML à l'aide d'une seule <appwidget-provider> et enregistrez-le dans le dossier res/xml/ du projet.

Ce processus est illustré dans l'exemple suivant :

<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/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Attributs de dimensionnement des widgets

L'écran d'accueil par défaut positionne les widgets dans sa fenêtre en fonction d'une grille de cellules d'une hauteur et d'une largeur définies. Avec la plupart des écrans d'accueil, seuls les widgets peuvent s'afficher tailles qui sont des multiples entiers des cellules de la grille (par exemple, deux cellules) horizontalement de trois cellules verticalement.

Les attributs de dimensionnement de widget vous permettent de spécifier une taille par défaut pour votre widget et indiquent les limites inférieure et supérieure de la taille du widget. Dans ce contexte, la taille par défaut d'un widget est la taille qu'il prend en charge ajouté à l'écran d'accueil.

Le tableau suivant décrit les attributs <appwidget-provider> concernant au dimensionnement des widgets:

Exemple

Pour illustrer l'impact des attributs du tableau précédent sur le dimensionnement des widgets, supposent les spécifications suivantes:

• Une cellule de grille fait 30 dp de large et 50 dp de hauteur.
• Les spécifications d'attribut suivantes sont fournies:

<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" />

À partir d'Android 12:

Utilisez les attributs targetCellWidth et targetCellHeight par défaut. la taille du widget.

Par défaut, la taille du widget est 2 x 2. Le widget peut être redimensionné à 2 x 1 ou jusqu'à 4x3.

Android 11 ou version antérieure:

Utilisez les attributs minWidth et minHeight pour calculer la taille par défaut de le widget.

Largeur par défaut = Math.ceil(80 / 30) = 3

Hauteur par défaut = Math.ceil(80 / 50) = 2

Par défaut, la taille du widget est 3 x 2. Le widget peut être redimensionné à 2 x 1 ou jusqu'en plein écran.

Autres attributs de widget

Le tableau suivant décrit les attributs <appwidget-provider> concernant à des qualités autres que le dimensionnement du widget.

Utiliser la classe AppWidgetProvider pour gérer les diffusions de widget

La classe AppWidgetProvider gère les diffusions du widget et le met à jour. en réponse aux événements de cycle de vie des widgets. Les sections suivantes décrivent comment déclarer AppWidgetProvider dans le fichier manifeste, puis l'implémenter.

Déclarer un widget dans le fichier manifeste

Commencez par déclarer la classe AppWidgetProvider dans le AndroidManifest.xml de votre application. , comme illustré dans l'exemple suivant:

<receiver android:name="ExampleAppWidgetProvider"
                 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/example_appwidget_info" />
</receiver>

L'élément <receiver> nécessite l'attribut android:name, qui spécifie AppWidgetProvider utilisé par le widget. Le composant ne doit pas être exporté sauf si un processus distinct doit être diffusé sur votre AppWidgetProvider, ce qui ce n'est généralement pas le cas.

L'élément <intent-filter> doit inclure un élément <action> avec le paramètre android:name. Cet attribut indique que AppWidgetProvider accepte les ACTION_APPWIDGET_UPDATE annonce. Il s'agit de la seule diffusion que vous devez déclarer explicitement. La AppWidgetManager envoie automatiquement toutes les autres annonces de widget à AppWidgetProvider en tant que nécessaires.

L'élément <meta-data> spécifie la ressource AppWidgetProviderInfo et requiert les attributs suivants:

• android:name: spécifie le nom des métadonnées. Utilisez android.appwidget.provider pour identifier les données comme Descripteur AppWidgetProviderInfo.
• android:resource: spécifie la ressource AppWidgetProviderInfo. l'emplacement.

Implémenter la classe AppWidgetProvider

La classe AppWidgetProvider étend BroadcastReceiver en tant que pour gérer les diffusions de widget. Il ne reçoit que l'événement des annonces pertinentes pour le widget, comme la mise à jour du widget, supprimé, activé et désactivé. Lorsque ces événements de diffusion se produisent, les éléments suivants Les méthodes AppWidgetProvider sont appelées:

onUpdate()

Cette méthode est appelée pour mettre à jour le widget à des intervalles définis par le updatePeriodMillis dans AppWidgetProviderInfo. Consultez le tableau décrivant d'autres attributs de widget sur cette page pour plus d'informations.

Cette méthode est également appelée lorsque l'utilisateur ajoute le widget afin qu'il effectue l'action configuration essentielle, comme la définition de gestionnaires d'événements pour Objets View ou démarrage de tâches pour charger des données s'affichent dans le widget. Toutefois, si vous déclarez une activité de configuration sans l'indicateur configuration_optional, cette méthode n'est pas appelée lorsque l'utilisateur ajoute le widget, mais il est appelé pour les mises à jour ultérieures. Il s'agit de l'activité de configuration pour effectuer la première mise à jour est terminée. Pour en savoir plus, consultez Permettre aux utilisateurs de configurer des widgets d'application.

Le rappel le plus important est onUpdate(). Consultez la section Gérer les événements à l'aide du module onUpdate() sur cette page.

onAppWidgetOptionsChanged()

Cette méthode est appelée lorsque le widget est placé pour la première fois et chaque fois qu'il est redimensionnée. Utilisez ce rappel pour afficher ou masquer le contenu en fonction de la taille du widget plages. Obtenez les plages de tailles et, à partir d'Android 12, la liste des tailles possibles d'une instance de widget en appelant getAppWidgetOptions(), qui renvoie un Bundle qui inclut le suivantes:

• OPTION_APPWIDGET_MIN_WIDTH: contient la limite inférieure de la largeur, en dp, d'une instance de widget.
• OPTION_APPWIDGET_MIN_HEIGHT: contient la limite inférieure de la hauteur, en dp, d'une instance de widget.
• OPTION_APPWIDGET_MAX_WIDTH: contient la limite supérieure de la largeur, en dp, d'une instance de widget.
• OPTION_APPWIDGET_MAX_HEIGHT: contient la limite supérieure de la hauteur, en dp, d'une instance de widget.
• OPTION_APPWIDGET_SIZES: contient la liste des tailles possibles (List<SizeF>), en dp, qu'un peut prendre. Introduit dans Android 12.

onDeleted(Context, int[])

Cette méthode est appelée chaque fois qu'un widget est supprimé de son hôte.

onEnabled(Context)

Cette méthode est appelée lorsqu'une instance du widget est créée pour la première fois. Par exemple, si l'utilisateur ajoute deux instances de votre widget, cette méthode ne sera appelée pour la première fois. Si vous devez ouvrir une nouvelle base de données ou effectuer une autre configuration ne doit se produire qu'une seule fois pour toutes les instances de widget, c'est l'endroit idéal pour le faire.

onDisabled(Context)

Cette méthode est appelée lorsque la dernière instance de votre widget est supprimée de hôte du widget. C'est ici que vous nettoyez tout le travail effectué dans onEnabled(Context), comme la suppression d'une base de données temporaire.

onReceive(Context, Intent)

Cette méthode est appelée pour chaque annonce et avant chacun des rappels précédents. méthodes. Normalement, vous n'avez pas besoin d'implémenter cette méthode, car la méthode par défaut L'implémentation de AppWidgetProvider filtre toutes les diffusions de widget et appelle la les méthodes précédentes, le cas échéant.

Vous devez déclarer l'implémentation de votre classe AppWidgetProvider en tant que diffusion. récepteur à l'aide de l'élément <receiver> dans AndroidManifest. Reportez-vous à la section Déclarer un dans le fichier manifeste sur cette page.

Gérer les événements avec la classe onUpdate()

Le rappel AppWidgetProvider le plus important est onUpdate(), car il s'agit appelé lorsque chaque widget est ajouté à un hôte, sauf si vous utilisez une règle de configuration d'activité sans l'indicateur configuration_optional. Si votre widget accepte les d'interaction utilisateur, puis enregistrez les gestionnaires d'événements dans ce rappel. Si votre widget ne crée pas de fichiers temporaires ou de bases de données et n'effectue aucun autre travail qui nécessite un nettoyage, onUpdate() peut être la seule méthode de rappel que vous à définir.

Par exemple, si vous voulez un widget avec un bouton qui lance une activité lorsque vous pouvez utiliser l'implémentation suivante de AppWidgetProvider:

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

Cet élément AppWidgetProvider définit uniquement la méthode onUpdate() et l'utilise pour créer un PendingIntent qui lance un Activity et l'associe au bouton avec setOnClickPendingIntent(int, PendingIntent). Elle comprend une boucle qui itère chaque entrée. dans appWidgetIds, qui est un tableau d'ID identifiant chaque widget créé par ce fournisseur. Si l'utilisateur crée plusieurs instances du widget, alors ils sont tous mis à jour en même temps. Cependant, une seule planification updatePeriodMillis est géré pour toutes les instances du widget. Par exemple, si le calendrier de mise à jour est définie pour être exécutée toutes les deux heures, et une deuxième instance du widget est ajoutée une heure après la première, ils sont tous les deux mis à jour sur la période définie par la première et la deuxième période de mise à jour est ignorée. Elles se mettent à jour toutes les deux pas toutes les heures.

Consultez le ExampleAppWidgetProvider.java pour en savoir plus.

Recevoir des intents de diffusion de widget

AppWidgetProvider est une classe de commodité. Si vous souhaitez recevoir le widget diffuse directement, vous pouvez implémenter votre propre BroadcastReceiver ou ignorer la Rappel onReceive(Context,Intent). Les intents dont vous devez vous soucier sont suivantes:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Créer la mise en page de widget

Vous devez définir une mise en page initiale pour votre widget au format XML et l'enregistrer dans le fichier dans le répertoire res/layout/ du projet. Consultez la section Conception consignes.

La mise en page des widgets est simple si vous connaissez mises en page. Toutefois, sachez que les widgets les mises en page sont basées sur RemoteViews, qui n'est pas compatible avec tous les types de mise en page ou de widget de vue. Vous ne pouvez pas utiliser des vues ou des sous-classes des vues compatibles avec RemoteViews.

RemoteViews est également compatible avec ViewStub, qui est une View invisible de taille nulle que vous pouvez utiliser pour gonfler la mise en page de manière différée ressources lors de l'exécution.

Compatibilité avec le comportement avec état

Android 12 prend en charge le comportement avec état à l'aide des éléments suivants : composants existants:

• CheckBox

• Switch

• RadioButton

Le widget est toujours sans état. Votre application doit stocker l'état et s'inscrire à les événements de changement d'état.

L'exemple de code suivant montre comment implémenter ces composants.

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

Fournissez deux mises en page: l'une cible les appareils équipés d'Android 12 ou plus élevée dans res/layout-v31, tandis que l'autre ciblage Android 11 ou version antérieure dans le dossier res/layout par défaut.

Implémenter des angles arrondis

Android 12 introduit les paramètres système suivants pour définir le rayons des angles arrondis de votre widget:

• system_app_widget_background_radius: le rayon de l'angle de l'arrière-plan du widget, qui ne doit jamais dépasser 28 dp.

• system_app_widget_inner_radius: le rayon d'angle de n'importe quelle vue à l'intérieur du widget. Il fait exactement 8 dp. inférieur à l'arrondi de l'arrière-plan, pour un alignement optimal lors de l'utilisation d'une résolution de 8 dp. marge intérieure.

L'exemple suivant montre un widget qui utilise system_app_widget_background_radius pour l'angle du widget et system_app_widget_inner_radius pour les vues à l'intérieur du widget.

1 Coin du widget

2 Angle d'une vue dans le widget.

Remarques importantes concernant les angles arrondis

• Les lanceurs d'applications tiers et les fabricants d'appareils peuvent ignorer system_app_widget_background_radius doit être inférieure à 28 dp. Le paramètre system_app_widget_inner_radius est toujours inférieur de 8 dp à la valeur de system_app_widget_background_radius.
• Si votre widget n'utilise pas @android:id/background ou ne définit pas d'arrière-plan qui extrait son contenu en fonction du plan, avec android:clipToOutline définie sur true, le lanceur d'applications identifie automatiquement l'arrière-plan et rogne le widget à l'aide d'un rectangle dont les angles arrondis ne dépassent pas 16 dp. Consultez la section Vérifier que votre widget est compatible avec Android 12

Pour assurer la compatibilité des widgets avec les versions précédentes d'Android, nous vous recommandons définir des attributs personnalisés et utiliser un thème personnalisé pour les remplacer Android 12, comme illustré dans les exemples de fichiers XML suivants:

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

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

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

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

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />