Les Réglages rapides sont des blocs affichés dans le panneau Réglages rapides. Ils représentent les actions sur lesquelles les utilisateurs peuvent appuyer pour effectuer rapidement des tâches récurrentes.
Votre application peut fournir une carte personnalisée aux utilisateurs via la classe TileService et utiliser un objet Tile pour suivre l'état de la carte. Par exemple, vous pouvez créer une carte permettant aux utilisateurs d'activer ou de désactiver un VPN fourni par votre application.
Décider quand créer une carte
Nous vous recommandons de créer des cartes pour les fonctionnalités spécifiques auxquelles vous pensez que les utilisateurs auront besoin d'un accès rapide (ou les deux). Les cartes les plus efficaces sont celles qui correspondent à ces deux qualités et permettent d'accéder rapidement aux actions fréquemment effectuées.
Par exemple, vous pouvez créer une carte pour une application de fitness qui permettrait aux utilisateurs de démarrer rapidement une session d'entraînement. Toutefois, nous ne recommandons pas de créer une carte pour la même application qui permettrait aux utilisateurs de consulter l'intégralité de l'historique de leurs entraînements.
Pour améliorer la visibilité et la facilité d'utilisation de votre carte, nous vous recommandons d'éviter certaines pratiques:
Évitez d'utiliser des cartes pour lancer une application. Utilisez plutôt un raccourci d'application ou un lanceur d'applications standard.
Évitez d'utiliser des cartes pour des actions utilisateur ponctuelles. Utilisez plutôt un raccourci d'application ou une notification.
Évitez de créer trop de cartes. Nous vous recommandons d'en utiliser deux au maximum par application. Utilisez plutôt un raccourci d'application.
Évitez d'utiliser des cartes qui affichent des informations, mais ne sont pas interactives pour les utilisateurs. Utilisez plutôt une notification ou un widget.
Créer votre carte
Pour créer une carte, vous devez d'abord créer une icône de carte appropriée, puis créer et déclarer votre TileService dans le fichier manifeste de votre application.
L'exemple de Réglages rapides montre comment créer et gérer une carte.
Créer votre icône personnalisée
Vous devez fournir une icône personnalisée qui s'affiche sur la tuile dans le panneau "Quick Settings" (Réglages rapides). (Vous ajouterez cette icône lors de la déclaration de TileService, comme décrit dans la section suivante.) Elle doit être d'un blanc uni avec un arrière-plan transparent, mesurer 24 x 24 dp et se présenter sous la forme d'un VectorDrawable.
Créez une icône qui donne une indication visuelle sur l'objectif de votre carte. Les utilisateurs peuvent ainsi déterminer facilement si votre carte répond à leurs besoins. Par exemple, vous pouvez créer une icône de chronomètre pour une carte d'application de fitness, qui permet aux utilisateurs de démarrer une session d'entraînement.
Créer et déclarer votre TileService
Créez un service pour votre carte qui étend la classe TileService.
Kotlin
class MyQSTileService: TileService() {
// Called when the user adds your tile.
override fun onTileAdded() {
super.onTileAdded()
}
// Called when your app can update your tile.
override fun onStartListening() {
super.onStartListening()
}
// Called when your app can no longer update your tile.
override fun onStopListening() {
super.onStopListening()
}
// Called when the user taps on your tile in an active or inactive state.
override fun onClick() {
super.onClick()
}
// Called when the user removes your tile.
override fun onTileRemoved() {
super.onTileRemoved()
}
}
Java
public class MyQSTileService extends TileService {
// Called when the user adds your tile.
@Override
public void onTileAdded() {
super.onTileAdded();
}
// Called when your app can update your tile.
@Override
public void onStartListening() {
super.onStartListening();
}
// Called when your app can no longer update your tile.
@Override
public void onStopListening() {
super.onStopListening();
}
// Called when the user taps on your tile in an active or inactive state.
@Override
public void onClick() {
super.onClick();
}
// Called when the user removes your tile.
@Override
public void onTileRemoved() {
super.onTileRemoved();
}
}
Déclarez votre TileService dans le fichier manifeste de votre application. Ajoutez le nom et le libellé de votre TileService, l'icône personnalisée que vous avez créée dans la section précédente et l'autorisation appropriée.
<service
android:name=".MyQSTileService"
android:exported="true"
android:label="@string/my_default_tile_label" // 18-character limit.
android:icon="@drawable/my_default_icon_label"
android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
<intent-filter>
<action android:name="android.service.quicksettings.action.QS_TILE" />
</intent-filter>
</service>
Gérer votre TileService
Une fois que vous avez créé et déclaré votre TileService dans le fichier manifeste de votre application, vous devez gérer son état.
TileService est un service lié. Votre TileService est lié lorsqu'il est demandé par votre application ou si le système doit communiquer avec lui. Un cycle de vie de service lié type contient les quatre méthodes de rappel suivantes : onCreate(), onBind(), onUnbind() et onDestroy(). Ces méthodes sont appelées par le système chaque fois que le service entre dans une nouvelle phase de cycle de vie.
Présentation du cycle de vie de TileService
En plus des rappels qui contrôlent le cycle de vie du service lié, vous devez implémenter d'autres méthodes spécifiques au cycle de vie de l'TileService. Ces méthodes peuvent être appelées en dehors de onCreate() et de onDestroy(), car les méthodes de cycle de vie Service et TileService sont appelées dans deux threads asynchrones distincts.
Le cycle de vie d'une TileService contient les méthodes suivantes, qui sont appelées par le système chaque fois que votre TileService entre dans une nouvelle phase de cycle de vie:
onTileAdded(): cette méthode n'est appelée que lorsque l'utilisateur ajoute votre carte pour la première fois, et qu'il la supprime et l'ajoute à nouveau. C'est le meilleur moment pour effectuer une initialisation ponctuelle. Toutefois, cela peut ne pas suffire.onStartListening()etonStopListening(): ces méthodes sont appelées chaque fois que votre application met à jour la carte, et sont appelées souvent. LeTileServicereste lié entreonStartListening()etonStopListening(), ce qui permet à votre application de modifier la carte et d'envoyer des mises à jour.onTileRemoved(): cette méthode n'est appelée que si l'utilisateur supprime votre carte.
Sélectionner un mode d'écoute
Votre TileService écoute en mode actif ou non actif. Nous vous recommandons d'utiliser le mode actif, que vous devrez déclarer dans le fichier manifeste de l'application. Sinon, TileService est le mode standard et n'a pas besoin d'être déclaré.
Ne partez pas du principe que votre TileService se trouvera en dehors de la paire de méthodes onStartListening() et onStopListening().
Mode Actif (recommandé)
Utilisez le mode actif pour un TileService qui écoute et surveille son état dans son propre processus. Un TileService en mode actif est lié à onTileAdded(), à onTileRemoved(), aux événements d'appui et à la demande du processus de l'application.
Nous vous recommandons le mode actif si votre TileService est avertie lorsque l'état de votre carte doit être mis à jour par son propre processus. Les tuiles actives limitent la charge sur le système, car elles n'ont pas besoin d'être liées chaque fois que le panneau "Quick Settings" (Réglages rapides) devient visible par l'utilisateur.
La méthode statique TileService.requestListeningState() peut être appelée pour demander le démarrage de l'état d'écoute et recevoir un rappel à onStartListening().
Vous pouvez déclarer le mode actif en ajoutant META_DATA_ACTIVE_TILE au fichier manifeste de votre application.
<service ...>
<meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
android:value="true" />
...
</service>
Mode inactif
Le mode inactif est le mode standard. Un TileService est en mode inactif s'il est associé chaque fois que votre carte est visible par l'utilisateur. Cela signifie que votre TileService peut être créée et liée à nouveau à des moments indépendants de son contrôle. Elle peut également être dissociée et détruite lorsque l'utilisateur ne consulte pas la carte.
Votre application reçoit un rappel à onStartListening() une fois que l'utilisateur a ouvert le panneau "Quick Settings" (Réglages rapides). Vous pouvez mettre à jour votre objet Tile autant de fois que vous le souhaitez entre onStartListening() et onStopListening().
Vous n'avez pas besoin de déclarer le mode inactif. Il vous suffit de ne pas ajouter le META_DATA_ACTIVE_TILE au fichier manifeste de votre application.
Présentation des états des cartes
Une fois qu'un utilisateur a ajouté votre carte, celle-ci présente toujours l'un des états suivants.
STATE_ACTIVE: indique l'état "Activé" ou "Activé". L'utilisateur peut interagir avec votre carte dans cet état.Par exemple, pour une carte d'application de fitness qui permet aux utilisateurs de lancer une session d'entraînement chronométré,
STATE_ACTIVEsignifie que l'utilisateur a lancé une session d'entraînement et que le minuteur est en cours d'exécution.STATE_INACTIVE: indique qu'il est éteint ou en pause. L'utilisateur peut interagir avec votre carte dans cet état.Pour reprendre l'exemple de carte d'application de fitness, une carte dans
STATE_INACTIVEsignifie que l'utilisateur n'a pas démarré de session d'entraînement, mais qu'il pourrait le faire s'il le souhaite.STATE_UNAVAILABLE: indique un état temporairement indisponible. L'utilisateur ne peut pas interagir avec votre carte dans cet état.Par exemple, une carte dans
STATE_UNAVAILABLEsignifie que l'utilisateur n'y a pas accès actuellement pour une raison quelconque.
Le système ne définit que l'état initial de votre objet Tile. Vous définissez l'état de l'objet Tile pour le reste de son cycle de vie.
Le système peut teinter l'icône de la tuile et l'arrière-plan pour refléter l'état de votre objet Tile. Les objets Tile définis sur STATE_ACTIVE sont les plus sombres, avec STATE_INACTIVE et STATE_UNAVAILABLE de plus en plus clairs. La teinte exacte est spécifique au fabricant et à la version.
Mettre à jour votre carte
Vous pourrez mettre à jour votre carte après avoir reçu un rappel à onStartListening().
Selon le mode de la carte, votre carte peut être mise à jour au moins une fois jusqu'à ce qu'elle reçoive un rappel à onStopListening().
En mode actif, vous pouvez mettre à jour votre carte exactement une fois avant de recevoir un rappel vers onStopListening(). En mode inactif, vous pouvez mettre à jour votre carte autant de fois que vous le souhaitez entre onStartListening() et onStopListening().
Vous pouvez récupérer votre objet Tile en appelant getQsTile(). Pour mettre à jour des champs spécifiques de votre objet Tile, appelez les méthodes suivantes:
Une fois que vous avez défini les champs de l'objet Tile sur les valeurs appropriées, vous devez appeler updateTile() pour mettre à jour votre carte. Le système analysera alors les données de carte mises à jour et mettra à jour l'UI.
Kotlin
data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)
override fun onStartListening() {
super.onStartListening()
val state = getStateFromService()
qsTile.label = state.label
qsTile.contentDescription = tile.label
qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
qsTile.icon = state.icon
qsTile.updateTile()
}
Java
public class StateModel {
final boolean enabled;
final String label;
final Icon icon;
public StateModel(boolean e, String l, Icon i) {
enabled = e;
label = l;
icon = i;
}
}
@Override
public void onStartListening() {
super.onStartListening();
StateModel state = getStateFromService();
Tile tile = getQsTile();
tile.setLabel(state.label);
tile.setContentDescription(state.label);
tile.setState(state.enabled ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
tile.setIcon(state.icon);
tile.updateTile();
}
Gérer les appuis
Les utilisateurs peuvent appuyer sur votre carte pour déclencher une action si elle se trouve dans STATE_ACTIVE ou STATE_INACTIVE. Le système appelle ensuite le rappel onClick() de votre application.
Une fois que votre application reçoit un rappel à onClick(), elle peut lancer une boîte de dialogue ou une activité, déclencher une tâche en arrière-plan ou modifier l'état de votre carte.
Kotlin
var clicks = 0
override fun onClick() {
super.onClick()
counter++
qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
qsTile.label = "Clicked $counter times"
qsTile.contentDescription = qsTile.label
qsTile.updateTile()
}
Java
int clicks = 0;
@Override
public void onClick() {
super.onClick();
counter++;
Tile tile = getQsTile();
tile.setState((counter % 2 == 0) ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
tile.setLabel("Clicked " + counter + " times");
tile.setContentDescription(tile.getLabel());
tile.updateTile();
}
Ouvrir une boîte de dialogue
showDialog() réduit le panneau "Réglages rapides" et affiche une boîte de dialogue.
Utilisez une boîte de dialogue pour ajouter du contexte à votre action si elle nécessite une entrée supplémentaire ou le consentement de l'utilisateur.
Lancer une activité
startActivityAndCollapse() démarre une activité tout en réduisant le panneau. Les activités sont utiles si vous devez afficher des informations plus détaillées que dans une boîte de dialogue ou si votre action est très interactive.
Si votre application nécessite une interaction importante de l'utilisateur, elle ne doit lancer une activité qu'en dernier recours. Envisagez plutôt d'utiliser une boîte de dialogue ou un bouton d'activation/de désactivation.
Lorsque l'utilisateur appuie de manière prolongée sur une carte, l'écran App Info (Informations sur l'application) s'affiche. Pour ignorer ce comportement et lancer une activité pour définir les préférences, ajoutez un <intent-filter> à l'une de vos activités avec ACTION_QS_TILE_PREFERENCES.
Marquer votre carte comme activable
Nous vous recommandons de marquer votre carte comme activable si elle fonctionne principalement comme un commutateur à deux états (ce qui est le comportement le plus courant des cartes). Cela permet de fournir des informations sur le comportement de la carte au système d'exploitation et d'améliorer l'accessibilité globale.
Définissez les métadonnées TOGGLEABLE_TILE sur true pour marquer votre carte comme activable.
<service ...>
<meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
android:value="true" />
</service>
N'effectuer des actions sécurisées que sur des appareils verrouillés de façon sécurisée
Votre carte peut s'afficher en haut de l'écran de verrouillage sur les appareils verrouillés. Si la carte contient des informations sensibles, vérifiez la valeur de isSecure() pour déterminer si l'appareil est sécurisé. Votre TileService doit alors modifier son comportement en conséquence.
Si l'action de carte peut être effectuée sans risque lorsque l'appareil est verrouillé, utilisez startActivity() pour lancer une activité en haut de l'écran de verrouillage.
Si l'action de la carte n'est pas sécurisée, utilisez unlockAndRun() pour inviter l'utilisateur à déverrouiller son appareil. Si l'opération réussit, le système exécute l'objet Runnable que vous transmettez à cette méthode.
Inviter l'utilisateur à ajouter votre carte
Pour ajouter votre carte manuellement, les utilisateurs doivent suivre plusieurs étapes:
- Balayez l'écran vers le bas pour ouvrir le panneau "Réglages rapides".
- Appuyez sur le bouton "Modifier".
- faire défiler toutes les tuiles sur son appareil jusqu'à ce qu'il la trouve ;
- Maintenez votre vignette enfoncée et faites-la glisser vers la liste des vignettes actives.
L'utilisateur peut également déplacer ou supprimer votre vignette à tout moment.
À partir d'Android 13, vous pouvez utiliser la méthode requestAddTileService() pour permettre aux utilisateurs d'ajouter beaucoup plus facilement votre carte à un appareil. Cette méthode invite les utilisateurs à ajouter rapidement votre carte directement à leur panneau "Réglages rapides". L'invite inclut le nom de l'application, le libellé fourni et l'icône.
public void requestAddTileService (
ComponentName tileServiceComponentName,
CharSequence tileLabel,
Icon icon,
Executor resultExecutor,
Consumer<Integer> resultCallback
)
Le rappel contient des informations indiquant si la carte a été ajoutée ou non, si elle était déjà présente ou si une erreur s'est produite.
Faites preuve de discernement lorsque vous décidez quand et à quelle fréquence envoyer une invite aux utilisateurs. Nous vous recommandons d'appeler requestAddTileService() uniquement en contexte, par exemple lorsque l'utilisateur interagit pour la première fois avec une fonctionnalité proposée par votre carte.
Le système peut choisir d'arrêter le traitement des requêtes pour une ComponentName donnée si l'utilisateur l'a refusée suffisamment de fois. L'utilisateur est déterminé à partir du Context utilisé pour récupérer ce service. Il doit correspondre à l'utilisateur actuel.