Android – Vue de paramètres rapides des paramètres rapides (créer des vignettes de paramètres rapides personnalisées)

Introduction

Les paramètres rapides sont des vignettes qui apparaissent dans le volet Paramètres rapides et représentent des actions sur lesquelles les utilisateurs peuvent appuyer pour effectuer rapidement des tâches récurrentes. Votre application peut fournir aux utilisateurs des vignettes personnalisées via la classe TileService et utiliser l'objet tuile pour suivre l'état de la vignette. Par exemple, vous pouvez créer un en-tête permettant aux utilisateurs d'activer ou de désactiver le VPN proposé par votre application.

Scénarios pour les vignettes Paramètres rapides

Nous vous recommandons de créer des vignettes pour des fonctionnalités spécifiques auxquelles les utilisateurs accèdent fréquemment ou auxquelles ils ont besoin d'un accès rapide (ou les deux). Les textures les plus efficaces sont celles qui combinent ces deux qualités, donnant aux joueurs un accès rapide aux actions fréquemment effectuées.

Par exemple, vous pouvez créer un titre pour une application de fitness permettant aux utilisateurs de démarrer rapidement une séance d'entraînement. Cependant, nous ne recommandons pas de créer un en-tête pour la même application qui permet aux utilisateurs de visualiser l'intégralité de leur historique d'entraînement.

Pour améliorer la visibilité et la facilité d'utilisation des vignettes, nous vous recommandons d'éviter les pratiques suivantes :

• Évitez d'utiliser des vignettes pour lancer des applications. Utilisez des raccourcis d'application ou des lanceurs standards.
• Évitez d'utiliser des vignettes pour des actions utilisateur ponctuelles. Utilisez plutôt les raccourcis d’applications ou les notifications.
• Évitez de créer trop de tuiles. Un maximum de deux par application est recommandé.
• Évitez les vignettes qui affichent des informations mais ne peuvent pas interagir avec l'utilisateur. Utilisez plutôt des notifications ou des widgets.

Créer des tuiles

Pour créer une vignette, vous devez d'abord créer une icône de vignette appropriée, puis créer et déclarer votre TileService dans le fichier manifeste de votre application.

Remarque : La création d'un service de vignettes pour votre application ne l'ajoute pas au panneau de paramètres rapides de l'utilisateur. Ce n'est qu'une fois que l'utilisateur a ajouté une vignette que votre service de vignettes fera office d'interface de la vignette.

Créer des icônes personnalisées

Une icône personnalisée doit être fournie, qui est affichée sur la vignette dans le panneau Paramètres rapides (elle sera ajoutée lors de la déclaration du TileService). Les icônes doivent être d'un blanc uni avec un fond transparent, avoir une taille de 24 x 24 dp et VectorDrawableêtre présentées au format .
Créez une icône qui fait visuellement allusion au but de votre titre. Cela aide les utilisateurs à identifier facilement si votre tuile répond à leurs besoins. Par exemple, vous pouvez créer une icône de chronomètre pour le titre d'une application de fitness qui permet aux utilisateurs de commencer à faire de l'exercice.

Créez et déclarez votre service de tuiles

TileServiceCréez un service qui étend la classe pour les tuiles .

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();
  }
}

manifestDéclarez le vôtre dans les fichiers de votre application TileService. Ajoutez votre TileServicenom et vos balises, l'icône personnalisée créée dans la section précédente et les autorisations appropriées.

 <service
     android:name=".MyQSTileService"
     android:label="@string/my_default_tile_label"
     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érez votre service de tuiles

Une fois que vous avez créé et déclaré votre TileService dans le manifeste de l'application, vous devez gérer son état.
TileServiceest un service lié. TileServiceLe vôtre est lié lorsque votre application le demande ou lorsque le système a besoin de communiquer avec elle . Un cycle de vie de service lié typique contient les quatre méthodes de rappel suivantes : onCreate(), et . Ces méthodes sont appelées chaque fois que le service entre dans une nouvelle phase du cycle de vie.onBind()onUnbind()onDestroy()

Remarque : le vôtre TileServicesuivra toujours le cycle de vie de service typique. Cependant, TileServiceil diffère de la plupart des autres services liés dans la mesure où il inclut TileServicedes méthodes de cycle de vie spécifiques auxquelles l'application doit répondre.

Cycle de vie du TileService

Outre les 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 du service de tuiles. Ces méthodes peuvent être appelées en dehors de onCreate()et onDestroy()parce que Serviceles méthodes de cycle de vie et TileServiceles méthodes de cycle de vie sont appelées dans deux threads asynchrones distincts.

TileServiceLe cycle de vie contient les méthodes suivantes, TileServicequi sont appelées par le système chaque fois que votre objet entre dans une nouvelle phase du cycle de vie :

• onTileAdded(): Cette méthode n'est appelée que lorsque l'utilisateur ajoute votre vignette pour la première fois, et si l'utilisateur supprime et ajoute à nouveau votre vignette. C'est le moment idéal pour effectuer une initialisation unique. Cependant, cela peut ne pas satisfaire toutes les initialisations requises.

Description : La tuile a déjà été créée et onTileAdded()ne sera pas appelée. Par exemple, si une vignette a été ajoutée et n'a pas été supprimée avant la mise hors tension de l'appareil, elle ne sera pas appelée au redémarrage ou à la mise sous tension de l'appareil onTileAdded().

• onStartListening()etonstoppllistening() : ces méthodes sont appelées lorsque l'application met à jour la vignette et sont appelées fréquemment. TileServiceToujours lié entre onStartListening()et onstoppllistening(), permettant à votre application de modifier les vignettes et de diffuser des mises à jour.
• onTileRemoved(): Cette méthode n'est appelée que lorsque l'utilisateur supprime votre autocollant.

Explication : Ces phases peuvent ne pas se produire consécutivement. onTileAdded()Probablement appelé une seule fois lorsque l'utilisateur ajoute une vignette à son panneau Paramètres rapides. onStartListening()et onstoppllistening()peut être appelé plusieurs fois au cours du cycle de vie du service de tuiles. onTileRemoved()Ne sera jamais appelé si l'utilisateur n'a pas supprimé votre texture de son panneau de paramètres rapides .

Sélectionnez le mode moniteur

Votre écoute TileServiceen mode actif ou en mode non actif . Il est recommandé d'utiliser le modèle d'activité que vous devez déclarer dans le manifeste de l'application. Sinon, TileServicec'est le mode standard et aucune déclaration n'est requise.

Mode actif (recommandé)

Pour TileServiceson utilisation active mode, il écoute et surveille son statut dans son propre processus. non-active modeDans le mode, TileServiceil est lié aux événements onTileAdded(), onTileRemoved(), tap et à la demande du processus de candidature.

Nous vous recommandons d'utiliser le mode actif si votre service de tuiles est averti lorsque l'état de votre tuile doit être mis à jour par son propre processus. Les vignettes dynamiques limitent la pression sur le système car elles n'ont pas besoin d'être liées à chaque fois que le panneau de paramètres rapides devient visible pour l'utilisateur.

Une méthode statique TileService.requestListeningState()peut être appelée pour demander le début de l'état d'écoute et recevoir onStartListening()un rappel pour l'objet.

Vous pouvez déclarer le mode actif en ajoutant le manifestfichier de l'application .META_DATA_ACTIVE_TILE

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
         android:value="true" />
    ...
</service>

Mode non actif

Le mode non actif est le mode standard. Lorsque votre vignette est visible par l'utilisateur, elle est en mode non actif si elle est liée à un service de vignette. Cela signifie que le vôtre TileServicepeut être créé et lié à nouveau dans des circonstances indépendantes de sa volonté. Il est également possible de dissocier et de détruire la vignette lorsque l'utilisateur ne la visualise pas.

Le rappel que votre application reçoit une fois que l'utilisateur ouvre son panneau de paramètres rapides onStartListening(). Vous pouvez mettre à jour l'objet Tile autant que vous le souhaitez entre onStartListening()et .onstoppllistening()

Remarque : Si vous utilisez le mode non actif au lieu du mode actif, le vôtre TileServicepeut être lié à chaque fois qu'un utilisateur ouvre son panneau de paramètres rapides.

Vous n'avez pas besoin de déclarer le mode non actif, mais ne META_DATA_ACTIVE_TILEl'ajoutez pas aux fichiers de votre application manifest.

Statut de la vignette

Une fois qu'un utilisateur a ajouté votre vignette, elle existe toujours dans l'un des états suivants.

• STATE_ACTIVE: État Activé ou Activé. Dans cet état, l'utilisateur peut interagir avec la vignette.
  Par exemple, pour le titre d’une application de fitness qui permet à l’utilisateur de démarrer une séance d’entraînement chronométrée, STATE_ACTIVEcela signifierait que l’utilisateur a déjà commencé la séance d’entraînement et que le chronomètre est en cours d’exécution.
• STATE_INACTIVE: État fermé ou en pause. Dans cet état, l'utilisateur peut interagir avec la vignette.
  En utilisant à nouveau l'exemple de vignette de l'application de fitness, STATE_INACTIVEla vignette signifie que l'utilisateur n'a pas encore commencé une séance d'entraînement, mais qu'il pourrait le faire s'il le souhaitait.
• STATE_UNAVAILABLE: Temporairement indisponible. Dans cet état, l’utilisateur ne peut pas interagir avec la vignette.
  Par exemple, STATE_UNAVAILABLEune vignette dans signifie que, pour une raison quelconque, la vignette n'est actuellement pas disponible pour l'utilisateur.

Description : Sera STATE_UNAVAILABLEutilisé pour les tuiles qui ne sont actuellement pas disponibles mais qui pourraient le devenir ultérieurement. COMPONENT_ENABLED_STATE_DISABLEDSera transmis à si l'utilisateur ne peut plus utiliser le composant setComponentEnabledSetting().

Le système définit uniquement l'état initial de l'objet Tile. Définit l'état de l'objet Tile pour le reste de sa durée de vie.

Mettre à jour les vignettes

Vous pouvez onStartListening()mettre à jour vos vignettes après avoir reçu le rappel. Selon le mode de la vignette, la vignette peut être mise à jour au moins une fois jusqu'à ce qu'un rappel soit reçu onStoppListening().
En mode , vous pouvez mettre à jour votre vignette une fois avant de activerecevoir le rappel. onStoppListening()En non-activemode , vous pouvez mettre à jour vos tuiles autant que vous le souhaitez entre et onStartListening().onStoppListening()

Vous pouvez getQsTile()récupérer un objet Tile en appelant Pour mettre à jour un champ spécifique d'un objet Tile, appelez la méthode suivante :

• setContentDescription()
• setIcon()
• setLabel()
• setState()
• setStateDescription()
• setSubtitle()

Description : les icônes et les étiquettes définies dans le fichier manifeste de votre application sont les valeurs par défaut affichées sur les vignettes du panneau Paramètres rapides. Cependant, les méthodes setIcon() et setLabel() peuvent être appelées pour définir les champs sur de nouvelles valeurs lors de la mise à jour de la vignette.

Une fois que le champ d'un objet tuile a été défini sur une nouvelle valeur, il doit être appelé updateTile()pour mettre à jour la tuile. Cela amènera le système à analyser les données des vignettes mises à jour et à mettre à jour l'interface utilisateur.

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 l'événement Tap

Si votre autocollant est à l' état STATE_ACTIVEou STATE_INACTIVE, l'utilisateur peut cliquer sur votre autocollant pour déclencher une action. Le système appelle ensuite le onClick()rappel de l'application.

Une fois que votre application reçoit onClick()le rappel, elle peut démarrer une boîte de dialogue ou une activité, déclencher un travail en arrière-plan ou modifier l'état de vos vignettes.

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();
}

démarrer la boîte de dialogue

showDialog()Réduit le panneau Paramètres rapides et affiche une boîte de dialogue. Si une saisie supplémentaire ou le consentement de l'utilisateur est requis, des boîtes de dialogue peuvent être utilisées pour ajouter du contexte à l'action.

Description : isLocked()Vérifie si l'écran de verrouillage de l'utilisateur est affiché. Lors isLocked()du retour true, showDialog()une boîte de dialogue visible ne s'affiche pas car elle se charge sous l'écran de verrouillage.

Démarrer l'activité

startActivityAndCollapse()Commencez-en un lorsque le panneau est réduit Activity. ActivityUtile si vous souhaitez afficher des informations plus détaillées qu'une boîte de dialogue, ou si vos opérations sont hautement interactives .

Si votre application nécessite beaucoup d’interactions utilisateur, elle doit en lancer une Activityen dernier recours. Pensez plutôt à utiliser des boîtes de dialogue ou des commutateurs.

Un appui long sur une vignette invitera l'utilisateur à accéder à l'interface d'informations sur l'application. Pour remplacer ce comportement et en démarrer un Activitypour définir les préférences, utilisez ACTION_QS_TILE_PREFERENCESAjouter à l'une des activités <intent-filter>.

Marquer les vignettes comme basculables

Si votre texture est principalement utilisée comme commutateur entre deux états (c'est le comportement le plus courant des textures), nous vous recommandons de la marquer comme basculable. Cela permet de fournir des informations au système d'exploitation sur le comportement de la vignette et d'améliorer l'accessibilité générale.

Définissez TOGGLEABLE_TILEles métadonnées truepour marquer votre vignette comme basculable.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

Les opérations de sécurité ne peuvent être effectuées que sur des appareils verrouillés en toute sécurité

Sur les appareils verrouillés, des vignettes peuvent apparaître en haut de l'écran de verrouillage. Si la vignette contient des informations sensibles, vérifiez isSecure()la valeur de s pour déterminer si l'appareil est dans un état sécurisé et le vôtre TileServicedevrait modifier son comportement en conséquence.

S'il est sécuritaire d'effectuer des opérations de mosaïque tout en étant verrouillé, utilisez startActivity()Lancer une activité en haut de l'écran de verrouillage.

unlockAndRun()Utilisez -le pour inviter l'utilisateur à déverrouiller son appareil si l'opération de vignette n'est pas sécurisée . En cas de succès, le système exécute Runnablel'objet transmis dans cette méthode.

Inviter l'utilisateur à ajouter une vignette

Pour ajouter manuellement des tuiles, l'utilisateur doit suivre quelques étapes :

• Faites glisser votre doigt vers le bas pour ouvrir le panneau des paramètres rapides.
• Cliquez sur le bouton Modifier.
• Faites défiler tous les autocollants sur votre appareil jusqu'à ce que vous trouviez le vôtre.
• Appuyez et maintenez votre vignette et faites-la glisser vers la liste des vignettes dynamiques.

Les utilisateurs peuvent également déplacer ou supprimer vos vignettes à tout moment. À partir d’Android 13, vous pouvez utiliser requestAddTileService()des méthodes pour permettre aux utilisateurs d’ajouter plus facilement vos vignettes à l’appareil. Cette méthode invite l'utilisateur à demander que votre vignette soit rapidement ajoutée directement à son panneau Paramètres rapides. L'invite inclut le nom de l'application, l'étiquette fournie et l'icône.

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

Le rappel contient des informations indiquant s'il a été ajouté, non ajouté, s'il existe déjà ou si des erreurs se sont produites. Faites preuve de discrétion pour décider quand et à quelle fréquence inviter l'utilisateur. Nous vous recommandons d'appeler cela uniquement dans son contexte requestAddTileService(), par exemple lorsque l'utilisateur interagit pour la première fois avec la fonctionnalité facilitée par votre vignette.

Description : Nous vous recommandons d'appeler requestAddTileService()pour augmenter la visibilité de vos vignettes et réduire la charge imposée aux utilisateurs par l'ajout de vos vignettes au panneau de paramètres rapides.