Benutzerdefinierte Schnelleinstellungen-Kacheln für Ihre App erstellen

Schnelleinstellungen sind Kacheln, die im Bereich „Schnelleinstellungen“ angezeigt werden und Aktionen darstellen, auf die Nutzer tippen können, um wiederkehrende Aufgaben schnell auszuführen. Ihre App kann Nutzern über die TileService eine benutzerdefinierte Kachel zur Verfügung stellen. und ein Tile-Objekt verwenden, um den Status der Kachel zu verfolgen. Beispiel: können Sie eine Kachel erstellen, über die Nutzer ein von Ihrer App bereitgestelltes VPN aktivieren oder deaktiviert.

Abbildung 1: Bereich „Schnelleinstellungen“ mit aktivierter und deaktivierter VPN-Kachel

Hinweis: In diesem Leitfaden werden nur Kacheln behandelt, die nicht zu Wear OS gehören. Kacheln in den Schnelleinstellungen haben keinen Bezug zu den in Wear OS definierten Kacheln. Informationen zu Wear OS-Kacheln finden Sie im Leitfaden zu Wear OS-Kacheln.

Entscheiden, wann eine Kachel erstellt werden soll

Wir empfehlen, Kacheln für bestimmte Funktionen zu erstellen, die Nutzer erwarten. oft oder schnell auf sie zugreifen möchten (oder beides). Die effektivsten Kacheln erfüllen beide Kriterien und bieten schnellen Zugriff auf häufig ausgeführte Aktionen.

Sie können beispielsweise eine Kachel für eine Fitness-App erstellen, mit der Nutzer schnell ein Training starten können. Wir raten jedoch davon ab, für dieselbe App eine Kachel zu erstellen, über die Nutzer ihren gesamten Trainingsverlauf ansehen können.

Abbildung 2: Beispiele für empfohlene und nicht empfohlene Ansichten für eine Fitness-App.

Um die Sichtbarkeit und Nutzerfreundlichkeit Ihrer Kachel zu verbessern, empfehlen wir, bestimmte Praktiken zu vermeiden:

• Verwenden Sie keine Kacheln, um eine App zu starten. Verwenden Sie stattdessen einen App-Verknüpfung oder einen Standard-Launcher.

• Verwenden Sie keine Kacheln für einmalige Nutzeraktionen. App-Verknüpfung oder eine notification.

• Erstellen Sie nicht zu viele Kacheln. Wir empfehlen maximal zwei pro App. Verwenden Sie stattdessen einen App-Verknüpfung.

• Verwenden Sie keine Kacheln, die Informationen anzeigen, aber für Nutzenden. Verwenden Sie stattdessen eine Benachrichtigung oder ein Widget.

Kachel erstellen

Wenn Sie eine Kachel erstellen möchten, müssen Sie zuerst ein geeignetes Kachelsymbol erstellen und dann die TileService in der Manifestdatei Ihrer App erstellen und deklarieren.

Hinweis :Wenn Sie eine TileService für Ihre App erstellen, wird sie nicht der Quick Search-App des Nutzers hinzugefügt. Bereich „Einstellungen“. TileService fungiert nur als Schnittstelle für die Kachel nachdem der Nutzer sie hinzugefügt hat.

Das Beispiel für die Schnelleinstellungen zeigt, wie Sie eine Kachel erstellen und verwalten.

Benutzerdefiniertes Symbol erstellen

Sie benötigen ein benutzerdefiniertes Symbol, das auf der Kachel im Schnellzugriff Bereich „Einstellungen“. (Dieses Symbol wird beim Deklarieren der TileService hinzugefügt, wie im nächsten Abschnitt beschrieben.) Das Symbol muss durchgehend weiß sein und transparenter Hintergrund, 24 x 24 dp groß und in Form eines VectorDrawable

Abbildung 3 Beispiel für ein Vektor-Drawable

Erstellen Sie ein Symbol, das visuell auf den Zweck Ihrer Kachel hinweist. So können Nutzer leicht erkennen, ob Ihre Kachel ihren Anforderungen entspricht. Sie können beispielsweise eine Symbol einer Stoppuhr für eine Kachel für eine Fitness-App, mit der Nutzende eine Trainingseinheit.

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

Deklarieren Sie Ihre TileService in der Manifestdatei Ihrer App. Fügen Sie den Namen und das Label Ihrer 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 Sie Ihre TileService im App-Manifest erstellt und deklariert haben, müssen Sie ihren Status verwalten.

TileService ist ein gebundener Dienst. Ihre TileService wird gebunden, wenn sie von Ihrer App angefordert wird oder das System mit ihr kommunizieren muss. Ein typischer Lebenszyklus eines gebundenen Dienstes umfasst die folgenden vier Rückrufmethoden: onCreate(), onBind(), onUnbind() und onDestroy(). Diese Methoden werden vom System jedes Mal aufgerufen, wenn der Dienst in eine neue Lebenszyklusphase eintritt.

Wichtig: Ihr TileService durchläuft weiterhin den üblichen Service-Lebenszyklus. TileService unterscheidet sich jedoch von den meisten anderen gebundenen Diensten, da er TileService-spezifische Lebenszyklusmethoden enthält, auf die Ihre App reagieren muss.

TileService-Lebenszyklus – Übersicht

Zusätzlich zu den Callbacks, die den Lebenszyklus des verknüpften Dienstes steuern, müssen Sie andere Methoden implementieren, die speziell für den TileService-Lebenszyklus gelten. Diese Methoden kann außerhalb von onCreate() und onDestroy() aufgerufen werden, da die Service und die TileService-Lebenszyklusmethoden in zwei um separate asynchrone Threads zu erstellen.

Der TileService-Lebenszyklus umfasst die folgenden Methoden, die vom System jedes Mal aufgerufen werden, wenn Ihr TileService in eine neue Lebenszyklusphase eintritt:

• onTileAdded(): Diese Methode wird nur aufgerufen, wenn der Nutzer Ihre und wenn der Benutzer Ihre Kachel entfernt und wieder hinzufügt. Dies ist der beste Zeitpunkt für eine einmalige Initialisierung. Dies kann jedoch nicht alle erforderlichen Initialisierungen erfüllt.

  Hinweis: onTileAdded() wird bei der Erstellung der Kachel nicht aufgerufen. onTileAdded() wird beispielsweise nicht aufgerufen, wenn das Gerät neu gestartet oder eingeschaltet wird, wenn die Kachel hinzugefügt und nicht entfernt wurde, bevor das Gerät ausgeschaltet wurde.

• onStartListening() und onStopListening(): Diese Methoden sind wird aufgerufen, wenn deine App die Kachel aktualisiert, und wird häufig aufgerufen. Die TileService bleibt zwischen onStartListening() und onStopListening() gebunden, sodass Ihre App die Kachel ändern und Updates pushen kann.

• onTileRemoved(): Diese Methode wird nur aufgerufen, wenn der Nutzer Ihre Kachel entfernt.

Achtung :Diese Phasen treten möglicherweise nicht aufeinander auf. onTileAdded() wird möglicherweise nur einmal aufgerufen, wenn ein Nutzer Ihre Kachel in den Schnelleinstellungen hinzufügt. onStartListening() und onStopListening() können während des TileService-Lebenszyklus mehrmals aufgerufen werden. onTileRemoved() wird nie aufgerufen Der Nutzer entfernt Ihre Kachel nicht aus den Schnelleinstellungen.

Zuhörmodus auswählen

TileService hört im Aktivmodus oder im Nicht-Aktiv-Modus zu. Wir empfehlen den aktiven Modus, den Sie im App-Manifest deklarieren müssen. Andernfalls ist TileService der Standardmodus und muss nicht deklariert werden.

Angenommen, Ihr TileService wird außerhalb der Methoden onStartListening() und onStopListening() verwendet.

Aktivmodus (empfohlen)

Aktivmodus für einen TileService verwenden, der seinen Status in seiner eigenen Prozess. Ein TileService im Aktivmodus ist für onTileAdded(), onTileRemoved(), Tippen-Ereignisse und auf Anfrage des App-Prozesses gebunden.

Wir empfehlen den aktiven Modus, wenn Ihre TileService benachrichtigt werden soll, wenn der Kachelnstatus durch einen eigenen Prozess aktualisiert werden soll. Aktive Kacheln begrenzen die Belastung des Systems, da sie nicht jedes Mal gebunden werden müssen, wenn das Steuerfeld für die Schnelleinstellungen für den Nutzer sichtbar wird.

Die statische Methode TileService.requestListeningState() kann aufgerufen werden, um den Start des Hörstatus anzufordern und einen Callback an onStartListening() zu erhalten.

Sie können den aktiven Modus deklarieren, indem Sie der Manifestdatei Ihrer App META_DATA_ACTIVE_TILE hinzufügen.

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

Nicht-Aktiv-Modus

Der nicht aktive Modus ist der Standardmodus. Ein TileService befindet sich im Inaktivmodus, wenn es immer dann gebunden ist, wenn Ihre Kachel für den Nutzer sichtbar ist. Das bedeutet, dass Ihre TileService möglicherweise außerhalb des Einflussbereichs von Google erstellt und wieder gebunden wird. Es kann auch aufgelöst und zerstört werden, wenn der Benutzer die Kachel nicht anzeigt.

Ihre App erhält einen Rückruf an onStartListening(), nachdem der Nutzer das Steuerfeld für die Schnelleinstellungen geöffnet hat. Sie können Ihr Tile-Objekt zwischen onStartListening() und onStopListening() beliebig oft aktualisieren.

Achtung: Wenn Sie den inaktiven Modus anstelle des aktiven Modus verwenden, wird Ihre TileService möglicherweise jedes Mal gebunden, wenn der Nutzer das Schnelleinstellungsfeld öffnet.

Der inaktive Modus muss nicht deklariert werden. Fügen Sie lediglich META_DATA_ACTIVE_TILE in die Manifestdatei deiner App.

Kachelstatus – Übersicht

Nachdem ein Nutzer Ihre Kachel hinzugefügt hat, befindet sie sich immer in einem der folgenden Status.

• STATE_ACTIVE: Gibt an, dass die Funktion aktiviert ist. Der Nutzer kann mit deiner Kachel interagieren.

  Bei einer Kachel für eine Fitness-App, mit der Nutzer ein zeitgesteuertes Training starten können, würde STATE_ACTIVE beispielsweise bedeuten, dass der Nutzer ein Training gestartet hat und der Timer läuft.

• STATE_INACTIVE: steht für „Aus“ oder „Pausiert“. Der Nutzer kann mit deiner Kachel interagieren.

  Um wieder das Beispiel für die Kachel der Fitness-App zu verwenden, würde eine Kachel in STATE_INACTIVE dass der Nutzer keine Trainingseinheit gestartet hat, dies aber tun könnte, sie wollten.

• STATE_UNAVAILABLE: zeigt an, dass der Status vorübergehend nicht verfügbar ist. In diesem Status kann der Nutzer nicht mit Ihrer Kachel interagieren.

  Beispielsweise bedeutet eine Kachel in STATE_UNAVAILABLE, dass die Kachel nicht dem Nutzer derzeit zur Verfügung stehen.

  Achtung :Verwenden Sie STATE_UNAVAILABLE für Kacheln, die derzeit nicht verfügbar sind. aber später in den Status „Verfügbar“ versetzt werden kann. Wenn die Komponente für den Nutzer nie wieder verfügbar sein wird, übergeben Sie COMPONENT_ENABLED_STATE_DISABLED an setComponentEnabledSetting().

Das System legt nur den anfänglichen Status des Tile-Objekts fest. Du legst die Tile fest Status des Objekts während des restlichen Lebenszyklus.

Das System kann das Kachelsymbol und den Hintergrund färben, um den Zustand Ihrer Tile-Objekt. Tile-Objekte, die auf STATE_ACTIVE gesetzt sind, sind am dunkelsten, wobei STATE_INACTIVE und STATE_UNAVAILABLE werden immer leichter. Den genauen Farbton ist hersteller- und versionsspezifisch.

Abbildung 4: Beispiele für eine Kachel, die entsprechend dem Kachelstatus (aktiv, inaktiv und nicht verfügbar) gefärbt ist.

Kachel aktualisieren

Du kannst deine Kachel aktualisieren, sobald du einen Rückruf von onStartListening() erhältst. Je nach Modus der Kachel kann Ihre Kachel mindestens einmal aktualisiert werden, bis Ein Rückruf von onStopListening() wird empfangen.

Im Aktivmodus können Sie Ihre Kachel genau einmal aktualisieren, bevor Sie einen Rückruf an onStopListening() erhalten. Im inaktiven Modus kannst du deine Kachel folgendermaßen aktualisieren: zwischen onStartListening() und onStopListening() beliebig oft eingegeben werden.

Hinweis: Im aktiven Modus können Sie Ihre Kachel aktualisieren, unabhängig davon, ob sie für den Nutzer sichtbar ist oder nicht.

Sie können das Tile-Objekt durch Aufrufen von getQsTile() abrufen. Wenn Sie bestimmte Felder Ihres Tile-Objekts aktualisieren möchten, rufen Sie die folgenden Methoden auf:

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

Hinweis :Das Symbol und das Label, die in der Manifestdatei Ihrer App festgelegt sind, sind die Standardwerte. die auf der Kachel im Bereich „Schnelleinstellungen“ angezeigt wird. Sie können jedoch die Methode setIcon()- und setLabel()-Methoden, wenn Sie Ihre Kachel aktualisieren, um die Felder festzulegen in neue Werte zu verwandeln.

Rufen Sie updateTile() auf, um die Kachel zu aktualisieren, sobald Sie die Felder des Tile-Objekts auf die richtigen Werte festgelegt haben. Dadurch werden die aktualisierten Kacheln vom System geparst und die Benutzeroberfläche aktualisiert.

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

Armaturen bedienen

Benutzer können auf Ihre Kachel tippen, um eine Aktion auszulösen, wenn sich Ihre Kachel befindet STATE_ACTIVE oder STATE_INACTIVE. Das System ruft dann den onClick()-Callback Ihrer App auf.

Sobald Ihre App einen Rückruf an onClick() erhält, kann sie ein Dialogfeld oder eine Aktivität starten, Hintergrundarbeiten auslösen oder den Status Ihrer 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. Verwenden Sie ein Dialogfeld, um Ihrer Aktion Kontext hinzuzufügen, falls zusätzliche Informationen erforderlich sind oder die Einwilligung der Nutzer.

Hinweis :isLocked() prüft, ob der Sperrbildschirm des Nutzers angezeigt wird. Wann? isLocked() gibt „true“ zurück, showDialog() zeigt kein sichtbares Dialogfeld an weil sie unter dem Sperrbildschirm geladen wird.

Aktivität starten

startActivityAndCollapse() startet eine Aktivität beim Minimieren des . Aktivitäten sind nützlich, wenn detailliertere Informationen angezeigt werden sollen als in einem Dialog oder wenn Ihre Handlung sehr interaktiv ist.

Wenn Ihre App eine erhebliche Nutzerinteraktion erfordert, sollte sie eine Aktivitäten nur als letztes Mittel. Verwenden Sie stattdessen einen Dialog oder einen Schalter.

Wenn Sie lange auf eine Kachel tippen, wird der Bildschirm App-Informationen angezeigt. Zum Überschreiben und starten Sie stattdessen eine Aktivität zum Festlegen von Einstellungen, fügen Sie eine <intent-filter> auf eine deiner Aktivitäten mit ACTION_QS_TILE_PREFERENCES

Ab Android API 28 muss die PendingIntent folgende 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 in der spezifischen Activity.

Kachel als umschaltbar markieren

Wir empfehlen, Ihre Kachel als ein-/ausschaltbar zu kennzeichnen, wenn sie primär als Zwei-Status-Schalter (dies ist das gängigste Verhalten von Kacheln) Das hilft, dem Betriebssystem Informationen über das Verhalten der Kachel liefern die Barrierefreiheit insgesamt zu verbessern.

Legen Sie die TOGGLEABLE_TILE-Metadaten auf true fest, um die Kachel als umschaltbar 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

Auf gesperrten Geräten wird Ihre Kachel möglicherweise über dem Sperrbildschirm angezeigt. Wenn die Kachel vertrauliche Informationen enthält, prüfen Sie den Wert von isSecure(), um um festzustellen, ob sich das Gerät in einem sicheren Zustand befindet, und dein TileService sollte ihr Verhalten entsprechend ändern.

Wenn die Aktion der Kachel bei gesperrtem Display sicher ausgeführt werden kann, verwenden Sie startActivity(), um eine Aktivität über dem Sperrbildschirm zu starten.

Wenn die Aktion der Kachel nicht sicher ist, verwenden Sie unlockAndRun(), um den Nutzer aufzufordern, sein Gerät zu entsperren. Bei Erfolg führt das System das Runnable-Objekt aus, das Sie in diese Methode übergeben.

Nutzer auffordern, Ihre Kachel hinzuzufügen

Wenn Nutzer Ihre Kachel manuell hinzufügen möchten, müssen sie mehrere Schritte ausführen:

1. Wischen Sie nach unten, um die Schnelleinstellungen zu öffnen.
2. Tippe auf die Schaltfläche „Bearbeiten“.
3. Scrollen Sie auf dem Gerät durch alle Kacheln, bis sie Ihre Kachel finden.
4. Halte deine Kachel gedrückt und ziehe sie in die Liste der aktiven Kacheln.

Der Nutzer kann Ihre Kachel 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 direkt in den Bereich „Schnelleinstellungen“ aufzunehmen. Die Aufforderung enthält den Namen der Anwendung, das bereitgestellte Label und das Symbol.

Abbildung 5: Quick Settings API-Aufforderung

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

Der Rückruf enthält Informationen dazu, ob die Kachel hinzugefügt wurde oder nicht, ob sie bereits vorhanden war oder ob ein Fehler aufgetreten ist.

Entscheiden Sie selbst, wann und wie oft Sie Nutzer auffordern. Mi. empfehlen, requestAddTileService() nur im Kontext aufzurufen, z. B. wenn der Nutzer zum ersten Mal mit einer Funktion interagiert, die von deiner Kachel unterstützt wird.

Das System kann die Verarbeitung von Anfragen für eine bestimmte ComponentName beenden, wenn sie vom Nutzer schon oft genug abgelehnt wurde. Die Nutzer wird aus dem Context ermittelt, mit dem dies abgerufen wurde Dienst – er muss dem aktuellen Nutzer entsprechen.

Hinweis: Wir empfehlen, requestAddTileService() aufzurufen, um die Sichtbarkeit Ihrer Kachel zu erhöhen und die Nutzer zu entlasten, die Ihre Kachel in den Schnelleinstellungen hinzufügen müssen.