Benutzerdefinierte Schnelleinstellungen-Kacheln für Ihre App erstellen

Schnelleinstellungen sind Kacheln, die im Bereich Schnelleinstellungen angezeigt werden. Aktionen darstellen, auf die Nutzende tippen können, um schnell wiederkehrende Aufgaben zu erledigen. 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.

</ph>

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 entsprechen diesen beiden Eigenschaften, sodass Sie schnell auf häufig durchgeführten Aktionen.

Sie könnten beispielsweise eine Kachel für eine Fitness-App erstellen, mit der Nutzende Trainingseinheit schnell starten. Wir raten jedoch davon ab, eine Kachel zu erstellen, für dieselbe App, mit der Nutzer ihren gesamten Trainingsverlauf einsehen können.

</ph>

Um die Sichtbarkeit und Nutzerfreundlichkeit Ihrer Kachel zu verbessern, empfehlen wir, Vermeidung bestimmter Praktiken:

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

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

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

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

Kachel erstellen

Um eine Kachel zu erstellen, müssen Sie zuerst ein entsprechendes Kachelsymbol erstellen und dann die TileService in der Manifestdatei deiner App erstellen und deklarieren.

Das Beispiel Schnelleinstellungen enthält ein Beispiel für das Erstellen und eine Kachel verwalten.

Benutzerdefiniertes Symbol erstellen

Sie benötigen ein benutzerdefiniertes Symbol, das auf der Kachel im Schnellzugriff 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

</ph>

Erstellen Sie ein Symbol, das optisch auf den Zweck Ihrer Kachel verweist. Dies hilft Nutzenden, um leicht feststellen zu können, 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.

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

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. Name und Label hinzufügen von TileService, dem benutzerdefinierten Symbol, das Sie im vorherigen Abschnitt erstellt haben, und der entsprechenden Berechtigung.

 <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 TileService in deinem App-Manifest erstellt und deklariert hast, seinen Status verwalten muss.

TileService ist ein gebundener Dienst. Ihre TileService ist gebunden, wenn die von deiner App angefordert werden oder ob das System mit ihr kommunizieren muss. Ein typisches bound-service life enthält die folgenden vier Callback-Methoden: onCreate(), onBind(), onUnbind() und onDestroy(). Diese Methoden werden jedes Mal vom System aufgerufen, wenn der eine neue Lebenszyklusphase beginnt.

TileService-Lebenszyklus – Übersicht

Zusätzlich zu den Callbacks, die den Lebenszyklus des gebundenen Dienstes steuern, müssen Sie Implementieren Sie weitere Methoden, die für den TileService-Lebenszyklus spezifisch sind. 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 Lebenszyklus TileService enthält die folgenden Methoden, die aufgerufen werden vom System jedes Mal aus, wenn TileService in eine neue Lebenszyklusphase wechselt:

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

• 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() – so erlaubst du deiner App, die Ansicht zu ändern und Updates zu senden.

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

Zuhörmodus auswählen

TileService hört im Aktivmodus oder im Nicht-Aktiv-Modus zu. Wir empfehlen, im Aktivmodus. Diese musst du im App-Manifest deklarieren. Andernfalls TileService ist der Standardmodus und muss nicht deklariert werden.

Gehe nicht davon aus, dass dein TileService außerhalb von onStartListening() lebt und onStopListening()-Methodenpaar.

Aktivmodus (empfohlen)

Aktivmodus für einen TileService verwenden, der seinen Status in seiner eigenen Prozess. Ein TileService im Aktivmodus wird für onTileAdded() gebunden, onTileRemoved(), tippe auf Ereignisse und wenn dies vom App-Prozess angefordert wird.

Wir empfehlen den Aktivmodus, wenn dein TileService benachrichtigt wird, wenn dein Kachelstatus angezeigt wird in einem eigenen Prozess aktualisiert werden sollte. Aktive Kacheln begrenzen die Belastung des da sie nicht jedes Mal gebunden werden müssen, für den Nutzer sichtbar wird.

Die statische Methode TileService.requestListeningState() kann aufgerufen werden, um fordert den Start des Überwachungsstatus an und empfängt einen Rückruf an onStartListening().

Du kannst den Aktivmodus deklarieren, indem du META_DATA_ACTIVE_TILE zu deinem in der Manifestdatei der App.

<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 inaktiven Modus, wenn wenn Ihre Kachel für den Nutzer sichtbar ist. Das bedeutet, dass Ihre TileService kann zu Zeiten, die außerhalb ihrer Kontrolle liegen, neu erstellt und gebunden werden. Es kann auch aufgelöst und zerstört werden, wenn der Benutzer die Kachel nicht anzeigt.

Deine App erhält einen Rückruf an onStartListening(), nachdem der Nutzer sein Schnelleinstellungen. Sie können Ihr Tile-Objekt beliebig oft aktualisieren zwischen onStartListening() und onStopListening().

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

Ü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 der Status aktiviert oder aktiviert ist. Der Nutzer kann mit deiner Kachel interagieren.

  Zum Beispiel für eine Fitness-App-Kachel, mit der Nutzer ein zeitlich festgelegtes Training starten können. Sitzung bedeutet, bedeutet STATE_ACTIVE, 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. Die Benutzer kann in diesem Zustand nicht mit deiner Kachel interagieren.

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

  .

Das System legt nur den Anfangszustand 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.

</ph>

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 kannst du deine Kachel genau einmal aktualisieren, bevor du eine Callback an onStopListening(). Im inaktiven Modus kannst du deine Kachel folgendermaßen aktualisieren: zwischen onStartListening() und onStopListening() beliebig oft eingegeben werden.

Sie können das Tile-Objekt durch Aufrufen von getQsTile() abrufen. Zum Aktualisieren Ihres Tile-Objekts enthalten, rufen Sie die folgenden Methoden auf:

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

Du musst updateTile() aufrufen, um deine Kachel zu aktualisieren, sobald du mit dem Festlegen der des Tile-Objekts die richtigen Werte an. Dadurch wird das System die aktualisierten Kacheldaten parsen und die Benutzeroberfläche aktualisieren.

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

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

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 die Methode onClick()-Callback

Sobald deine App einen Callback von onClick() erhält, kann sie ein Dialogfeld öffnen oder Aktivitäten starten, Hintergrundarbeiten auslösen oder den Status der Kachel ändern.

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

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.

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 umfassende Nutzerinteraktion erfordert, sollte sie eine Aktivitäten nur als letztes Mittel. Verwenden Sie stattdessen ein Dialogfeld oder eine Ein/Aus-Schaltfläche.

Durch langes Tippen auf eine Kachel wird der Bildschirm App-Info 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 der PendingIntent Intent.FLAG_ACTIVITY_NEW_TASK:

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 ein-/ausschaltbar 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.

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ü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 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 dazu aufzufordern das Gerät zu entsperren. Bei Erfolg führt das System den Runnable-Objekt, das Sie in dieses .

Nutzer auffordern, Ihre Kachel hinzuzufügen

Um Ihre Kachel manuell hinzuzufügen, müssen Nutzende 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 auch jederzeit verschieben oder entfernen.

Ab Android 13 können Sie die Methode requestAddTileService() verwenden. damit Nutzende Ihre Kachel viel einfacher zu einem Gerät hinzufügen können. Diese Methode fordert Nutzende auf, Ihre Kachel schnell direkt ihrer Schnellübersicht hinzuzufügen. Einstellungen. Der Prompt enthält den Namen der Anwendung, das angegebene Label, und Symbol.

</ph>

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 wurde. hinzugefügt wurden, bereits vorhanden waren oder 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, wenn der Nutzer sie schon oft genug abgelehnt hat. Die Nutzer wird aus dem Context ermittelt, mit dem dies abgerufen wurde Dienst – er muss dem aktuellen Nutzer entsprechen.