Les raccourcis fournissent des types de contenu spécifiques à vos utilisateurs en les aidant à accéder rapidement à certaines parties de votre application.
![Image montrant le contraste entre les raccourcis d'application et les raccourcis épinglés](https://developer.android.google.cn/static/images/guide/topics/ui/shortcuts/pinned-shortcuts.png?authuser=5&hl=fr)
La manière dont vous fournissez du contenu avec des raccourcis dépend de votre cas d'utilisation et de si le contexte du raccourci est basé sur l'application ou sur l'utilisateur. Bien que le contexte d'un raccourci statique ne change pas et que le contexte d'un raccourci dynamique change constamment, votre application gère le contexte dans les deux cas. Dans les cas où un utilisateur choisit la manière dont votre application lui envoie du contenu, par exemple avec un raccourci épinglé, le contexte est défini par l'utilisateur. Les scénarios suivants décrivent quelques cas d'utilisation pour chaque type de raccourci:
- Les raccourcis statiques sont recommandés pour les applications qui renvoient au contenu à l'aide d'une structure cohérente tout au long de la durée d'interaction d'un utilisateur avec l'application. La plupart des lanceurs n'affichent que quatre raccourcis à la fois. Ils sont donc utiles pour effectuer une tâche de routine de manière cohérente, par exemple si l'utilisateur souhaite consulter son agenda ou ses e-mails d'une manière spécifique.
- Les raccourcis dynamiques sont utilisés pour les actions dans les applications sensibles au contexte. Les raccourcis contextuels sont adaptés aux actions que les utilisateurs effectuent dans une application. Par exemple, si vous créez un jeu qui permet à l'utilisateur de reprendre son niveau actuel au lancement, vous devez le mettre à jour fréquemment. L'utilisation d'un raccourci dynamique vous permet de le mettre à jour chaque fois que l'utilisateur efface un niveau.
- Les raccourcis épinglés sont utilisés pour des actions spécifiques dirigées par l'utilisateur. Par exemple, un utilisateur peut vouloir épingler un site Web spécifique dans le lanceur d'applications. Cette approche est utile, car elle permet à l'utilisateur d'effectuer une action personnalisée (par exemple, accéder au site Web en une seule étape) plus rapidement qu'en utilisant une instance par défaut d'un navigateur.
Créer des raccourcis statiques
Les raccourcis statiques fournissent des liens vers des actions génériques dans votre application. Ces actions doivent rester cohérentes pendant toute la durée de vie de la version actuelle de votre application. Les bonnes options pour les raccourcis statiques incluent l'affichage des messages envoyés, la définition d'une alarme et l'affichage de l'activité physique d'un utilisateur pour la journée.
Pour créer un raccourci statique, procédez comme suit:
-
Dans le fichier
AndroidManifest.xml
de votre application, recherchez l'activité dont les filtres d'intent sont définis sur l'actionandroid.intent.action.MAIN
et la catégorieandroid.intent.category.LAUNCHER
. -
Ajoutez à cette activité un élément
<meta-data>
qui référence le fichier de ressources dans lequel les raccourcis de l'application sont définis:<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.myapplication"> <application ... > <activity android:name="Main"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> <meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" /> </activity> </application> </manifest>
-
Créez un fichier de ressources nommé
res/xml/shortcuts.xml
. -
Dans le nouveau fichier de ressources, ajoutez un élément racine
<shortcuts>
contenant une liste d'éléments<shortcut>
. Dans chaque élément<shortcut>
, incluez des informations sur un raccourci statique, y compris son icône, ses libellés de description et les intents qu'il lance dans l'application:<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <shortcut android:shortcutId="compose" android:enabled="true" android:icon="@drawable/compose_icon" android:shortcutShortLabel="@string/compose_shortcut_short_label1" android:shortcutLongLabel="@string/compose_shortcut_long_label1" android:shortcutDisabledMessage="@string/compose_disabled_message1"> <intent android:action="android.intent.action.VIEW" android:targetPackage="com.example.myapplication" android:targetClass="com.example.myapplication.ComposeActivity" /> <!-- If your shortcut is associated with multiple intents, include them here. The last intent in the list determines what the user sees when they launch this shortcut. --> <categories android:name="android.shortcut.conversation" /> <capability-binding android:key="actions.intent.CREATE_MESSAGE" /> </shortcut> <!-- Specify more shortcuts here. --> </shortcuts>
Personnaliser les valeurs des attributs
La liste suivante inclut des descriptions des différents attributs dans un raccourci statique. Indiquez une valeur pour android:shortcutId
et android:shortcutShortLabel
. Toutes les autres valeurs sont facultatives.
-
android:shortcutId
-
Littéral de chaîne qui représente le raccourci lorsqu'un objet
ShortcutManager
effectue des opérations sur celui-ci. -
android:shortcutShortLabel
-
Formule concise décrivant l'objectif du raccourci. Si possible, limitez cette brève description à 10 caractères.
Pour en savoir plus, consultez
setShortLabel()
. -
android:shortcutLongLabel
-
Formule étendue décrivant l'objectif du raccourci. Si l'espace est suffisant, le lanceur affiche cette valeur au lieu de
android:shortcutShortLabel
. Si possible, limitez la description longue à 25 caractères.Pour en savoir plus, consultez
setLongLabel()
. -
android:shortcutDisabledMessage
-
Message qui s'affiche dans un lanceur d'applications compatible lorsque l'utilisateur tente de lancer un raccourci désactivé. Le message doit expliquer à l'utilisateur pourquoi le raccourci est désactivé. La valeur de cet attribut n'a aucun effet si
android:enabled
est défini surtrue
. -
android:enabled
-
Détermine si l'utilisateur peut interagir avec le raccourci à partir d'un lanceur d'applications compatible. La valeur par défaut de
android:enabled
esttrue
. Si vous la définissez surfalse
, définissez uneandroid:shortcutDisabledMessage
qui explique pourquoi vous désactivez le raccourci. Si vous pensez que vous n'avez pas besoin de fournir un tel message, supprimez complètement le raccourci du fichier XML. -
android:icon
-
Bitmap ou icône adaptative utilisé par le lanceur d'applications lors de l'affichage du raccourci auprès de l'utilisateur. Cette valeur peut être le chemin d'accès à une image ou le fichier de ressources qui la contient. Dans la mesure du possible, utilisez des icônes adaptatives pour améliorer les performances et la cohérence.
Configurer les éléments internes
Le fichier XML qui répertorie les raccourcis statiques d'une application est compatible avec les éléments suivants dans chaque élément <shortcut>
. Vous devez inclure un élément interne intent
pour chaque raccourci statique que vous définissez.
-
intent
-
Action lancée par le système lorsque l'utilisateur sélectionne le raccourci. Cet intent doit fournir une valeur pour l'attribut
android:action
.Vous pouvez fournir plusieurs intents pour un même raccourci. Pour en savoir plus, consultez Gérer plusieurs intents et activités, Définir un intent et la documentation de référence sur la classe
TaskStackBuilder
. -
categories
-
Fournit un regroupement des types d'actions effectuées par les raccourcis de votre application, comme la création de messages de chat.
Pour obtenir la liste des catégories de raccourcis compatibles, consultez la documentation de référence de la classe
ShortcutInfo
. -
capability-binding
-
Déclare l'élément capability associé au raccourci.
Dans l'exemple précédent, le raccourci est associé à une fonctionnalité déclarée pour
CREATE_MESSAGE
, qui est un intent intégré Actions dans les applications. Cette liaison de fonctionnalités permet aux utilisateurs d'utiliser des commandes vocales avec l'Assistant Google pour appeler un raccourci.
Créer des raccourcis dynamiques
Les raccourcis dynamiques fournissent des liens vers des actions spécifiques et sensibles au contexte dans votre application. Ces actions peuvent varier selon l'utilisation de votre application et pendant son exécution. Les raccourcis dynamiques sont utiles pour appeler une personne spécifique, naviguer vers un lieu spécifique et charger un jeu à partir du dernier point d'enregistrement de l'utilisateur. Vous pouvez également utiliser des raccourcis dynamiques pour ouvrir une conversation.
La bibliothèque Jetpack ShortcutManagerCompat
est une aide de l'API ShortcutManager
, qui vous permet de gérer les raccourcis dynamiques dans votre application. L'utilisation de la bibliothèque ShortcutManagerCompat
réduit le code récurrent et permet de garantir que vos raccourcis fonctionnent de manière cohérente sur toutes les versions d'Android. Cette bibliothèque est également nécessaire pour transmettre des raccourcis dynamiques afin qu'ils puissent apparaître sur les surfaces Google, telles que l'Assistant, à l'aide de la bibliothèque d'intégration de raccourcis Google.
L'API ShortcutManagerCompat
permet à votre application d'effectuer les opérations suivantes avec des raccourcis dynamiques:
-
Transférer et mettre à jour:utilisez
pushDynamicShortcut()
pour publier et mettre à jour vos raccourcis dynamiques. S'il existe déjà des raccourcis dynamiques ou épinglés avec le même ID, chaque raccourci modifiable est mis à jour. -
Suppression:supprimez un ensemble de raccourcis dynamiques avec
removeDynamicShortcuts()
. Supprimez tous les raccourcis dynamiques avecremoveAllDynamicShortcuts()
.
Pour en savoir plus sur l'exécution d'opérations sur les raccourcis, consultez la page Gérer les raccourcis et la documentation de référence sur ShortcutManagerCompat
.
Voici un exemple de création d'un raccourci dynamique et de son association à votre application:
Kotlin
val shortcut = ShortcutInfoCompat.Builder(context, "id1") .setShortLabel("Website") .setLongLabel("Open the website") .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website)) .setIntent(Intent(Intent.ACTION_VIEW, Uri.parse("https://www.mysite.example.com/"))) .build() ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)
Java
ShortcutInfoCompat shortcut = new ShortcutInfoCompat.Builder(context, "id1") .setShortLabel("Website") .setLongLabel("Open the website") .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website)) .setIntent(new Intent(Intent.ACTION_VIEW, Uri.parse("https://www.mysite.example.com/"))) .build(); ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);
Ajouter la bibliothèque d'intégration de raccourcis Google
La bibliothèque d'intégration de raccourcis Google est une bibliothèque Jetpack facultative. Il vous permet d'envoyer des raccourcis dynamiques pouvant être affichés sur les surfaces Android, telles que le lanceur d'applications, et sur les surfaces Google, comme l'Assistant. Cette bibliothèque permet aux utilisateurs de découvrir vos raccourcis pour accéder rapidement à des contenus spécifiques ou des actions de rejeu dans votre application.
Par exemple, une application de chat peut envoyer un raccourci dynamique pour un contact nommé "Alex" après qu'un utilisateur a envoyé un message à cette personne. Une fois le raccourci dynamique envoyé, si l'utilisateur demande à l'Assistant "Hey Google, envoie un message à Alex sur ExempleApp", l'Assistant peut lancer ExampleApp et le configurer automatiquement pour envoyer un message à Alex.
Les raccourcis dynamiques transmis avec cette bibliothèque ne sont pas soumis aux limites de raccourcis appliquées à chaque appareil. Cela permet à votre application d'envoyer un raccourci chaque fois qu'un utilisateur effectue une action associée dans votre application. En déployant des raccourcis fréquents, vous permettez à Google de comprendre les habitudes d'utilisation de votre utilisateur et de lui suggérer des raccourcis pertinents d'un point de vue contextuel.
Par exemple, l'Assistant peut apprendre à partir des raccourcis transmis à partir de votre application de suivi de remise en forme qu'un utilisateur exécute généralement chaque matin et suggérer de manière proactive un raccourci "commencer une course à pied" lorsque l'utilisateur prend son téléphone le matin.
La bibliothèque d'intégration de raccourcis Google n'offre aucune fonctionnalité adressable. L'ajout de cette bibliothèque à votre application permet aux surfaces Google d'utiliser les raccourcis transmis par votre application à l'aide de ShortcutManagerCompat
.
Pour utiliser cette bibliothèque dans votre application, procédez comme suit:
-
Mettez à jour votre fichier
gradle.properties
pour qu'il soit compatible avec les bibliothèques AndroidX:android.useAndroidX=true # Automatically convert third-party libraries to use AndroidX android.enableJetifier=true
-
Dans
app/build.gradle
, ajoutez des dépendances pour la bibliothèque d'intégration de raccourcis Google etShortcutManagerCompat
:dependencies { implementation "androidx.core:core:1.6.0" implementation 'androidx.core:core-google-shortcuts:1.0.0' ... }
Une fois les dépendances de bibliothèque ajoutées à votre projet Android, votre application peut utiliser la méthode pushDynamicShortcut()
de ShortcutManagerCompat
pour transférer des raccourcis dynamiques pouvant être affichés dans le lanceur d'applications et sur les surfaces Google participantes.
Créer des raccourcis épinglés
Sur Android 8.0 (niveau d'API 26) ou version ultérieure, vous pouvez créer des raccourcis épinglés. Contrairement aux raccourcis statiques et dynamiques, les raccourcis épinglés s'affichent dans les lanceurs d'applications sous forme d'icônes distinctes. La figure 1 montre la distinction entre ces deux types de raccourcis.
Pour épingler un raccourci à un lanceur d'applications compatible à l'aide de votre application, procédez comme suit:
-
Utilisez
isRequestPinShortcutSupported()
pour vérifier que le lanceur d'applications par défaut de l'appareil est compatible avec l'épinglage des raccourcis dans l'application. -
Créez un objet
ShortcutInfo
de l'une des deux manières suivantes, selon que le raccourci existe ou non:-
Si le raccourci existe, créez un objet
ShortcutInfo
ne contenant que l'ID du raccourci existant. Le système trouve et épingle automatiquement toutes les autres informations liées au raccourci. -
Si vous épinglez un nouveau raccourci, créez un objet
ShortcutInfo
contenant un ID, un intent et un libellé abrégé pour le nouveau raccourci.
-
Si le raccourci existe, créez un objet
-
Épinglez le raccourci dans le lanceur d'applications de l'appareil en appelant
requestPinShortcut()
. Au cours de ce processus, vous pouvez transmettre un objetPendingIntent
, qui avertit votre application uniquement lorsque le raccourci a bien été épinglé.Une fois qu'un raccourci est épinglé, votre application peut mettre à jour son contenu à l'aide de la méthode
updateShortcuts()
. Pour en savoir plus, consultez Mettre à jour les raccourcis.
L'extrait de code suivant montre comment créer un raccourci épinglé.
Kotlin
val shortcutManager = getSystemService(ShortcutManager::class.java) if (shortcutManager!!.isRequestPinShortcutSupported) { // Enable the existing shortcut with the ID "my-shortcut". val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build() // Create the PendingIntent object only if your app needs to be notified // that the user let the shortcut be pinned. If the pinning operation fails, // your app isn't notified. Assume here that the app implements a method // called createShortcutResultIntent() that returns a broadcast intent. val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo) // Configure the intent so that your app's broadcast receiver gets the // callback successfully. For details, see PendingIntent.getBroadcast(). val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0, pinnedShortcutCallbackIntent, /* flags */ 0) shortcutManager.requestPinShortcut(pinShortcutInfo, successCallback.intentSender) }
Java
ShortcutManager shortcutManager = context.getSystemService(ShortcutManager.class); if (shortcutManager.isRequestPinShortcutSupported()) { // Enable the existing shortcut with the ID "my-shortcut". ShortcutInfo pinShortcutInfo = new ShortcutInfo.Builder(context, "my-shortcut").build(); // Create the PendingIntent object only if your app needs to be notified // that the user let the shortcut be pinned. If the pinning operation fails, // your app isn't notified. Assume here that the app implements a method // called createShortcutResultIntent() that returns a broadcast intent. Intent pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo); // Configure the intent so that your app's broadcast receiver gets the // callback successfully. For details, see PendingIntent.getBroadcast(). PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0, pinnedShortcutCallbackIntent, /* flags */ 0); shortcutManager.requestPinShortcut(pinShortcutInfo, successCallback.getIntentSender()); }
Créer une activité de raccourci personnalisé
![Image montrant l'activité de la boîte de dialogue personnalisée qui affiche l'invite "Do you want to add the Gmail launcher icon to your home screen?" (Voulez-vous ajouter l'icône du lanceur d'applications Gmail à votre écran d'accueil ?) Les options personnalisées sont "Non, merci" et "Ajouter une icône".](https://developer.android.google.cn/static/images/guide/topics/ui/shortcuts/pinned-shortcuts-dialog.png?authuser=5&hl=fr)
Vous pouvez également créer une activité spécialisée qui aide les utilisateurs à créer des raccourcis, avec des options personnalisées et un bouton de confirmation. La figure 2 illustre un exemple de ce type d'activité dans l'application Gmail.
Dans le fichier manifeste de votre application, ajoutez ACTION_CREATE_SHORTCUT
à l'élément <intent-filter>
de l'activité. Cette déclaration configure le comportement suivant lorsque l'utilisateur tente de créer un raccourci:
- Le système lance l'activité spécialisée de votre application.
- L'utilisateur définit les options du raccourci.
- L'utilisateur sélectionne le bouton de confirmation.
-
Votre application crée le raccourci à l'aide de la méthode
createShortcutResultIntent()
. Cette méthode renvoie unIntent
, que votre application relaie à l'activité en cours d'exécution précédente à l'aide desetResult()
. -
Votre application appelle
finish()
sur l'activité utilisée pour créer le raccourci personnalisé.
De même, votre application peut inviter les utilisateurs à ajouter des raccourcis épinglés à l'écran d'accueil après l'installation ou la première fois que l'application est lancée. Cette méthode est efficace, car elle aide vos utilisateurs à créer un raccourci dans le cadre de leur workflow ordinaire.
Tester les raccourcis
Pour tester les raccourcis de votre application, installez-la sur un appareil doté d'un lanceur d'applications compatible. Ensuite, effectuez les actions suivantes:
- Appuyez de manière prolongée sur l'icône de lanceur de votre application pour afficher les raccourcis que vous avez définis pour cette application.
- Faites glisser un raccourci pour l'épingler dans le lanceur d'applications de l'appareil.