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

Szybkie ustawienia to kafelki wyświetlane w panelu Szybkie ustawienia, reprezentujące działania, które użytkownicy mogą kliknąć, aby szybko ukończyć zadania cykliczne. Aplikacja może udostępniać użytkownikom niestandardowy kafelek za pomocą TileService i użyj obiektu Tile do śledzenia stanu kafelka. Przykład: możesz utworzyć kafelek umożliwiający użytkownikom włączanie sieci VPN udostępnianej przez Twoją aplikację wyłączone.

Zdecyduj, kiedy utworzyć kafelek

Zalecamy tworzenie kafelków dla określonych funkcji, których oczekujesz od użytkowników do często używanych lub do szybkiego dostępu (albo do obu tych rzeczy). Najskuteczniejszy kafelki to te, które pasują do obu tych cech. Zapewnia to szybki dostęp do często wykonywane działania.

Możesz na przykład utworzyć kafelek aplikacji do fitnessu, który umożliwi użytkownikom szybko rozpocząć sesję treningową. Nie zalecamy jednak tworzenia kafelka do tej samej aplikacji, która pozwalałaby użytkownikom przeglądać całą historię treningów.

Aby zwiększyć wykrywalność i łatwość obsługi kafelka, zalecamy unikanie pewnych praktyk:

• Unikaj uruchamiania aplikacji przy użyciu kafelków. Użyj skrótu do aplikacji lub standardowego Menu z aplikacjami.

• Unikaj używania kafelków do jednorazowych działań użytkownika. Użyj skrótu do aplikacji lub powiadomienie.

• Unikaj tworzenia zbyt wielu kafelków. Zalecamy ustawienie maksymalnie 2 na aplikację. Użyj skrót do aplikacji.

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

Utwórz kafelek

Aby utworzyć kafelek, musisz najpierw utworzyć odpowiednią ikonę, a potem Utwórz i zadeklaruj TileService w pliku manifestu aplikacji.

Przykład Szybkich ustawień pokazuje, jak utworzyć i zarządzać kafelkiem.

Utwórz ikonę niestandardową

Należy dodać ikonę niestandardową, która będzie wyświetlana na kafelku w Panel ustawień. (Tę ikonę trzeba dodać podczas deklarowania opcji TileService, opisane w następnej sekcji). Ikona musi być biała i zawierać ciąg Przezroczyste tło, 24 x 24 dp VectorDrawable

Utwórz ikonę informującą o przeznaczeniu kafelka. Pomaga to użytkownikom łatwo określić, czy Twój kafelek odpowiada potrzebom klienta. Możesz na przykład utworzyć ikona stopera dla kafelka aplikacji do fitnessu, który umożliwia użytkownikom sesji treningowej.

Tworzenie i zadeklarowanie usługi TileService

Utwórz dla kafelka usługę, 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 TileService w pliku manifestu aplikacji. Dodaj nazwę i etykietę z TileService, niestandardowej ikony utworzonej w poprzedniej sekcji, i odpowiedniej zgody.

 <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 właściwości TileService w manifeście aplikacji zarządzać swoim stanem.

TileService jest usługą powiązaną. Twoja TileService jest powiązana, gdy lub że system musi się z nią komunikować. Typowa Atrybut bound-service Lifecycle (cykl życia usługi) zawiera 4 metody wywołania zwrotnego: onCreate(), onBind(), onUnbind() i onDestroy(). Te metody są wywoływane przez system za każdym razem, gdy usługa przechodzi w nowy etap cyklu życia.

Omówienie cyklu życia TileService

Oprócz wywołań zwrotnych, które kontrolują cykl życia powiązanej usługi, musisz zaimplementuj inne metody właściwe dla cyklu życia TileService. Te metody może być wywoływane poza krajami onCreate() i onDestroy(), ponieważ Service metody cyklu życia i metody cyklu TileService są wywoływane w dwóch w osobnych wątkach asynchronicznych.

Cykl życia TileService obejmuje wywoływane metody przez system za każdym razem, gdy TileService rozpocznie nowy etap cyklu życia:

• onTileAdded(): ta metoda jest wywoływana tylko wtedy, gdy użytkownik doda Twoje pierwszy kafelek, a użytkownik usunie i ponownie doda kafelek. To najlepszy moment na każdą jednorazową inicjalizację. Może to jednak spowodować nie spełnia wszystkich wymagań inicjowania.

• onStartListening() i onStopListening(): te metody są jest wywoływana za każdym razem, gdy aplikacja aktualizuje kafelek i jest często wywoływana. TileService pozostaje w zakresie między onStartListening() a onStopListening(), co umożliwi aplikacji modyfikowanie kafelka i przekazywanie aktualizacji.

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

Wybierz tryb słuchania

Urządzenie TileService nasłuchuje w trybie aktywnym lub nieaktywnym. Zalecamy używając trybu aktywnego, co musisz zadeklarować w manifeście aplikacji. W przeciwnym razie TileService to tryb standardowy i nie trzeba go zadeklarować.

Nie zakładaj, że TileService będzie znajdować się poza tymi regionami: onStartListening() Para metod: onStopListening().

Tryb aktywny (zalecany)

Użyj trybu aktywnego w przypadku instancji TileService, która nasłuchuje i monitoruje stan i własny proces. Element TileService w trybie aktywnym jest powiązany z adresem onTileAdded(), onTileRemoved(), kliknąć zdarzenia, a gdy proces aplikacji o to poprosi.

Zalecamy tryb aktywny, jeśli urządzenie TileService otrzymuje powiadomienie o stanie kafelka powinny być aktualizowane w ramach własnego procesu. Aktywne kafelki ograniczają obciążenie systemu, ponieważ nie muszą być powiązane za każdym razem. stają się widoczne dla użytkownika.

Statyczna metoda TileService.requestListeningState() może zostać wywołana do zażąda rozpoczęcia stanu nasłuchiwania i otrzyma oddzwonienie pod onStartListening()

Tryb aktywny możesz zadeklarować, dodając META_DATA_ACTIVE_TILE do plik 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 za każdym razem, gdy Twój kafelek jest widoczny dla użytkownika. Oznacza to, że Twoja Element TileService może zostać utworzony i powiązany ponownie w przypadku, gdy jest on poza kontrolą tej organizacji. it może też być niepowiązana i zniszczona, gdy użytkownik nie wyświetla kafelka.

Twoja aplikacja otrzyma połączenie zwrotne pod numer onStartListening(), gdy użytkownik otworzy Panel Szybkie ustawienia. Obiekt Tile możesz zaktualizować dowolną liczbę razy od onStartListening() do onStopListening().

Nie musisz deklarować trybu nieaktywnego – wystarczy, że nie dodasz parametru META_DATA_ACTIVE_TILE do pliku manifestu aplikacji.

Omówienie stanów kafelków

Gdy użytkownik doda Twój kafelek, zawsze będzie on istniał w jednym z następujących stanów.

• STATE_ACTIVE: oznacza, że urządzenie jest włączone lub włączone. Użytkownik może w tym stanie wchodzić w interakcję z Twoim kafelkiem.

  Na przykład w przypadku kafelka aplikacji do fitnessu, który umożliwia użytkownikom rozpoczęcie treningu czasowego sesja, STATE_ACTIVE oznacza, że użytkownik zainicjował trening i minutnik jest aktywny.

• STATE_INACTIVE – oznacza, że urządzenie jest wyłączone lub wstrzymane. Użytkownik może w tym stanie wchodzić w interakcję z Twoim kafelkiem.

  Aby ponownie użyć przykładowego kafelka aplikacji fitness, kafelek w aplikacji STATE_INACTIVE oznacza, że użytkownik nie rozpoczął sesji treningu, ale może to zrobić, jeśli co chcieli.

• STATE_UNAVAILABLE: wskazuje stan tymczasowo niedostępny. użytkownik nie może wchodzić w interakcję z Twoim kafelkiem w tym stanie.

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

System ustawia tylko początkowy stan obiektu Tile. Ty ustawiasz: Tile stanie obiektu w pozostałej części jego cyklu życia.

System może zabarwić ikonę kafelka i tło, aby odzwierciedlić stan Tile obiekt. Tile obiekty ustawione na STATE_ACTIVE są najciemniejsze, z STATE_INACTIVE i STATE_UNAVAILABLE są coraz lżejsze. Dokładny odcień zależy od producenta i wersji.

Zaktualizuj kafelek

Możesz zaktualizować kafelek, gdy zadzwoni do Ciebie onStartListening(). W zależności od trybu kafelka możesz go zaktualizować co najmniej raz do odebranie połączenia zwrotnego pod numer onStopListening().

W trybie aktywnym możesz zaktualizować kafelek dokładnie raz, zanim otrzymasz oddzwanianie do onStopListening(). W trybie nieaktywnym możesz zaktualizować kafelek jako tyle razy, ile chcesz, od onStartListening() do onStopListening().

Możesz pobrać obiekt Tile, wywołując metodę getQsTile(). Aby zaktualizować określonych pól obiektu Tile wywołaj te metody:

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

Aby zaktualizować kafelek, musisz zadzwonić pod numer updateTile(), gdy skończysz ustawiać obiektu Tile na prawidłowe wartości. Dzięki temu system przeanalizować zaktualizowane dane kafelków i zaktualizować UI.

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

Dotknij uchwytu

Użytkownicy mogą kliknąć Twój kafelek, aby wywołać działanie, jeśli jest on w STATE_ACTIVE lub STATE_INACTIVE. System następnie wywołuje metodę onClick() – wywołanie zwrotne.

Gdy aplikacja otrzyma wywołanie zwrotne do onClick(), może otworzyć okno lub aktywności, aktywuj działanie w tle lub zmień 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();
}

Otwórz okno

showDialog() zwija panel Szybkie ustawienia i wyświetla okno. Jeśli wymagane jest dodatkowe wprowadzenie danych, użyj okna, aby dodać kontekst do działania. lub zgody użytkownika.

Uruchamianie aktywności

startActivityAndCollapse() rozpoczyna aktywność podczas zwijania elementu panel. Aktywności są przydatne, jeśli chcesz wyświetlić bardziej szczegółowe informacje niż w oknie lub jeśli akcja jest bardzo interaktywna.

Jeśli aplikacja wymaga istotnej interakcji użytkownika, powinna uruchomić tylko w ostateczności. Zamiast tego spróbuj użyć okna lub przełącznika.

Przytrzymanie kafelka powoduje wyświetlenie ekranu Informacje o aplikacji. Aby zastąpić i zamiast tego uruchom aktywność związaną z ustawieniami, dodaj <intent-filter> do jednej z Twoich aktywności z ACTION_QS_TILE_PREFERENCES

Od wersji Android API w wersji 28 interfejs PendingIntent musi Intent.FLAG_ACTIVITY_NEW_TASK:

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

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

Oznacz kafelek jako z możliwością przełączania

Zalecamy oznaczenie kafelka jako przełączania, jeśli działa on głównie przełączania dwóch stanów (co jest najczęstszym zachowaniem kafelków). To pomaga podać informacje o działaniu kafelka w systemie operacyjnym oraz poprawić ogólną dostępność.

Ustaw metadane TOGGLEABLE_TILE na true, aby oznaczyć kafelek jako możliwy do przełączania.

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

Wykonuj działania tylko na bezpiecznie zablokowanych urządzeniach

Na zablokowanych urządzeniach kafelek może się wyświetlać u góry ekranu blokady. Jeśli kafelek zawiera informacje poufne, sprawdź wartość isSecure() do określić, czy urządzenie jest w stanie bezpiecznym, a urządzenie TileService powinno odpowiednio zmienić jego działanie.

Jeśli działanie związane z kafelkiem można bezpiecznie wykonać po zablokowaniu, użyj ikony startActivity() , aby uruchomić aktywność na górze ekranu blokady.

Jeśli działanie związane z kafelkiem jest niebezpieczne, użyj polecenia unlockAndRun(), aby poprosić użytkownika o wykonanie tych czynności odblokować urządzenie dziecka. Jeśli operacja się uda, system wykona polecenie Runnable przekazywane do tego obiektu .

Poproś użytkownika o dodanie Twojego 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. Przewijać 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ąć Twój kafelek.

Począwszy od Androida 13 możesz używać metody requestAddTileService() , aby znacznie ułatwić użytkownikom dodawanie kafelka do urządzenia. Ta metoda prosi użytkowników o szybkie dodanie Twojego kafelka bezpośrednio do Panel ustawień. Zawiera on nazwę aplikacji, podaną etykietę, i ikonę.

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

Wywołanie zwrotne zawiera informacje o tym, czy kafelek został dodany. dodane, jeśli już tam są lub jeśli wystąpił jakiś błąd.

Decyzję o tym, kiedy i jak często prosić użytkowników o zgodę na wykorzystanie danych, należy wedle własnego uznania. Śr zalecamy wywoływanie funkcji requestAddTileService() tylko w kontekście, takim jak gdy użytkownik po raz pierwszy wejdzie w interakcję z funkcją udostępnianą przez Twój kafelek.

System może przestać przetwarzać żądania dotyczące określonej ComponentName, jeśli użytkownik odrzucił go wystarczająco często wcześniej. użytkownik jest określany na podstawie zbioru danych Context użytego do pobrania tego service – musi być zgodna z bieżącym użytkownikiem.