Twórz własne kafelki Szybkich ustawień dla swojej aplikacji

Szybkie ustawienia to kafelki wyświetlane w panelu Szybkie ustawienia, które reprezentują działania, które użytkownicy mogą wykonać, aby szybko wykonać powtarzające się zadania. Aplikacja może wyświetlać użytkownikom niestandardową kartę za pomocą klasy TileService i obiektu Tile, aby śledzić stan karty. Możesz na przykład utworzyć kafelek, który umożliwia użytkownikom włączanie i wyłączanie VPN-u udostępnianego przez Twoją aplikację.

Kiedy utworzyć kafelek

Zalecamy tworzenie kafelków dla konkretnych funkcji, do których użytkownicy będą często zaglądać lub do których będą potrzebować szybkiego dostępu (lub obu tych opcji). Najskuteczniejsze kafelki to te, które spełniają oba te kryteria i zapewniają szybki dostęp do często wykonywanych czynności.

Możesz na przykład utworzyć kafelek dla aplikacji fitness, która pozwoli użytkownikom szybko rozpocząć trening. Nie zalecamy jednak tworzenia kafelka dla tej samej aplikacji, który pozwoliłby użytkownikom przeglądać całą historię treningów.

Aby zwiększyć widoczność kafelka i ułatwić jego obsługę, zalecamy unikanie tych praktyk:

• Nie używaj kafelków do uruchamiania aplikacji. Zamiast tego użyj skrótu aplikacji lub standardowego programu uruchamiającego.

• Unikaj używania płytek w przypadku jednorazowych działań użytkowników. Zamiast tego użyj skrótu aplikacji lub powiadomienia.

• Unikaj tworzenia zbyt wielu kafelków. Zalecamy maksymalnie 2 skróty na aplikację. Zamiast tego użyj skrótu aplikacji.

• Unikaj kafelków, które wyświetlają informacje, ale nie są interaktywne dla użytkowników. Zamiast tego użyj powiadomienia lub widżetu.

Tworzenie kafelka

Aby utworzyć kafelek, musisz najpierw utworzyć odpowiednią ikonę kafelka, a potem utworzyć i zadeklarować TileService w pliku manifestu aplikacji.

Przykład Szybkich ustawień pokazuje, jak tworzyć kafelki i nimi zarządzać.

Tworzenie ikony niestandardowej

Musisz przesłać niestandardową ikonę, która będzie widoczna na kafelku w panelu Szybkie ustawienia. (dodasz tę ikonę podczas deklarowania TileService, jak opisano w następnej sekcji). Ikona musi być w kolorze białym na przezroczystym tle, mieć wymiary 24 x 24 pikseli i być w formie VectorDrawable.

Utwórz ikonę, która wizualnie wskazuje przeznaczenie kafelka. Dzięki temu użytkownicy mogą łatwo określić, czy Twoja karta odpowiada ich potrzebom. Możesz na przykład utworzyć ikonę stopera dla kafelka aplikacji fitness, która pozwala użytkownikom rozpocząć trening.

Tworzenie i deklarowanie TileService

Utwórz usługę dla kafelka, która rozszerza klasę TileService.

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

Zadeklaruj uprawnienia TileService w pliku manifestu aplikacji. Dodaj nazwę i etykietę TileService, ikonę niestandardową utworzoną w poprzedniej sekcji oraz odpowiednie uprawnienia.

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

Zarządzanie usługą TileService

Po utworzeniu i zadeklarowaniu TileService w pliku manifestu aplikacji musisz zarządzać jego stanem.

TileService to powiązana usługa. TileService jest związany, gdy aplikacja o to poprosi lub gdy system musi się z nim komunikować. Typowy cykl życia usługi powiązanej obejmuje 4 metody wywołania zwrotnego: onCreate(), onBind(), onUnbind() i onDestroy(). Te metody są wywoływane przez system za każdym razem, gdy usługa wchodzi w nową fazę cyklu życia.

Omówienie cyklu życia usługi TileService

Oprócz wywołań zwrotnych, które kontrolują cykl życia powiązanej usługi, musisz zaimplementować inne metody związane z cyklem życia TileService. Te metody mogą być wywoływane poza onCreate() i onDestroy(), ponieważ metody cyklu życia Service i metody cyklu życia TileService są wywoływane w 2 oddzielnych wątkach asynchronicznych.

Cykl życia TileService zawiera te metody, które są wywoływane przez system za każdym razem, gdy TileService wchodzi w nową fazę cyklu życia:

• onTileAdded(): ta metoda jest wywoływana tylko wtedy, gdy użytkownik dodaje kafelek po raz pierwszy lub gdy usuwa i ponownie dodaje kafelek. To najlepszy moment na wykonanie jednorazowej inicjalizacji. Może to jednak nie wystarczyć do pełnej inicjalizacji.

• onStartListening() i onStopListening(): te metody są wywoływane za każdym razem, gdy aplikacja aktualizuje kafelek. Są one często wywoływane. TileService pozostaje powiązany między onStartListening() a onStopListening(), co pozwala aplikacji modyfikować kafelek i przesyłać aktualizacje.

• onTileRemoved(): ta metoda jest wywoływana tylko wtedy, gdy użytkownik usunie kafelek.

Wybierz tryb słuchania

Usługa TileService nasłuchuje w trybie aktywnym lub nieaktywnym. Zalecamy używanie trybu aktywnego, który musisz zadeklarować w manifeście aplikacji. W przeciwnym razie TileService jest trybem standardowym i nie wymaga deklaracji.

Nie zakładaj, że TileService będzie działać poza metodami onStartListening() i onStopListening().

Tryb aktywny (zalecany)

Użyj trybu aktywnego w przypadku aplikacji TileService, która nasłuchuje i monitoruje swój stan w ramach własnego procesu. TileService w trybie aktywnym jest powiązany z aplikacją onTileAdded(), onTileRemoved(), zdarzeniami dotknięcia oraz wtedy, gdy proces aplikacji o to poprosi.

Zalecamy tryb aktywny, jeśli TileService jest powiadamiany, gdy stan kafelka powinien zostać zaktualizowany przez własny proces. Aktywne kafelki ograniczają obciążenie systemu, ponieważ nie muszą być powiązane za każdym razem, gdy użytkownik widzi panel Szybkie ustawienia.

Statyczne metody TileService.requestListeningState() można użyć, aby poprosić o rozpoczęcie stanu słuchania i otrzymanie połączenia zwrotnego do metody onStartListening().

Tryb aktywny możesz zadeklarować, dodając META_DATA_ACTIVE_TILE do pliku manifestu aplikacji.

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

Tryb nieaktywny

Tryb nieaktywny to tryb standardowy. TileService jest w trybie nieaktywnym, jeśli jest powiązany z każdym widocznym dla użytkownika kafelkiem. Oznacza to, że TileService może zostać utworzona i ponownie powiązana w czasie, na który nie ma wpływu. Może też zostać odłączona i zniszczona, gdy użytkownik nie wyświetla kafelka.

Gdy użytkownik otworzy panel Szybkie ustawienia, Twoja aplikacja otrzyma wywołanie zwrotne do funkcji onStartListening(). Obiekt Tile możesz aktualizować dowolną liczbę razy w okresie od onStartListening() do onStopListening().

Nie musisz deklarować trybu nieaktywnego – po prostu nie dodawaj tagu META_DATA_ACTIVE_TILE do pliku manifestu aplikacji.

Omówienie stanów kart

Gdy użytkownik doda kafelek, będzie on zawsze w jednym z tych stanów.

• STATE_ACTIVE: oznacza stan włączony. W tym stanie użytkownik może wchodzić w interakcje z Twoim kafelkiem.

  Na przykład w przypadku kafelka aplikacji fitness, która umożliwia użytkownikom rozpoczęcie treningu z licznikiem czasu, STATE_ACTIVE oznacza, że użytkownik rozpoczął trening i licznik jest uruchomiony.

• STATE_INACTIVE: oznacza stan wyłączony lub wstrzymany. W tym stanie użytkownik może wchodzić w interakcje z Twoim kafelkiem.

  Wracając do przykładu kafelka aplikacji do fitnessu, kafelek w pozycji STATE_INACTIVE oznacza, że użytkownik nie rozpoczął sesji treningowej, ale może to zrobić, jeśli zechce.

• STATE_UNAVAILABLE: oznacza stan tymczasowo niedostępny. W tym stanie użytkownik nie może korzystać z Twojego kafelka.

  Na przykład kafelek w pozycji STATE_UNAVAILABLE oznacza, że z jakiegoś powodu nie jest on obecnie dostępny dla użytkownika.

System ustawia tylko początkowy stan obiektu Tile. Stan obiektu Tile możesz zmieniać przez cały jego cykl życia.

System może zabarwić ikonę i tło kafelka, aby odzwierciedlić stan obiektu Tile. Obiekty Tile z wartością STATE_ACTIVE są najciemniejsze, a z wartością STATE_INACTIVE i STATE_UNAVAILABLE – coraz jaśniejsze. Dokładny odcień zależy od producenta i wersji.

Aktualizowanie kafelka

Możesz zaktualizować kafelek, gdy otrzymasz połączenie zwrotne na numer onStartListening(). W zależności od trybu kafelka może on zostać zaktualizowany co najmniej raz, dopóki nie otrzymasz połączenia zwrotnego na numer onStopListening().

W trybie aktywnym możesz zaktualizować kafelek dokładnie raz przed otrzymaniem wywołania zwrotnego onStopListening(). W trybie nieaktywnym możesz aktualizować kafelek dowolną liczbę razy w okresie od onStartListening() do onStopListening().

Obiekt Tile możesz odzyskać, wywołując funkcję getQsTile(). Aby zaktualizować określone pola obiektu Tile, wywołaj te metody:

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

Aby zaktualizować kafelek, po ustawieniu odpowiednich wartości pól obiektu Tile musisz wywołać funkcję updateTile(). System przeanalizuje zaktualizowane dane kafelka i zaktualizuje interfejs użytkownika.

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

Obsługa dotknięć

Użytkownicy mogą kliknąć kafelek, aby wywołać działanie, jeśli jest on w stanie STATE_ACTIVE lub STATE_INACTIVE. Następnie system wywołuje funkcję wywołania zwrotnego onClick() w aplikacji.

Gdy aplikacja otrzyma wywołanie zwrotne do onClick(), może uruchomić okno dialogowe lub aktywność, wywołać działanie w tle lub zmienić stan kafelka.

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

Uruchom okno

showDialog() zwijanie panelu Szybkie ustawienia i wyświetlenie okna dialogowego. Jeśli działanie wymaga dodatkowych danych lub zgody użytkownika, dodaj kontekst za pomocą okna.

Uruchamianie aktywności

startActivityAndCollapse() rozpoczyna aktywność podczas zwijania panelu. Aktywności są przydatne, gdy chcesz wyświetlić więcej szczegółowych informacji niż w dialogu lub gdy Twoje działanie jest bardzo interaktywne.

Jeśli aplikacja wymaga znaczącej interakcji z użytkownikiem, powinna uruchamiać aktywność tylko w ostatniej chwili. Zamiast tego rozważ użycie okna dialogowego lub przełącznika.

Długie naciśnięcie kafelka powoduje wyświetlenie użytkownikowi ekranu Informacje o aplikacji. Aby zmienić to zachowanie i zamiast tego uruchomić aktywność do ustawiania preferencji, dodaj <intent-filter> do jednej z aktywności z ACTION_QS_TILE_PREFERENCES.

Począwszy od poziomu 28 interfejsu API Androida PendingIntent musi mieć Intent.FLAG_ACTIVITY_NEW_TASK:

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

Możesz też dodać flagę w sekcji AndroidManifest.xml w sekcji Activity.

Oznaczanie kafelka jako przełączalny

Zalecamy oznaczenie kafelka jako przełącznika, jeśli działa on głównie jako przełącznik dwustanowy (co jest najczęstszym zachowaniem kafelków). Pomaga to systemowi operacyjnemu w dostarczanie informacji o zachowaniu kafelka i poprawiać ogólną dostępność.

Aby oznaczyć kafelek jako przełączalny, ustaw metadane TOGGLEABLE_TILE na true.

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

Wykonywanie tylko bezpiecznych działań na urządzeniach z włączoną blokadą

Na zablokowanych urządzeniach kafelek może być widoczny u góry ekranu blokady. Jeśli kafelek zawiera poufne informacje, sprawdź wartość isSecure(), aby określić, czy urządzenie jest w bezpiecznym stanie, i odpowiednio zmień działanie funkcji TileService.

Jeśli działanie przycisku jest bezpieczne, gdy ekran jest zablokowany, naciśnij startActivity(), aby uruchomić aktywność na ekranie blokady.

Jeśli działanie kafelka jest niebezpieczne, użyj polecenia unlockAndRun(), aby poprosić użytkownika o odblokowanie urządzenia. Jeśli operacja się powiedzie, system wykona obiekt Runnable przekazany do tej metody.

Prośba o dodanie kafelka

Aby ręcznie dodać kafelek, użytkownicy muszą wykonać kilka czynności:

1. Przesuń palcem w dół, aby otworzyć panel Szybkie ustawienia.
2. Kliknij przycisk edycji.
3. Przewijają wszystkie kafelki na urządzeniu, aż znajdą Twój kafelek.
4. Przytrzymaj kafelek i przeciągnij go na listę aktywnych kafelków.

Użytkownik może też w dowolnym momencie przenieść lub usunąć Twoją kartę.

Od Androida 13 możesz używać metody requestAddTileService(), aby znacznie ułatwić użytkownikom dodawanie kafelka do urządzenia. Ta metoda wyświetla użytkownikom prośbę o szybkie dodanie kafelka bezpośrednio do panelu Szybkie ustawienia. Prośba zawiera nazwę aplikacji, podawaną etykietę i ikonę.

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

Odwołanie zawiera informacje o tym, czy kafelek został dodany, nie został dodany, czy był już dodany lub czy wystąpił jakiś błąd.

Decydując, kiedy i jak często wyświetlać użytkownikom prompty, kieruj się zdrowym rozsądkiem. Zalecamy wywoływanie funkcji requestAddTileService() tylko w określonym kontekście, np. gdy użytkownik po raz pierwszy wejdzie w interakcję z funkcją obsługiwaną przez kafelek.

System może przestać przetwarzać żądania dotyczące danego ComponentName, jeśli użytkownik odrzucił je wystarczająco dużo razy. Użytkownik jest określany na podstawie parametru Context użytego do pobrania tej usługi. Musi on odpowiadać bieżącemu użytkownikowi.