Schnelleinstellungen sind Kacheln, die im Bereich für Schnelleinstellungen angezeigt werden und Aktionen darstellen, auf die Nutzer tippen können, um wiederkehrende Aufgaben schnell auszuführen.
Deine App kann Nutzern über die Klasse TileService
eine benutzerdefinierte Kachel zur Verfügung stellen und ein Tile
-Objekt verwenden, um den Status der Kachel zu verfolgen. Sie können beispielsweise eine Kachel erstellen, über die Nutzer ein von Ihrer App bereitgestelltes VPN aktivieren oder deaktivieren können.
![Bereich „Schnelleinstellungen“ mit aktivierter und deaktivierter Kachel „VPN“](https://developer.android.com/static/develop/ui/views/images/quick-settings-vpn-on-off.png?authuser=6&hl=de)
Entscheiden, wann eine Kachel erstellt werden soll
Wir empfehlen, Kacheln für bestimmte Funktionen zu erstellen, auf die Nutzer häufig oder schnell zugreifen müssen (oder beides). Die effektivsten Kacheln sind die Kacheln, die beiden Eigenschaften entsprechen und einen schnellen Zugriff auf häufig ausgeführte Aktionen ermöglichen.
Sie könnten beispielsweise eine Kachel für eine Fitness-App erstellen, mit der Nutzende schnell eine Trainingseinheit starten können. Wir raten jedoch davon ab, eine Kachel für dieselbe App zu erstellen, mit der Nutzer ihren gesamten Trainingsverlauf ansehen können.
![Anwendungsfälle für Kacheln in der Fitness-App](https://developer.android.com/static/develop/ui/views/images/use-cases-fitness-tiles.png?authuser=6&hl=de)
Um die Sichtbarkeit und Nutzerfreundlichkeit Ihrer Kachel zu verbessern, empfehlen wir, bestimmte Vorgehensweisen zu vermeiden:
Verwende keine Kacheln, um eine App zu starten. Verwende stattdessen eine App-Verknüpfung oder einen Standard-Launcher.
Verwenden Sie Kacheln nicht für einmalige Nutzeraktionen. Verwenden Sie stattdessen eine App-Verknüpfung oder eine Benachrichtigung.
Erstellen Sie nicht zu viele Kacheln. Wir empfehlen maximal zwei pro App. Verwenden Sie stattdessen eine App-Verknüpfung.
Verwenden Sie keine Kacheln, die Informationen anzeigen, aber für Nutzer nicht interaktiv sind. Verwenden Sie stattdessen eine Benachrichtigung oder ein Widget.
Kachel erstellen
Um eine Kachel zu erstellen, musst du zuerst ein entsprechendes Kachelsymbol erstellen und dann dein TileService
in der Manifestdatei deiner App erstellen und deklarieren.
Das Beispiel für die Schnelleinstellungen enthält ein Beispiel für das Erstellen und Verwalten einer Kachel.
Benutzerdefiniertes Symbol erstellen
Sie müssen ein benutzerdefiniertes Symbol angeben, das auf der Kachel im Bereich „Schnelleinstellungen“ angezeigt wird. Dieses Symbol wird bei der Deklaration des TileService
hinzugefügt, wie im nächsten Abschnitt beschrieben. Das Symbol muss durchgehend weiß mit transparentem Hintergrund und 24 x 24 dp groß sein und in Form eines VectorDrawable
-Elements vorliegen.
![Beispiel für ein Vektor-Drawable](https://developer.android.com/static/develop/ui/views/images/vector-drawable.png?authuser=6&hl=de)
Erstellen Sie ein Symbol, das optisch auf den Zweck Ihrer Kachel verweist. So können Nutzende auf einfache Weise feststellen, ob Ihre Kachel ihren Anforderungen entspricht. Sie können beispielsweise das Symbol einer Stoppuhr für eine Kachel für eine Fitness-App erstellen, mit der Nutzer eine Trainingseinheit starten können.
TileService erstellen und deklarieren
Erstellen Sie für Ihre Kachel einen Dienst, der die TileService
-Klasse erweitert.
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(); } }
Deklariere TileService
in der Manifestdatei deiner App. Fügen Sie den Namen und das Label Ihres TileService
, das benutzerdefinierte Symbol, das Sie im vorherigen Abschnitt erstellt haben, und die entsprechende Berechtigung hinzu.
<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>
TileService verwalten
Nachdem du dein TileService
in deinem App-Manifest erstellt und deklariert hast, musst du dessen Status verwalten.
TileService
ist ein gebundener Dienst. Die TileService
wird gebunden, wenn sie von der Anwendung angefordert wird oder wenn das System mit ihr kommunizieren muss. Ein typischer Lebenszyklus eines gebundenen Dienstes umfasst die folgenden vier Callback-Methoden: onCreate()
, onBind()
, onUnbind()
und onDestroy()
. Diese Methoden werden vom System jedes Mal aufgerufen, wenn der Dienst eine neue Lebenszyklusphase erreicht.
TileService-Lebenszyklus – Übersicht
Zusätzlich zu den Callbacks, die den Lebenszyklus eines gebundenen Dienstes steuern, müssen Sie andere Methoden implementieren, die für den Lebenszyklus TileService
spezifisch sind. Diese Methoden können außerhalb von onCreate()
und onDestroy()
aufgerufen werden, da die Lebenszyklusmethoden Service
und TileService
in zwei separaten asynchronen Threads aufgerufen werden.
Der Lebenszyklus TileService
enthält die folgenden Methoden, die jedes Mal vom System aufgerufen werden, wenn TileService
in eine neue Lebenszyklusphase wechselt:
onTileAdded()
: Diese Methode wird nur aufgerufen, wenn der Nutzer deine Kachel zum ersten Mal hinzufügt oder wenn er sie entfernt und noch einmal hinzufügt. Dies ist der beste Zeitpunkt für eine einmalige Initialisierung. Dies erfüllt jedoch möglicherweise nicht alle erforderlichen Initialisierungen.onStartListening()
undonStopListening()
: Diese Methoden werden oft aufgerufen, wenn deine App die Kachel aktualisiert. DieTileService
bleibt zwischenonStartListening()
undonStopListening()
gebunden, sodass deine App die Kachel ändern und Updates senden kann.onTileRemoved()
: Diese Methode wird nur aufgerufen, wenn der Nutzer die Kachel entfernt.
Zuhörmodus auswählen
TileService
hört im Aktivmodus oder im Nicht-Aktiv-Modus zu. Wir empfehlen, den Aktivmodus zu verwenden. Diesen musst du im App-Manifest deklarieren. Andernfalls ist TileService
der Standardmodus und muss nicht deklariert werden.
Gehen Sie nicht davon aus, dass sich Ihr TileService
außerhalb der Methodenpaare onStartListening()
und onStopListening()
befindet.
Aktivmodus (empfohlen)
Verwenden Sie den Aktivmodus für eine TileService
, die ihren Status in einem eigenen Prozess überwacht und überwacht. Eine TileService
im Aktivmodus wird an onTileAdded()
, onTileRemoved()
, Tippereignisse und auf Anforderung durch den App-Prozess gebunden.
Wir empfehlen den Aktivmodus, wenn TileService
benachrichtigt wird, wenn der Kachelstatus von einem eigenen Prozess aktualisiert werden sollte. Aktive Kacheln begrenzen die Belastung des Systems, da sie nicht jedes Mal gebunden werden müssen, wenn der Bereich „Schnelleinstellungen“ für den Nutzer sichtbar wird.
Die statische Methode TileService.requestListeningState()
kann aufgerufen werden, um den Start des Überwachungsstatus anzufordern und einen Callback von onStartListening()
zu erhalten.
Wenn du den Aktivmodus deklarieren möchtest, füge der Manifestdatei deiner App META_DATA_ACTIVE_TILE
hinzu.
<service ...>
<meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
android:value="true" />
...
</service>
Nicht-Aktiv-Modus
Der nicht aktive Modus ist der Standardmodus. Eine TileService
befindet sich im inaktiven Modus, wenn sie immer gebunden ist, wenn deine Kachel für den Nutzer sichtbar ist. Dies bedeutet, dass Ihre TileService
zu Zeiten außerhalb ihrer Kontrolle erstellt und neu gebunden werden kann. Sie kann auch aufgelöst und gelöscht werden, wenn der Nutzer die Kachel nicht ansieht.
Deine App erhält einen Callback an onStartListening()
, nachdem der Nutzer die Schnelleinstellungen geöffnet hat. Sie können Ihr Tile
-Objekt zwischen onStartListening()
und onStopListening()
beliebig oft aktualisieren.
Der inaktive Modus muss nicht deklariert werden. Füge der Manifestdatei deiner App nur META_DATA_ACTIVE_TILE
nicht hinzu.
Übersicht über Kachelzustände
Nachdem ein Nutzer Ihre Kachel hinzugefügt hat, befindet sie sich immer in einem der folgenden Status.
STATE_ACTIVE
: Gibt an, dass es sich um einen An- oder Aktivierungsstatus handelt. Der Nutzer kann in diesem Zustand mit Ihrer Kachel interagieren.Bei einer Fitness-App-Kachel, mit der Nutzer eine zeitgebundene Trainingseinheit starten können, bedeutet
STATE_ACTIVE
, dass der Nutzer eine Trainingseinheit gestartet hat und der Timer läuft.STATE_INACTIVE
: steht für „Aus“ oder „Pausiert“. Der Nutzer kann in diesem Zustand mit Ihrer Kachel interagieren.Wenn du das Beispiel für die Kachel der Fitness-App noch einmal verwenden möchtest, würde eine Kachel in
STATE_INACTIVE
bedeuten, dass der Nutzer keine Trainingseinheit gestartet hat, dies aber bei Bedarf tun könnte.STATE_UNAVAILABLE
: zeigt an, dass der Status vorübergehend nicht verfügbar ist. Der Nutzer kann in diesem Zustand nicht mit Ihrer Kachel interagieren.Beispielsweise bedeutet eine Kachel in
STATE_UNAVAILABLE
, dass sie dem Nutzer derzeit aus irgendeinem Grund nicht zur Verfügung steht.
Das System legt nur den Anfangszustand des Tile
-Objekts fest. Den Status des Tile
-Objekts legen Sie für den Rest des Lebenszyklus fest.
Das Kachelsymbol und der Hintergrund werden möglicherweise vom System färben, damit sie den Status des Tile
-Objekts widerspiegeln. Tile
-Objekte, die auf STATE_ACTIVE
gesetzt sind, sind am dunkelsten, wobei STATE_INACTIVE
und STATE_UNAVAILABLE
zunehmend heller sind. Der genaue Farbton richtet sich nach dem Hersteller und der Version.
![VPN-Kachel, die zur Anzeige des Objektstatus gefärbt ist](https://developer.android.com/static/develop/ui/views/images/state-hues.png?authuser=6&hl=de)
Kachel aktualisieren
Du kannst deine Kachel aktualisieren, sobald du einen Rückruf von onStartListening()
erhältst.
Je nach Kachelmodus kann die Kachel mindestens einmal aktualisiert werden, bis ein Callback von onStopListening()
eingeht.
Im Aktivmodus kannst du deine Kachel genau einmal aktualisieren, bevor du einen Rückruf an onStopListening()
erhältst. Im inaktiven Modus können Sie Ihre Kachel zwischen onStartListening()
und onStopListening()
beliebig oft aktualisieren.
Sie können das Tile
-Objekt durch Aufrufen von getQsTile()
abrufen. Mit den folgenden Methoden können Sie bestimmte Felder des Tile
-Objekts aktualisieren:
Sie müssen updateTile()
aufrufen, um Ihre Kachel zu aktualisieren, sobald Sie die Felder des Tile
-Objekts auf die richtigen Werte festgelegt haben. Dadurch parst das System die aktualisierten Kacheldaten und aktualisiert die Benutzeroberfläche.
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(); }
Fingertipps
Nutzer können auf deine Kachel tippen, um eine Aktion auszulösen, wenn sie sich in STATE_ACTIVE
oder STATE_INACTIVE
befindet. Das System ruft dann den onClick()
-Callback der Anwendung auf.
Sobald deine App einen Callback von onClick()
empfängt, kann sie ein Dialogfeld oder eine Aktivität starten, Hintergrundarbeiten auslösen oder den Status der Kachel ändern.
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(); }
Dialogfeld öffnen
showDialog()
minimiert den Bereich mit den Schnelleinstellungen und zeigt ein Dialogfeld an.
Fügen Sie Ihrer Aktion über ein Dialogfeld Kontext hinzu, wenn eine zusätzliche Eingabe oder die Einwilligung des Nutzers erforderlich ist.
Aktivität starten
startActivityAndCollapse()
startet beim Minimieren des Bereichs eine Aktivität. Aktivitäten sind nützlich, wenn Sie detailliertere Informationen als in einem Dialogfeld anzeigen möchten oder wenn Ihre Aktion sehr interaktiv ist.
Wenn Ihre Anwendung eine erhebliche Nutzerinteraktion erfordert, sollte sie nur als letzte Option eine Aktivität starten. Verwenden Sie stattdessen ein Dialogfeld oder eine Ein/Aus-Schaltfläche.
Durch langes Tippen auf eine Kachel wird der Bildschirm App-Info angezeigt. Wenn Sie dieses Verhalten überschreiben und stattdessen eine Aktivität zum Festlegen von Einstellungen starten möchten, fügen Sie einer Ihrer Aktivitäten mit ACTION_QS_TILE_PREFERENCES
eine <intent-filter>
hinzu.
Ab Android API 28 muss PendingIntent
die Intent.FLAG_ACTIVITY_NEW_TASK
haben:
if (Build.VERSION.SDK_INT >= 28) {
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}
Alternativ können Sie das Flag im AndroidManifest.xml
im jeweiligen Activity
-Abschnitt hinzufügen.
Kachel als ein-/ausschaltbar markieren
Wir empfehlen, Ihre Kachel als ein-/ausschaltbar zu kennzeichnen, wenn sie primär als Zwei-Status-Schalter dient (dies ist das gängigste Verhalten von Kacheln). Dadurch erhält das Betriebssystem Informationen zum Verhalten der Kachel und verbessert die allgemeine Zugänglichkeit.
Setze die TOGGLEABLE_TILE
-Metadaten auf true
, um deine Kachel als ein-/ausschaltbar zu kennzeichnen.
<service ...>
<meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
android:value="true" />
</service>
Nur sichere Aktionen auf sicher gesperrten Geräten ausführen
Ihre Kachel wird auf gesperrten Geräten möglicherweise oben auf dem Sperrbildschirm angezeigt. Wenn die Kachel vertrauliche Informationen enthält, prüfe den Wert von isSecure()
, um festzustellen, ob sich das Gerät in einem sicheren Zustand befindet. TileService
sollte dann ihr Verhalten entsprechend ändern.
Wenn die Kachelaktion im gesperrten Zustand sicher ausgeführt werden kann, verwende startActivity()
, um oben auf dem Sperrbildschirm eine Aktivität zu starten.
Wenn die Kachelaktion nicht sicher ist, verwende unlockAndRun()
, um den Nutzer zum Entsperren seines Geräts aufzufordern. Bei Erfolg führt das System das Objekt Runnable
aus, das Sie an diese Methode übergeben.
Nutzer auffordern, Ihre Kachel hinzuzufügen
Um Ihre Kachel manuell hinzuzufügen, müssen Nutzende mehrere Schritte ausführen:
- Wischen Sie nach unten, um die Schnelleinstellungen zu öffnen.
- Tippe auf die Schaltfläche „Bearbeiten“.
- Scrollen Sie auf dem Gerät durch alle Kacheln, bis sie Ihre Kachel finden.
- Halte deine Kachel gedrückt und ziehe sie in die Liste der aktiven Kacheln.
Der Nutzer kann Ihre Kachel auch jederzeit verschieben oder entfernen.
Ab Android 13 können Sie die Methode requestAddTileService()
verwenden, um Nutzern das Hinzufügen Ihrer Kachel zu einem Gerät zu erleichtern. Bei dieser Methode werden Nutzer aufgefordert, Ihre Kachel schnell direkt zu ihrem Schnelleinstellungen-Bereich hinzuzufügen. Der Prompt enthält den Namen der Anwendung, das angegebene Label und das Symbol.
![Aufforderung zur Platzierung der Quick Settings API](https://developer.android.com/static/develop/ui/views/images/placement-api-user-prompt.png?authuser=6&hl=de)
public void requestAddTileService (
ComponentName tileServiceComponentName,
CharSequence tileLabel,
Icon icon,
Executor resultExecutor,
Consumer<Integer> resultCallback
)
Der Callback enthält Informationen darüber, ob die Kachel hinzugefügt oder nicht hinzugefügt wurde, ob sie bereits vorhanden war oder ob ein Fehler aufgetreten ist.
Entscheiden Sie selbst, wann und wie oft Sie Nutzer auffordern. Wir empfehlen, requestAddTileService()
nur im Kontext aufzurufen, z. B. wenn der Nutzer zum ersten Mal mit einer Funktion interagiert, die deine Kachel unterstützt.
Das System kann die Verarbeitung von Anfragen für ein bestimmtes ComponentName
beenden, wenn es zuvor vom Nutzer häufig genug abgelehnt wurde. Der Nutzer wird aus dem Context
bestimmt, mit dem dieser Dienst abgerufen wurde. Er muss mit dem aktuellen Nutzer übereinstimmen.