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

Szybkie ustawienia to kafelki wyświetlane w panelu Szybkich ustawień, które reprezentują działania. Użytkownicy mogą je klikać, aby szybko wykonywać zadania cykliczne. Aplikacja może udostępniać użytkownikom niestandardową kartę za pomocą klasy TileService i używać obiektu Tile do śledzenia stanu karty. Możesz na przykład utworzyć kafelek, który umożliwia użytkownikom włączanie i wyłączanie sieci VPN udostępnianej przez Twoją aplikację.

Panel Szybkich ustawień z włączonym i wyłączonym kafelkiem VPN
Rysunek 1. Panel Szybkich ustawień z włączonym i wyłączonym kafelkiem VPN.

Kiedy warto utworzyć kartę

Zalecamy tworzenie kafelków dla konkretnych funkcji, z których użytkownicy będą często korzystać lub do których będą potrzebować szybkiego dostępu (lub jedno i drugie). Najskuteczniejsze kafelki to te, które łączą obie te cechy, zapewniając szybki dostęp do często wykonywanych działań.

Możesz na przykład utworzyć kartę aplikacji treningowej, która pozwoli użytkownikom szybko rozpocząć sesję treningową. Nie zalecamy jednak tworzenia kafelka dla tej samej aplikacji, który umożliwiałby użytkownikom przeglądanie całej historii treningów.

Przykłady użycia kart aplikacji treningowej
Rysunek 2. Przykłady zalecanych i niezalecanych kafelków aplikacji treningowej.

Aby ułatwić użytkownikom znajdowanie kafelka i korzystanie z niego, zalecamy unikanie pewnych praktyk:

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

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

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

  • Unikaj używania 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 następnie utworzyć i zadeklarować element TileService w pliku manifestu aplikacji.

Przykładowe Szybkie ustawienia pokazują, jak utworzyć kafelek i nim zarządzać.

Tworzenie ikony niestandardowej

Musisz podać ikonę niestandardową, która będzie wyświetlana na kafelku w panelu Szybkich ustawień. (Tę ikonę dodasz podczas deklarowania TileService, co opisano w następnej sekcji). Ikona musi być jednolicie biała na przezroczystym tle, mieć wymiary 24 x 24 dp i być w formacie VectorDrawable.

Przykład obiektu rysowalnego wektorowo
Rysunek 3. Przykład obiektu rysowalnego wektorowo.

Utwórz ikonę, która wizualnie wskazuje przeznaczenie kafelka. Dzięki temu użytkownicy mogą sprawdzić, czy Twoja karta odpowiada ich potrzebom. Możesz na przykład utworzyć ikonę stopera dla kafelka aplikacji treningowej, która umożliwia użytkownikom rozpoczęcie sesji treningowej.

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

Zadeklaruj TileService w pliku manifestu aplikacji. Dodaj nazwę i etykietę TileService (maksymalnie 18 znaków w przypadku android:label), ikonę niestandardową utworzoną w poprzedniej sekcji i odpowiednie uprawnienia.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     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 TileService

Po utworzeniu i zadeklarowaniu TileService w manifeście aplikacji musisz zarządzać jego stanem.

TileService to powiązana usługa. Usługa TileService jest powiązana, gdy wymaga tego aplikacja lub gdy system musi się z nią skomunikować. Typowy cykl życia powiązanej usługi zawiera te 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 TileService

Oprócz wywołań zwrotnych, które kontrolują cykl życia powiązanej usługi, musisz zaimplementować inne metody specyficzne dla cyklu życia TileService. Te metody mogą być wywoływane poza onCreate() i onDestroy(), ponieważ metody cyklu życia Service i 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, a także gdy go usunie i doda ponownie. To najlepszy moment na jednorazową inicjalizację. Może to jednak nie wystarczyć do przeprowadzenia całej wymaganej inicjalizacji.

  • onStartListening() i onStopListening(): te metody są wywoływane za każdym razem, gdy aplikacja aktualizuje kafelek, i są wywoływane często. TileService pozostaje powiązany z onStartListening() i onStopListening(), co umożliwia aplikacji modyfikowanie kafelka i wysyłanie aktualizacji.

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

Wybierz tryb słuchania

TileService nasłuchuje w trybie aktywnym lub nieaktywnym. Zalecamy korzystanie z trybu aktywnego, który musisz zadeklarować w pliku manifestu aplikacji. W przeciwnym razie TileService jest trybem standardowym i nie trzeba go deklarować.

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

Użyj trybu aktywnego w przypadku TileService, który nasłuchuje i monitoruje swój stan we własnym procesie. TileService w trybie aktywnym jest powiązany z onTileAdded(), onTileRemoved(), zdarzeniami kliknięcia i żądaniami procesu aplikacji.

Zalecamy tryb aktywny, jeśli TileService otrzymuje powiadomienie, gdy stan kafelka powinien zostać zaktualizowany przez jego własny proces. Aktywne kafelki ograniczają obciążenie systemu, ponieważ nie muszą być powiązane za każdym razem, gdy panel Szybkich ustawień staje się widoczny dla użytkownika.

Można wywołać statyczną metodę TileService.requestListeningState(), aby poprosić o rozpoczęcie stanu nasłuchiwania i otrzymać wywołanie zwrotne do 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 jest trybem standardowym. TileService jest w trybie nieaktywnym, jeśli jest powiązany, gdy kafelek jest widoczny dla użytkownika. Oznacza to, że TileService może być tworzony i wiązany ponownie w momentach, na które nie ma wpływu. Może też zostać odłączony i zniszczony, gdy użytkownik nie wyświetla kafelka.

Po otwarciu przez użytkownika panelu Szybkich ustawień aplikacja otrzyma wywołanie zwrotne do onStartListening(). Obiekt Tile możesz aktualizować dowolną liczbę razy między onStartListening() a onStopListening().

Nie musisz deklarować trybu nieaktywnego: nie dodawaj uprawnienia META_DATA_ACTIVE_TILE do pliku manifestu aplikacji.

Omówienie stanów kafelków

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

  • STATE_ACTIVE: wskazuje stan włączenia. W tym stanie użytkownik może wchodzić w interakcje z kartą.

    Na przykład w przypadku kafelka aplikacji treningowej, który umożliwia użytkownikom rozpoczęcie sesji treningowej z pomiarem czasu, STATE_ACTIVE oznacza, że użytkownik rozpoczął sesję treningową i stoper działa.

  • STATE_INACTIVE: wskazuje stan wyłączenia lub wstrzymania. W tym stanie użytkownik może wchodzić w interakcje z kartą.

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

  • STATE_UNAVAILABLE: wskazuje stan tymczasowej niedostępności. W tym stanie użytkownik nie może wejść w interakcję z kafelkiem.

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

System ustawia tylko stan początkowy obiektu Tile. Ustawiasz stan obiektu Tile przez pozostałą część jego cyklu życia.

System może zmienić odcień ikony i tła kafelka, aby odzwierciedlić stan obiektu Tile. Obiekty Tile ustawione na STATE_ACTIVE są najciemniejsze, a STATE_INACTIVE i STATE_UNAVAILABLE są coraz jaśniejsze. Dokładny odcień zależy od producenta i wersji.

Kafelek VPN jest zabarwiony, aby odzwierciedlać stany obiektów
Rysunek 4. Przykłady kafelka zabarwionego w celu odzwierciedlenia jego stanu (odpowiednio: aktywny, nieaktywny i niedostępny).

Aktualizowanie kafelka

Możesz zaktualizować kafelek, gdy otrzymasz oddzwonienie na numer onStartListening(). W zależności od trybu kafelka może on zostać zaktualizowany co najmniej raz, zanim otrzyma wywołanie zwrotne do onStopListening().

W trybie aktywnym możesz zaktualizować kafelek dokładnie raz, zanim otrzymasz wywołanie zwrotne do onStopListening(). W trybie nieaktywnym możesz aktualizować kafelek dowolną liczbę razy między onStartListening() a onStopListening().

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

Po ustawieniu prawidłowych wartości pól obiektu Tile musisz wywołać metodę updateTile(), aby zaktualizować kafelek. Spowoduje to, że system przeanalizuje zaktualizowane dane kafelka i zaktualizuje interfejs.

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 = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}

Obsługa kliknięć

Użytkownicy mogą kliknąć kafelek, aby wywołać działanie, jeśli kafelek znajduje się w STATE_ACTIVE lub STATE_INACTIVE. System wywołuje wtedy wywołanie zwrotne onClick() aplikacji.

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

var counter = 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()
}

Uruchamianie okna

showDialog() zwija panel Szybkich ustawień i wyświetla okno. Użyj okna, aby dodać kontekst do działania, jeśli wymaga ono dodatkowych danych lub zgody użytkownika.

Uruchamianie aktywności

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

Jeśli aplikacja wymaga znacznej interakcji z użytkownikiem, powinna uruchamiać aktywność tylko w ostateczności. Zamiast tego rozważ użycie okna lub przełącznika.

Długie naciśnięcie kafelka powoduje wyświetlenie ekranu Informacje o aplikacji. Aby zastąpić to zachowanie i zamiast tego uruchomić aktywność związaną z ustawianiem preferencji, dodaj <intent-filter> do jednej ze swoich aktywności za pomocą ACTION_QS_TILE_PREFERENCES.

Począwszy od interfejsu API Androida 28, 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 Activity w pliku AndroidManifest.xml.

Oznaczanie kafelka jako przełączanego

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

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

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

wykonywać tylko bezpieczne działania na bezpiecznie zablokowanych urządzeniach;

Kafelki mogą się wyświetlać na ekranie blokady na zablokowanych urządzeniach. Jeśli kafelek zawiera informacje poufne, sprawdź wartość isSecure(), aby określić, czy urządzenie jest w bezpiecznym stanie, i odpowiednio zmień działanie TileService.

Jeśli działanie kafelka można bezpiecznie wykonać, gdy urządzenie jest zablokowane, użyj startActivity(), aby uruchomić aktywność na ekranie blokady.

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

Kategoryzowanie kafelka

Aby ułatwić użytkownikom korzystanie z Szybkich ustawień, możesz przypisać kafelek do kategorii. System porządkuje kafelki według kategorii, takich jak Łączność, Wyświetlacz i Prywatność. System używa tych kategorii do sortowania i grupowania kafelków w trybie edycji Szybkich ustawień, co ułatwia użytkownikom ich znajdowanie i zarządzanie nimi.

Implementacja

Aby określić kategorię dla TileService, dodaj pole metadanych do deklaracji usługi w pliku AndroidManifest.xml:

  • W pliku AndroidManifest.xml, w elemencie <service> dla TileService, dodaj element <meta-data>.
  • android:name: ustaw tę wartość na android.service.quicksettings.TILE_CATEGORY.
  • android:value: przypisz jedną ze zdefiniowanych stałych kategorii, np. android.service.quicksettings.CATEGORY_CONNECTIVITY lub android.service.quicksettings.CATEGORY_DISPLAY.

Jak widać na tym przykładzie:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

Interfejs API udostępnia zestaw wstępnie zdefiniowanych kategorii do wyboru. Te kategorie są zdefiniowane jako stałe ciągi znaków w klasie TileService.

Jeśli kategoria nie zostanie określona, system automatycznie przypisze kategorię domyślną:

  • Z aplikacji systemowych: w przypadku kart, które są częścią aplikacji systemowej.
  • Z zainstalowanych aplikacji: kafelki z aplikacji zainstalowanych przez użytkownika.

Chociaż urządzenia Google Pixel korzystają z kategorii w Szybkich ustawieniach, producenci OEM mogą używać tych informacji o kategoriach w swoich interfejsach systemowych lub je ignorować.

Zachęcanie użytkownika do dodania kafelka

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

  1. Przesuń palcem w dół, aby otworzyć panel Szybkich ustawień.
  2. Kliknij przycisk edytowania.
  3. przewinąć wszystkie kafelki na urządzeniu, aż znajdzie Twój kafelek;
  4. Przytrzymaj kafelek i przeciągnij go na listę aktywnych kafelków.

Użytkownik może też w każdej chwili 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 Szybkich ustawień. Prośba zawiera nazwę aplikacji, podaną etykietę i ikonę.

Prośba interfejsu Quick Settings Placement API
Rysunek 5. Wyświetla się prośba interfejsu Quick Settings Placement API.
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, czy nie, czy już tam był lub czy wystąpił błąd.

Decydując o tym, kiedy i jak często wyświetlać użytkownikom prośby, kieruj się zdrowym rozsądkiem. Zalecamy wywoływanie metody requestAddTileService() tylko w kontekście, np. gdy użytkownik po raz pierwszy wchodzi w interakcję z funkcją, którą ułatwia Twój kafelek.

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