Questa pagina è stata tradotta dall'API Cloud Translation.

Creare riquadri delle Impostazioni rapide personalizzati per la tua app

Le Impostazioni rapide sono riquadri visualizzati nel riquadro Impostazioni rapide. che rappresentano azioni, che gli utenti possono toccare per completare rapidamente le attività ricorrenti. La tua app può fornire un riquadro personalizzato agli utenti tramite TileService e utilizza un oggetto Tile per monitorare lo stato del riquadro. Ad esempio: potresti creare un riquadro che consenta agli utenti di attivare una VPN fornita dalla tua app disattivata.

Riquadro Impostazioni rapide con il riquadro VPN attivato
on e off — **Figura 1.** Riquadro Impostazioni rapide con il riquadro VPN attivato e disattivato.

Decidere quando creare un riquadro

Consigliamo di creare riquadri per le funzionalità specifiche che ti aspetti dagli utenti per poter accedere spesso o che necessitano di un accesso rapido (o entrambi). I riquadri più efficaci sono quelli che soddisfano entrambe queste caratteristiche, fornendo un accesso rapido alle azioni eseguite di frequente.

Ad esempio, puoi creare un riquadro per un'app per il fitness che consenta agli utenti di avviare rapidamente una sessione di allenamento. Tuttavia, sconsigliamo di creare un riquadro per la stessa app che consenta agli utenti di esaminare l'intera cronologia degli allenamenti.

Casi d'uso dei riquadri delle app per il fitness — **Figura 2**. Esempi di riquadri consigliati e non consigliati per un'app per il fitness.

Per migliorare la rilevabilità e la facilità d'uso del riquadro, ti consigliamo evitare alcune pratiche:

Evita di utilizzare riquadri per avviare un'app. Utilizza una scorciatoia dell'app o una scorciatoia standard in Avvio applicazioni.
Evita di utilizzare riquadri per azioni utente una tantum. Utilizza una scorciatoia per app o una notifica.
Evita di creare troppi riquadri. Consigliamo un massimo di due app per app. Utilizza un scorciatoia dell'app.
Evita di utilizzare riquadri che mostrano informazioni, ma non sono interattivi per utenti. Utilizza una notifica o un widget.

Creare il riquadro

Per creare un riquadro, devi prima creare un'icona del riquadro appropriata, quindi creare e dichiarare TileService nel file manifest dell'app.

L'esempio di Impostazioni rapide fornisce un esempio di come creare e gestire un riquadro.

Crea la tua icona personalizzata

Occorre fornire un'icona personalizzata, che verrà visualizzata nel riquadro della scheda Impostazioni. Aggiungerai questa icona quando dichiari TileService, descritto nella sezione successiva. L'icona deve essere bianca in tinta unita con una sfondo trasparente, misure 24 x 24 dp e sotto forma di VectorDrawable

**Figura 3.** Esempio di drawable vettoriale.

Crea un'icona che suggerisca visivamente lo scopo del riquadro. Questo aiuta gli utenti identificare facilmente se il tuo riquadro soddisfa le loro esigenze. Ad esempio, potresti creare un'etichetta icona di un cronometro per un riquadro di un'app per l'attività fisica che consente agli utenti di avviare sessione di allenamento.

Crea e dichiara il tuo TileService

Crea un servizio per il riquadro che estenda 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();
  }
}

Dichiara TileService nel file manifest dell'app. Aggiungi il nome e l'etichetta di TileService, l'icona personalizzata che hai creato nella sezione precedente, e dell'autorizzazione appropriata.

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

Gestire TileService

Dopo aver creato e dichiarato TileService nel file manifest dell'app, non deve gestire il proprio stato.

TileService è un servizio associato. TileService viene associato quando richiesto dalla tua app o se il sistema deve comunicare con esso. Un tipico ciclo di vita del servizio associato contiene i seguenti quattro metodi di callback: onCreate(), onBind(), onUnbind() e onDestroy(). Questi metodi vengono invocati dal sistema ogni volta che il servizio entra in una nuova fase del ciclo di vita.

Panoramica del ciclo di vita di TileService

Oltre ai callback che controllano il ciclo di vita dei servizi associati, devi implementare altri metodi specifici per il ciclo di vita di TileService. Questi metodi possono essere chiamati al di fuori di onCreate() e onDestroy() perché i metodi di ciclo di vita Service e TileService vengono chiamati in due thread asincroni distinti.

Il ciclo di vita di TileService contiene i seguenti metodi, che vengono richiamati dal sistema ogni volta che il tuo TileService entra in una nuova fase del ciclo di vita:

onTileAdded(): questo metodo viene chiamato solo quando l'utente aggiunge il riquadro per la prima volta e se lo rimuove e lo aggiunge di nuovo. Questo è il momento migliore per eseguire qualsiasi inizializzazione una tantum. Tuttavia, non soddisfano tutte le inizializzazioni necessarie.

Nota: onTileAdded() non viene chiamato ogni volta che viene creato il riquadro. Ad esempio, onTileAdded() non viene chiamato quando il dispositivo viene riavviato o acceso se il riquadro è stato aggiunto e non rimosso prima che il dispositivo venisse spento.
onStartListening() e onStopListening(): questi metodi vengono chiamati ogni volta che l'app aggiorna il riquadro e vengono chiamati di frequente. La TileService rimane vincolata tra onStartListening() e onStopListening(), consentendo alla tua app di modificare il riquadro ed eseguire il push degli aggiornamenti.
onTileRemoved(): questo metodo viene chiamato solo se l'utente rimuove la scheda.

Seleziona una modalità di ascolto

TileService ascolta in modalità attiva o non attiva. I nostri suggerimenti e la modalità attiva, che dovrai dichiarare nel file manifest dell'app. Altrimenti, TileService è la modalità standard e non deve essere dichiarata.

Non dare per scontato che il tuo TileService vivrà al di fuori di onStartListening() e onStopListening() coppia di metodi.

Modalità attiva (consigliata)

Utilizza la modalità attiva per un TileService che ascolta e monitora il proprio stato nel proprio processo. Un TileService in modalità attiva è associato a onTileAdded(), onTileRemoved(), agli eventi di tocco e quando richiesto dal processo dell'app.

Ti consigliamo la modalità attiva se il tuo TileService riceve una notifica quando il tuo riquadro dovrebbe essere aggiornato con la propria procedura. I riquadri attivi limitano la pressione sulla perché non devono essere vincolati ogni volta che il riquadro Impostazioni rapide diventa visibile all'utente.

Il metodo TileService.requestListeningState() statico può essere chiamato richiedere l'avvio dello stato di ascolto e ricevere un callback a onStartListening().

Puoi dichiarare la modalità attiva aggiungendo META_DATA_ACTIVE_TILE al file manifest dell'app.

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

Modalità non attiva

La modalità non attiva è la modalità standard. Un TileService è in modalità non attiva se è vincolato ogni volta che il riquadro è visibile all'utente. Ciò significa che il tuo TileService potrebbe essere creato e associato di nuovo in momenti al di fuori del suo controllo. Inoltre, può essere sganciato e distrutto quando l'utente non visualizza il riquadro.

La tua app riceve un callback a onStartListening() dopo che l'utente ha aperto il suo Riquadro Impostazioni rapide. Puoi aggiornare l'oggetto Tile tutte le volte che vuoi vuoi tra onStartListening() e onStopListening().

Non è necessario dichiarare la modalità non attiva, basta non aggiungere il META_DATA_ACTIVE_TILE al file manifest dell'app.

Panoramica degli stati dei riquadri

Dopo che un utente ha aggiunto il tuo riquadro, questo esiste sempre in uno dei seguenti stati.

STATE_ACTIVE: indica se lo stato è attivo o attivato. L'utente può interagire con il riquadro mentre si trova in questo stato.

Ad esempio, per un riquadro di un'app per il fitness che consente agli utenti di avviare una sessione di allenamento con timer, STATE_ACTIVE indica che l'utente ha avviato una sessione di allenamento e il timer è in esecuzione.
STATE_INACTIVE: indica uno stato di disattivazione o messa in pausa. L'utente può interagire con il riquadro mentre si trova in questo stato.

Per utilizzare di nuovo l'esempio del riquadro dell'app per il fitness, un riquadro in STATE_INACTIVE significa che l'utente non ha avviato una sessione di allenamento, ma potrebbe farlo se lo volesse.
STATE_UNAVAILABLE: indica uno stato temporaneamente non disponibile. L'utente non può interagire con il riquadro in questo stato.

Ad esempio, un riquadro in STATE_UNAVAILABLE indica che il riquadro non è attualmente disponibili per l'utente per qualche motivo.

Attenzione: utilizza STATE_UNAVAILABLE per i riquadri attualmente non disponibili ma potrebbe essere reso disponibile in un secondo momento. Se il componente non esegue mai essere di nuovo disponibile per l'utente, supera COMPONENT_ENABLED_STATE_DISABLED in setComponentEnabledSetting().

Il sistema imposta solo lo stato iniziale dell'oggetto Tile. Hai impostato Tile durante il resto del ciclo di vita.

Il sistema potrebbe colorare l'icona e lo sfondo del riquadro in base allo stato dell'oggetto Tile. Gli oggetti Tile impostati su STATE_ACTIVE sono i più scuri, mentre STATE_INACTIVE e STATE_UNAVAILABLE sono sempre più chiari. La tonalità esatta è specifica per il produttore e la versione.

Riquadro VPN colorato in base agli stati degli oggetti — **Figura 4.** Esempi di riquadri colorati in base allo stato (rispettivamente attivo, non attivo e non disponibile).

Aggiorna il tuo riquadro

Puoi aggiornare il riquadro quando ricevi una chiamata al numero onStartListening(). A seconda della modalità, il riquadro può essere aggiornato almeno una volta fino a quando non riceve un callback a onStopListening().

In modalità attiva, puoi aggiornare il riquadro esattamente una volta prima di ricevere un callback a onStopListening(). In modalità non attiva, puoi aggiornare il riquadro tutte le volte che vuoi tra onStartListening() e onStopListening().

Puoi recuperare l'oggetto Tile chiamando getQsTile(). Per aggiornare campi specifici dell'oggetto Tile, richiama i seguenti metodi:

Devi chiamare updateTile() per aggiornare il tuo riquadro una volta completata l'impostazione dell'oggetto Tile in base ai valori corretti. In questo modo, il sistema analizzerà i dati dei riquadri aggiornati e aggiornerà l'interfaccia utente.

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

Gestire i tocchi

Gli utenti possono toccare il tuo riquadro per attivare un'azione se si trova in STATE_ACTIVE o STATE_INACTIVE. Il sistema richiama quindi il callback onClick() della tua app.

Una volta che l'app riceve un callback a onClick(), può avviare una finestra di dialogo o un'attività, attivare un'operazione in background o modificare lo stato del riquadro.

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

Apri una finestra di dialogo

showDialog() comprime il riquadro Impostazioni rapide e mostra una finestra di dialogo. Utilizza una finestra di dialogo per aggiungere contesto all'azione se richiede un input aggiuntivo o consenso dell'utente.

Lanciare un'attività

startActivityAndCollapse() avvia un'attività mentre comprimi il dal riquadro. Le attività sono utili se ci sono informazioni più dettagliate da visualizzare rispetto a una finestra di dialogo o se l'azione è altamente interattiva.

Se la tua app richiede un'interazione significativa con l'utente, deve avviare un'attività solo come ultima risorsa. In alternativa, valuta la possibilità di utilizzare una finestra di dialogo o un pulsante di attivazione/disattivazione.

Se si tocca a lungo un riquadro, viene visualizzata la schermata Info app per l'utente. Per eseguire l'override di questo comportamento e avviare un'attività per l'impostazione delle preferenze, aggiungi un <intent-filter> a una delle tue attività con ACTION_QS_TILE_PREFERENCES.

A partire dall'API Android 28, il PendingIntent deve avere il Intent.FLAG_ACTIVITY_NEW_TASK:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}

In alternativa, puoi aggiungere il flag in AndroidManifest.xml nella sezione specificaActivity.

Contrassegnare il riquadro come attivabile

Ti consigliamo di contrassegnare il riquadro come attivabile/disattivabile se funziona principalmente come pulsante a due stati (che è il comportamento più comune dei riquadri). Ciò consente di fornire informazioni sul comportamento del riquadro al sistema operativo e migliorare l'accessibilità generale.

Imposta i metadati TOGGLEABLE_TILE su true per contrassegnare il riquadro come attivabile/disattivabile.

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

Esegui solo azioni sicure su dispositivi bloccati in modo sicuro

Il riquadro potrebbe essere visualizzato sopra la schermata di blocco sui dispositivi bloccati. Se il riquadro contiene informazioni sensibili, controlla il valore di isSecure() per determinare se il dispositivo è in uno stato sicuro e TileService dovrebbe cambiare il proprio comportamento di conseguenza.

Se l'azione del riquadro può essere eseguita in sicurezza mentre il dispositivo è bloccato, usa startActivity() per avviare un'attività nella parte superiore della schermata di blocco.

Se l'azione del riquadro non è sicura, utilizza unlockAndRun() per chiedere all'utente di sbloccare il suo dispositivo. Se l'operazione ha esito positivo, il sistema esegue Runnable che passi in questo .

Chiedi all'utente di aggiungere il tuo riquadro

Per aggiungere manualmente il riquadro, gli utenti devono seguire diversi passaggi:

Scorri verso il basso per aprire il riquadro Impostazioni rapide.
Tocca il pulsante Modifica.
Scorri tutti i riquadri sul dispositivo finché non trova il tuo.
Tieni premuto il riquadro e trascinalo nell'elenco dei riquadri attivi.

L'utente può anche spostare o rimuovere il riquadro in qualsiasi momento.

A partire da Android 13, puoi utilizzare il metodo requestAddTileService() per semplificare notevolmente l'aggiunta del riquadro a un dispositivo da parte degli utenti. Questo metodo richiede agli utenti di aggiungere rapidamente il riquadro direttamente al riquadro Impostazioni rapide. La richiesta include il nome dell'applicazione, l'etichetta e l'icona forniti.

Prompt dell'API Quick Settings Placement — **Figura 5.** Prompt dell'API Placement Impostazioni rapide.

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

Il callback contiene informazioni se il riquadro è stato aggiunto o meno, non aggiunto, se era già presente o se si è verificato un errore.

Usa la tua discrezione per decidere quando e con quale frequenza chiedere agli utenti di rispondere. Me consiglia di chiamare requestAddTileService() solo nel contesto, ad esempio quando l'utente interagisce per la prima volta con una funzionalità agevolata dal riquadro.

Il sistema può scegliere di interrompere l'elaborazione delle richieste per un determinato ComponentName se è stata rifiutata dall'utente un numero sufficiente di volte in precedenza. L'utente viene determinato dal valore Context utilizzato per recuperare questo servizio e deve corrispondere all'utente corrente.