Vous pouvez configurer les widgets d'application. Par exemple, un widget d'horloge permet aux utilisateurs configurer le fuseau horaire à afficher.
Si vous souhaitez autoriser les utilisateurs à configurer les paramètres de votre widget, créez un widget
configuration Activity
. Cette activité est
lancé automatiquement par l'hôte du widget d'application, que ce soit lors de la création du widget
ou ultérieure, en fonction des options de configuration que vous
spécifier.
Déclarer l'activité de configuration
Déclarer l'activité de configuration comme une activité normale dans le fichier manifeste Android
. L'hôte du widget d'application le lance avec
ACTION_APPWIDGET_CONFIGURE
l'activité doit donc accepter cet intent. Exemple :
<activity android:name=".ExampleAppWidgetConfigurationActivity">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
</intent-filter>
</activity>
Déclarez l'activité dans le fichier AppWidgetProviderInfo.xml
avec la
android:configure
. En savoir plus sur
déclarer ce fichier. Voici un exemple
comment déclarer l'activité de configuration:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
...
android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
... >
</appwidget-provider>
L'activité est déclarée avec un espace de noms complet, car le lanceur d'applications le référence depuis l'extérieur du champ d'application de votre package.
Vous n'avez besoin de rien d'autre pour démarrer une activité de configuration. Ensuite, vous devez pour mettre en œuvre l'activité proprement dite.
Implémenter l'activité de configuration
Il y a deux points importants à retenir lorsque vous mettez en œuvre l'activité:
- L'hôte du widget d'application appelle l'activité de configuration, et la configuration
l'activité doit toujours renvoyer un résultat. Le résultat doit inclure le widget d'application.
ID transmis par l'intent qui a lancé l'activité (enregistré dans l'intent)
extras comme
EXTRA_APPWIDGET_ID
- Le système n'envoie pas
ACTION_APPWIDGET_UPDATE
lorsqu'une activité de configuration est lancée, ce qui signifie qu'elle n'est pas appeler la méthodeonUpdate()
lors de la création du widget. Il est de la responsabilité de l'activité de configuration de demander une mise à jourAppWidgetManager
lorsque vous créez le widget pour la première fois. Toutefois,onUpdate()
est appelé pour les mises à jour ultérieures. Il n'ignore que la méthode pour la première fois.
Consultez les extraits de code dans la section suivante pour savoir comment renvoyer une de la configuration et mettre à jour le widget.
Mettre à jour le widget à partir de l'activité de configuration
Lorsqu'un widget utilise une activité de configuration,
l'activité pour mettre à jour le widget une fois la configuration terminée. Pour ce faire, procédez comme suit :
en demandant une mise à jour directement
AppWidgetManager
Voici un récapitulatif de la procédure à suivre pour mettre à jour le widget et fermer activité de configuration:
Obtenez l'ID du widget d'application à partir de l'intent qui a lancé l'activité:
Kotlin
val appWidgetId = intent?.extras?.getInt( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
Java
Intent intent = getIntent(); Bundle extras = intent.getExtras(); int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID; if (extras != null) { appWidgetId = extras.getInt( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); }
Définissez le résultat de l'activité sur
RESULT_CANCELED
.De cette façon, si l'utilisateur quitte l'activité avant d'atteindre la fin, système informe l'hôte du widget d'application que la configuration est annulée et l'hôte n'ajoute pas le widget:
Kotlin
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_CANCELED, resultValue)
Java
int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); setResult(Activity.RESULT_CANCELED, resultValue);
Configurez le widget en fonction des préférences de l'utilisateur.
Une fois la configuration terminée, récupérez une instance de
AppWidgetManager
en appelantgetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
Mettez à jour le widget avec une la mise en page
RemoteViews
en appelantupdateAppWidget(int,RemoteViews)
:Kotlin
val views = RemoteViews(context.packageName, R.layout.example_appwidget) appWidgetManager.updateAppWidget(appWidgetId, views)
Java
RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget); appWidgetManager.updateAppWidget(appWidgetId, views);
Créez l'intent renvoyé, définissez-le avec le résultat de l'activité, puis terminer l'activité:
Kotlin
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_OK, resultValue) finish()
Java
Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); setResult(RESULT_OK, resultValue); finish();
Consultez le
ListWidgetConfigureActivity.kt
sur GitHub.
Options de configuration du widget
Par défaut, l'hôte du widget d'application ne lance l'activité de configuration qu'une seule fois, immédiatement après que l'utilisateur a ajouté le widget à son écran d'accueil. Cependant, vous Vous pouvez spécifier des options permettant aux utilisateurs de reconfigurer des widgets existants ignorer la configuration initiale du widget en fournissant une configuration de widget par défaut.
Permettre aux utilisateurs de reconfigurer les widgets placés
Pour permettre aux utilisateurs de reconfigurer des widgets existants, indiquez
reconfigurable
dans la section
widgetFeatures
de appwidget-provider
. Consultez le guide pour déclarer la
AppWidgetProviderInfo.xml
pour en savoir plus
des informations. Exemple :
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
Les utilisateurs peuvent reconfigurer leur widget en appuyant sur & en maintenant le widget enfoncé et en appuyant le bouton Reconfigure (Reconfigurer) : 1 sur la figure 1.
![Le bouton apparaît en bas à droite](https://developer.android.com/static/images/appwidgets/widget-reconfigure-button.png?authuser=9&hl=fr)
Utiliser la configuration par défaut du widget
Vous pouvez offrir une expérience de widget plus fluide en permettant aux utilisateurs d'ignorer
l'étape de configuration initiale. Pour ce faire, spécifiez à la fois
configuration_optional
et reconfigurable
dans le champ widgetFeatures
. Cela permet de contourner
lancer l'activité de configuration après qu'un utilisateur a ajouté le widget. Comme indiqué précédemment
auparavant, l'utilisateur peut toujours reconfigurer le widget.
par la suite. Par exemple, un widget d'horloge peut contourner la configuration initiale
afficher le fuseau horaire de l'appareil par défaut.
Voici un exemple montrant comment marquer votre activité de configuration comme reconfigurable et facultatif:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>