Ta strona została przetłumaczona przez Cloud Translation API.

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 udostępniać użytkownikom niestandardowy kafelek za pomocą TileService i użyj obiektu Tile do śledzenia stanu kafelka. 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ę.

Panel Szybkie ustawienia z włączonym i wyłączonym kafelkiem VPN — **Rysunek 1.** Panel Szybkie ustawienia z włączonym kafelkiem VPN włącz i wyłącz.

Zdecyduj, 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 rzeczy). 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.

Przypadki użycia kafelka aplikacji Fitness — **Rysunek 2.** Przykłady kafelków zalecanych i niezalecanych w przypadku aplikacji do fitnessu.

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 kafelków do jednorazowych działań użytkownika. Zamiast tego użyj skrótu aplikacji lub powiadomienia.
Unikaj tworzenia zbyt wielu kafelków. Zalecamy ustawienie maksymalnie 2 na aplikację. Użyj skrót do 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.

Utwórz kafelek

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

Przykład Szybkich ustawień zawiera przykład tworzenia i zarządzać kafelkiem.

Utwórz ikonę niestandardową

Musisz przesłać niestandardową ikonę, która będzie widoczna na kafelku w panelu Szybkie ustawienia. (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

Przykład obiektu rysowanego wektorowo — **Rysunek 3.** Przykład rysowanego wektora.

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

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

Zadeklaruj uprawnienia 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 to powiązana usługa. TileService jest związany, gdy aplikacja o to poprosi lub gdy system musi się z nim 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 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 zaimplementuj inne metody właściwe dla cyklu ż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 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.

Uwaga: funkcja onTileAdded() nie jest wywoływana podczas tworzenia kafelka. Dla: na przykład funkcja onTileAdded() nie jest wywoływana po ponownym uruchomieniu urządzenia lub będzie włączony, jeśli kafelek został dodany, a nie usunięty, zanim urządzenie jest wyłączona.
onStartListening() i onStopListening(): te metody są wywoływane często, gdy aplikacja aktualizuje kafelek. 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 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. 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 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, gdy użytkownik zobaczy 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 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 jest powiązany z każdym widocznym dla użytkownika kafelkiem. Oznacza to, że konto TileService może zostać utworzone i ponownie powiązane w czasie, na który nie ma wpływu. 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 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 kafelków

Gdy użytkownik doda Twój kafelek, zawsze będzie on istniał w jednym z poniższych 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 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 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: oznacza 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.

Uwaga: w przypadku kafelków, które są obecnie niedostępne, ale mogą być później dostępne, użyj wartości STATE_UNAVAILABLE. Jeśli komponent nigdy być ponownie dostępne dla użytkownika, muszą być dostępne przez COMPONENT_ENABLED_STATE_DISABLED w setComponentEnabledSetting().

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ę i tło kafelka, aby odzwierciedlić stan obiektu Tile. 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.

Płytka VPN z kolorem wskazującym stan obiektu — **Rysunek 4.** Przykłady kafelków z kolorem odpowiadającym ich stanowi (odpowiednio aktywny, nieaktywny i niedostępny).

Aktualizowanie kafelka

Możesz zaktualizować swój kafelek, gdy ktoś do Ciebie oddzwoni. 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 zaktualizować kafelek jako tyle razy, ile chcesz, od onStartListening() do onStopListening().

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

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

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

Dotknij uchwytu

Użytkownicy mogą kliknąć Twój kafelek, aby wywołać działanie, jeśli jest on w 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 otworzyć okno lub aktywności, aktywuj działanie w tle lub zmień stan kafelka.

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

Otwórz okno

showDialog() zwija panel Szybkie ustawienia i wyświetla okno. Jeśli wymagane jest dodatkowe dane wejściowe, 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 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 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

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 AndroidManifest.xml w konkretnym 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ść.

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>

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

Na zablokowanych urządzeniach kafelek może być widoczny na górze 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 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 .

Prośba o dodanie kafelka

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

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

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

Począwszy 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ę.

Prompt interfejsu Quick Settings Places API — **Rysunek 5.** Prompt interfejsu Placement API w Szybkich ustawieniach

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.

Decydując, kiedy i jak często wyświetlać użytkownikom prompty, kieruj się zdrowym rozsądkiem. Ś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 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.