Le Impostazioni rapide sono riquadri visualizzati nel riquadro Impostazioni rapide che rappresentano le azioni che gli utenti possono toccare per completare rapidamente le attività ricorrenti.
La tua app può fornire un riquadro personalizzato agli utenti tramite la classe TileService
e utilizzare un oggetto Tile
per monitorare lo stato del riquadro. Ad esempio,
puoi creare un riquadro che consenta agli utenti di attivare o
disattivare una VPN fornita dalla tua app.
![Riquadro Impostazioni rapide con il riquadro VPN attivato e disattivato](https://developer.android.google.cn/static/develop/ui/views/images/quick-settings-vpn-on-off.png?authuser=6&hl=it)
Decidere quando creare un riquadro
Consigliamo di creare riquadri per funzionalità specifiche a cui vuoi che gli utenti accedano spesso o a cui devono accedere rapidamente (o entrambe). I riquadri più efficaci sono quelli che corrispondono a entrambe le qualità, fornendo accesso rapido alle azioni eseguite di frequente.
Ad esempio, puoi creare un riquadro per un'app di 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 rivedere l'intera cronologia di allenamento.
![Casi d'uso dei riquadri dell'app Fitness](https://developer.android.google.cn/static/develop/ui/views/images/use-cases-fitness-tiles.png?authuser=6&hl=it)
Per migliorare la rilevabilità e la facilità d'uso del riquadro, consigliamo di evitare alcune pratiche:
Evita di utilizzare i riquadri per avviare un'app. Utilizza invece una scorciatoia app o un'Avvio app standard.
Evita di utilizzare riquadri per azioni utente singole. Utilizza invece una scorciatoia dell'app o una notifica.
Evita di creare troppi riquadri. Consigliamo di usare al massimo due scorciatoie per app. Utilizza invece una scorciatoia app.
Evita di utilizzare riquadri che mostrano informazioni, ma non sono interattivi per gli utenti. Utilizza invece una notifica o un widget.
Crea il tuo riquadro
Per creare un riquadro, devi prima creare un'icona per il 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
Dovrai fornire un'icona personalizzata, che verrà visualizzata nel riquadro nel riquadro Impostazioni rapide. Dovrai aggiungere questa icona durante la dichiarazione di TileService
,
come descritto nella sezione successiva. L'icona deve essere bianca in tinta unita con uno sfondo trasparente, avere dimensioni di 24 x 24 dp e avere la forma di un VectorDrawable
.
![Esempio di drawable vettoriale](https://developer.android.google.cn/static/develop/ui/views/images/vector-drawable.png?authuser=6&hl=it)
Crea un'icona che indichi visivamente lo scopo del tuo riquadro. In questo modo gli utenti possono identificare facilmente se il tuo riquadro soddisfa le loro esigenze. Ad esempio, potresti creare l'icona di un cronometro per un riquadro di un'app di fitness che consenta agli utenti di avviare una sessione di allenamento.
Crea e dichiara il tuo TileService
Crea un servizio per il tuo riquadro che espanda 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 creata nella sezione precedente e l'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, devi gestirne lo stato.
TileService
è un servizio associato. TileService
è vincolato quando
richiesto dalla tua app o se il sistema deve comunicare con l'app. Un tipico ciclo di vita di un servizio associato contiene i seguenti quattro metodi di callback: onCreate()
, onBind()
, onUnbind()
e onDestroy()
. Questi metodi vengono richiamati 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 del ciclo di vita Service
e quelli del ciclo di vita TileService
vengono chiamati in due
thread asincroni separati.
Il ciclo di vita di TileService
contiene i seguenti metodi, richiamati
dal sistema ogni volta che TileService
entra in una nuova fase del ciclo di vita:
onTileAdded()
: questo metodo viene chiamato solo quando l'utente aggiunge il tuo riquadro per la prima volta e se l'utente lo rimuove e lo aggiunge di nuovo. Questo è il momento migliore per eseguire qualsiasi inizializzazione una tantum. Tuttavia, questo potrebbe non soddisfare tutte le inizializzazioni necessarie.onStartListening()
eonStopListening()
: questi metodi vengono richiamati ogni volta che l'app aggiorna il riquadro e vengono richiamati spesso. L'elementoTileService
rimane associato tra il giornoonStartListening()
e il giornoonStopListening()
, consentendo all'app di modificare il riquadro ed eseguire il push degli aggiornamenti.onTileRemoved()
: questo metodo viene chiamato solo se l'utente rimuove il riquadro.
Seleziona una modalità di ascolto
Il tuo TileService
ascolta in modalità attiva o non attiva. Ti consigliamo
di utilizzare la modalità attiva, che dovrai dichiarare nel file manifest dell'app. In caso contrario,
TileService
è la modalità standard e non deve essere dichiarata.
Non dare per scontato che il tuo TileService
vivrà al di fuori della coppia di metodi onStartListening()
e
onStopListening()
.
Modalità attiva (consigliata)
Utilizza la modalità attiva per un TileService
che ascolta e monitora il proprio stato durante il proprio processo. Un TileService
in modalità attiva è associato per onTileAdded()
,
onTileRemoved()
, eventi di tocco e quando richiesto dal processo dell'app.
Ti consigliamo la modalità attiva se TileService
riceve una notifica quando lo stato del riquadro deve essere aggiornato tramite la propria procedura. I riquadri attivi limitano il carico sul sistema perché non devono essere vincolati ogni volta che il riquadro Impostazioni rapide diventa visibile all'utente.
È possibile chiamare il metodo TileService.requestListeningState()
statico per 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 è quella standard. Un TileService
è in modalità non attiva se è associato ogni volta che il tuo riquadro è visibile all'utente. Ciò significa che TileService
potrebbe essere creato e vincolato di nuovo a volte al di fuori del suo controllo. Inoltre, potrebbe essere slegato ed eliminato quando l'utente non sta visualizzando il riquadro.
La tua app viene richiamata a onStartListening()
dopo che l'utente ha aperto il riquadro Impostazioni rapide. Puoi aggiornare l'oggetto Tile
tutte le volte che vuoi tra onStartListening()
e onStopListening()
.
Non è necessario dichiarare la modalità non attiva: è sufficiente non aggiungere META_DATA_ACTIVE_TILE
al file manifest dell'app.
Panoramica degli stati dei riquadri
Dopo che un utente ha aggiunto un riquadro, questo esiste sempre in uno dei seguenti stati.
STATE_ACTIVE
: indica se lo stato è attivo o attivato. L'utente può interagire con il tuo riquadro mentre si trova in questo stato.Ad esempio, per il riquadro di un'app per l'attività fisica che consente agli utenti di avviare una sessione di allenamento a tempo,
STATE_ACTIVE
significa che l'utente ha avviato una sessione di allenamento e il timer è in esecuzione.STATE_INACTIVE
: indica lo stato disattivato o in pausa. L'utente può interagire con il tuo riquadro mentre si trova in questo stato.Per utilizzare di nuovo l'esempio di riquadro dell'app per l'attività fisica, un riquadro in
STATE_INACTIVE
significa che l'utente non ha avviato una sessione di allenamento, ma può farlo se lo desidera.STATE_UNAVAILABLE
: indica uno stato temporaneamente non disponibile. L'utente non può interagire con il tuo riquadro in questo stato.Ad esempio, un riquadro in
STATE_UNAVAILABLE
indica che il riquadro non è attualmente disponibile per l'utente per qualche motivo.
Il sistema imposta solo lo stato iniziale dell'oggetto Tile
. Devi impostare lo stato dell'oggetto Tile
per tutto il resto del suo ciclo di vita.
Il sistema potrebbe applicare una tinta all'icona e allo sfondo del riquadro per riflettere lo stato dell'oggetto Tile
. Gli oggetti Tile
impostati su STATE_ACTIVE
sono i più scuri, con STATE_INACTIVE
e STATE_UNAVAILABLE
sempre più chiari. La tonalità esatta è specifica
per il produttore e la versione.
![Riquadro VPN colorato per riflettere gli stati dell'oggetto](https://developer.android.google.cn/static/develop/ui/views/images/state-hues.png?authuser=6&hl=it)
Aggiorna il tuo riquadro
Puoi aggiornare il tuo riquadro quando ricevi una richiamata al numero onStartListening()
.
A seconda della modalità, il riquadro può essere aggiornato almeno una volta fino a quando non ricevi un callback a onStopListening()
.
In modalità attiva, puoi aggiornare il tuo riquadro esattamente una volta prima di ricevere una
chiamata al onStopListening()
. Nella modalità non attiva, puoi aggiornare il tuo riquadro
tutte le volte che vuoi tra le ore onStartListening()
e le ore onStopListening()
.
Puoi recuperare l'oggetto Tile
chiamando getQsTile()
. Per aggiornare
campi specifici dell'oggetto Tile
, chiama i seguenti metodi:
Devi chiamare updateTile()
per aggiornare il tuo riquadro una volta che hai finito di impostare
i campi dell'oggetto Tile
sui valori corretti. In questo modo, il sistema analizzerà i dati dei riquadri aggiornati e aggiornerà la 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(); }
Gestire i tocchi
Gli utenti possono toccare il tuo riquadro per attivare un'azione se il riquadro è in STATE_ACTIVE
o STATE_INACTIVE
. Il sistema richiama quindi il callback onClick()
dell'app.
Quando l'app riceve un callback a onClick()
, può aprire una finestra di dialogo o
un'attività, attivare il lavoro 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 il consenso dell'utente.
Lanciare un'attività
startActivityAndCollapse()
avvia un'attività mentre comprimi il riquadro. Le attività sono utili se ci sono informazioni più dettagliate
da visualizzare in una finestra di dialogo o se l'azione è altamente interattiva.
Se la tua app richiede un'interazione utente significativa, l'app dovrebbe 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 ignorare
questo comportamento e avviare invece un'attività per l'impostazione delle preferenze, aggiungi
<intent-filter>
a una delle tue attività con
ACTION_QS_TILE_PREFERENCES
.
A partire dall'API Android 28, 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 nella sezione AndroidManifest.xml
della sezione Activity
specifica.
Contrassegnare il riquadro come attivabile
Ti consigliamo di contrassegnare il riquadro come attivabile se funziona principalmente come interruttore a due stati (che è il comportamento più comune dei riquadri). Ciò consente di fornire informazioni sul comportamento del riquadro al sistema operativo e di migliorare l'accessibilità generale.
Imposta i metadati TOGGLEABLE_TILE
su true
per contrassegnare il tuo riquadro come attivabile.
<service ...>
<meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
android:value="true" />
</service>
Esegui solo azioni sicure su dispositivi bloccati in modo sicuro
Sui dispositivi bloccati, il riquadro potrebbe essere visualizzato nella parte superiore della schermata di blocco. Se il riquadro
contiene informazioni sensibili, controlla il valore di isSecure()
per
determinare se il dispositivo è in stato sicuro e TileService
dovrebbe
modificare 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 proprio dispositivo. In caso di esito positivo, il sistema esegue l'oggetto Runnable
che trasmetti in questo metodo.
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 suo dispositivo fino a quando non trova il tuo riquadro.
- 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 l'aggiunta del tuo riquadro a un dispositivo da parte degli utenti. Questo metodo
consente agli utenti di richiedere l'aggiunta rapida del tuo riquadro direttamente al riquadro
Impostazioni rapide. Il prompt include il nome dell'applicazione,
l'etichetta fornita e l'icona.
![Richiesta dell'API posizionamento delle impostazioni rapide](https://developer.android.google.cn/static/develop/ui/views/images/placement-api-user-prompt.png?authuser=6&hl=it)
public void requestAddTileService (
ComponentName tileServiceComponentName,
CharSequence tileLabel,
Icon icon,
Executor resultExecutor,
Consumer<Integer> resultCallback
)
Il callback contiene informazioni se il riquadro è stato aggiunto, non aggiunto, se era già presente o se si è verificato un errore.
Valuta a tua discrezione quando e con quale frequenza inviare una richiesta agli utenti. Ti
consigliamo di chiamare requestAddTileService()
solo nel contesto, ad esempio
quando l'utente interagisce per la prima volta con una funzionalità agevolata dal tuo riquadro.
Il sistema può scegliere di interrompere l'elaborazione delle richieste per una determinata
ComponentName
se è stata rifiutata dall'utente un determinato numero di volte in precedenza. L'utente
viene determinato in base alla Context
utilizzata per recuperare questo
servizio e deve corrispondere all'utente corrente.