Создайте собственные плитки быстрых настроек для своего приложения.

Быстрые настройки — это плитки, отображаемые на панели быстрых настроек и представляющие действия, которые пользователи могут нажимать для быстрого выполнения повторяющихся задач. Ваше приложение может предоставить пользователям собственную плитку через класс TileService и использовать объект Tile для отслеживания её состояния. Например, вы можете создать плитку, которая позволит пользователям включать и выключать VPN, предоставляемый вашим приложением.

Решите, когда создавать плитку

Мы рекомендуем создавать плитки для определённых функций, к которым пользователи будут обращаться часто или к которым им нужен быстрый доступ (или и то, и другое). Наиболее эффективны плитки, которые сочетают в себе оба этих качества, обеспечивая быстрый доступ к часто выполняемым действиям.

Например, вы можете создать плитку для фитнес-приложения, которая позволит пользователям быстро начать тренировку. Однако мы не рекомендуем создавать плитку для того же приложения, которая позволит пользователям просматривать всю историю своих тренировок.

Чтобы улучшить заметность вашей плитки и сделать ее использование более простым, мы рекомендуем избегать определенных практик:

• Избегайте использования плиток для запуска приложений. Вместо этого используйте ярлык приложения или стандартный лаунчер.

• Избегайте использования плиток для одноразовых действий пользователя. Вместо этого используйте ярлык приложения или уведомление .

• Не создавайте слишком много плиток. Мы рекомендуем не более двух на приложение. Вместо этого используйте ярлык приложения.

• Избегайте использования плиток, которые отображают информацию, но не являются интерактивными для пользователей. Вместо этого используйте уведомления или виджеты .

Создайте свою плитку

Чтобы создать плитку, вам необходимо сначала создать соответствующий значок плитки, а затем создать и объявить TileService в файле манифеста вашего приложения.

Пример быстрых настроек демонстрирует, как создавать и управлять плиткой.

Создайте свой собственный значок

Вам потребуется предоставить пользовательский значок, который будет отображаться на плитке на панели быстрых настроек. (Вы добавите этот значок при объявлении TileService , как описано в следующем разделе.) Значок должен быть сплошным белым с прозрачным фоном, иметь размеры 24 x 24dp и иметь форму VectorDrawable .

Создайте значок, который визуально подскажет назначение вашей плитки. Это поможет пользователям легко определить, соответствует ли ваша плитка их потребностям. Например, вы можете создать значок секундомера для плитки фитнес-приложения, позволяющего пользователям начать тренировку.

Создайте и объявите свой TileService

Создайте службу для вашей плитки, которая расширяет класс 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();
  }
}

Объявите TileService в файле манифеста вашего приложения. Добавьте имя и метку TileService , значок, созданный в предыдущем разделе, и соответствующее разрешение.

 <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

После того как вы создали и объявили TileService в манифесте приложения, вам необходимо управлять его состоянием.

TileService — это привязанная служба . Ваша TileService привязывается по запросу вашего приложения или при необходимости взаимодействия с ней системы. Типичный жизненный цикл привязанной службы содержит следующие четыре метода обратного вызова: onCreate() , onBind() , onUnbind() и onDestroy() . Эти методы вызываются системой каждый раз, когда служба переходит в новую фазу жизненного цикла.

Обзор жизненного цикла TileService

Помимо обратных вызовов, управляющих жизненным циклом привязанной службы, необходимо реализовать другие методы, специфичные для жизненного цикла TileService . Эти методы могут вызываться вне onCreate() и onDestroy() поскольку методы жизненного цикла Service и методы жизненного цикла TileService вызываются в двух отдельных асинхронных потоках.

Жизненный цикл TileService содержит следующие методы, которые вызываются системой каждый раз, когда ваш TileService переходит в новую фазу жизненного цикла:

• onTileAdded() : этот метод вызывается только при первом добавлении плитки пользователем, а также при удалении и повторном добавлении плитки. Это лучший момент для однократной инициализации. Однако этого может быть недостаточно для выполнения всех необходимых действий.

• onStartListening() и onStopListening() : эти методы вызываются каждый раз, когда ваше приложение обновляет плитку, и делают это часто. TileService остаётся связанным между onStartListening() и onStopListening() , позволяя вашему приложению изменять плитку и отправлять обновления.

• onTileRemoved() : этот метод вызывается только если пользователь удаляет вашу плитку.

Выберите режим прослушивания

Ваш TileService может прослушивать события в активном или неактивном режиме. Мы рекомендуем использовать активный режим, который необходимо указать в манифесте приложения. В противном случае TileService будет работать в стандартном режиме и не требует указания.

Не думайте, что ваш TileService будет существовать за пределами пары методов onStartListening() и onStopListening() .

Активный режим (рекомендуется)

Используйте активный режим для TileService , который прослушивает и отслеживает своё состояние в своём собственном процессе. TileService в активном режиме привязан к onTileAdded() , onTileRemoved() , событиям касания и событиям, запрошенным процессом приложения.

Мы рекомендуем активный режим, если ваш TileService получает уведомления о необходимости обновления состояния плиток собственным процессом. Активные плитки снижают нагрузку на систему, поскольку их не нужно привязывать каждый раз, когда панель быстрых настроек становится видимой для пользователя.

Статический метод TileService.requestListeningState() можно вызвать для запроса начала состояния прослушивания и получения обратного вызова onStartListening() .

Вы можете объявить активный режим, добавив META_DATA_ACTIVE_TILE в файл манифеста вашего приложения.

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

Неактивный режим

Неактивный режим — это стандартный режим. TileService находится в неактивном режиме, если он привязан, когда плитка видна пользователю. Это означает, что TileService может быть создан и привязан снова в неконтролируемые им моменты. Он также может быть отвязан и уничтожен, когда пользователь не просматривает плитку.

Ваше приложение получает обратный вызов onStartListening() после того, как пользователь открывает панель быстрых настроек. Вы можете обновлять объект Tile неограниченное количество раз между onStartListening() и onStopListening() .

Вам не нужно объявлять неактивный режим — просто не добавляйте META_DATA_ACTIVE_TILE в файл манифеста вашего приложения.

Обзор состояний плитки

После того, как пользователь добавит вашу плитку, она всегда будет находиться в одном из следующих состояний.

• STATE_ACTIVE : Указывает на включенное или активное состояние. В этом состоянии пользователь может взаимодействовать с плиткой.

  Например, для плитки фитнес-приложения, позволяющей пользователям инициировать сеанс тренировки с заданным временем, STATE_ACTIVE будет означать, что пользователь инициировал сеанс тренировки и таймер запущен.

• STATE_INACTIVE : Указывает на выключенное или приостановленное состояние. В этом состоянии пользователь может взаимодействовать с плиткой.

  Если снова использовать пример с плиткой фитнес-приложения, плитка в STATE_INACTIVE будет означать, что пользователь не начал сеанс тренировки, но может сделать это, если захочет.

• STATE_UNAVAILABLE : Указывает на временно недоступное состояние. В этом состоянии пользователь не может взаимодействовать с плиткой.

  Например, плитка в STATE_UNAVAILABLE означает, что по какой-то причине плитка в данный момент недоступна пользователю.

Система устанавливает только начальное состояние объекта Tile . Вы сами определяете состояние объекта Tile на протяжении всего его жизненного цикла.

Система может изменять оттенок значка и фона плитки, отражая состояние объекта Tile . Объекты Tile в состоянии STATE_ACTIVE имеют самый тёмный оттенок, а в состоянии STATE_INACTIVE и STATE_UNAVAILABLE — более светлый. Точный оттенок зависит от производителя и версии.

Обновите свою плитку

Вы можете обновить плитку после получения обратного вызова onStartListening() . В зависимости от режима плитки, она может обновиться как минимум один раз до получения обратного вызова onStopListening() .

В активном режиме вы можете обновить плитку ровно один раз, прежде чем получите обратный вызов onStopListening() . В неактивном режиме вы можете обновить плитку столько раз, сколько захотите, между onStartListening() и onStopListening() .

Вы можете получить объект Tile , вызвав getQsTile() . Чтобы обновить определённые поля объекта Tile , вызовите следующие методы:

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

После установки правильных значений полей объекта Tile необходимо вызвать updateTile() для обновления плитки. Это позволит системе проанализировать обновлённые данные плитки и обновить пользовательский интерфейс.

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

Ручки кранов

Пользователи могут нажать на вашу плитку, чтобы активировать действие, если она находится в состоянии STATE_ACTIVE или STATE_INACTIVE . После этого система вызовет обратный вызов onClick() вашего приложения.

Как только ваше приложение получает обратный вызов onClick() , оно может запустить диалог или действие, запустить фоновую работу или изменить состояние вашей плитки.

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

Начать диалог

showDialog() сворачивает панель быстрых настроек и отображает диалоговое окно. Используйте диалоговое окно, чтобы добавить контекст к действию, если оно требует дополнительных данных или согласия пользователя.

Запустить деятельность

startActivityAndCollapse() запускает действие, одновременно сворачивая панель. Действие полезно, если требуется отобразить более подробную информацию, чем в диалоговом окне, или если действие требует высокой интерактивности.

Если ваше приложение требует значительного взаимодействия с пользователем, запуск активности должен осуществляться только в крайнем случае. Вместо этого рассмотрите возможность использования диалогового окна или переключателя.

Длительное нажатие на плитку открывает экран «Информация о приложении» . Чтобы переопределить это поведение и вместо этого запустить действие для настройки настроек, добавьте <intent-filter> к одному из действий с ACTION_QS_TILE_PREFERENCES .

Начиная с Android API 28, PendingIntent должен иметь Intent.FLAG_ACTIVITY_NEW_TASK :

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

В качестве альтернативы вы можете добавить флаг в AndroidManifest.xml в разделе « Activity .

Отметьте свою плитку как переключаемую

Мы рекомендуем отметить плитку как переключаемую, если она выполняет функцию переключателя с двумя состояниями (что является наиболее распространённым поведением плиток). Это поможет предоставить операционной системе информацию о её поведении и улучшить общую доступность.

Установите для метаданных TOGGLEABLE_TILE значение true , чтобы отметить плитку как переключаемую.

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

Выполняйте только безопасные действия на надежно заблокированных устройствах.

Ваша плитка может отображаться поверх экрана блокировки на заблокированных устройствах. Если плитка содержит конфиденциальную информацию, проверьте значение isSecure() чтобы определить, находится ли устройство в защищенном состоянии, и ваш TileService должен изменить своё поведение соответствующим образом.

Если действие с плиткой безопасно выполнять на заблокированном экране, используйте startActivity() для запуска действия поверх экрана блокировки.

Если действие с плиткой небезопасно, используйте unlockAndRun() чтобы предложить пользователю разблокировать устройство. В случае успеха система выполняет объект Runnable , переданный в этот метод.

Предложите пользователю добавить вашу плитку

Чтобы вручную добавить плитку, пользователям необходимо выполнить несколько шагов:

1. Проведите пальцем вниз, чтобы открыть панель быстрых настроек.
2. Нажмите кнопку «Изменить».
3. Прокручивайте все плитки на своем устройстве, пока не найдете вашу плитку.
4. Удерживайте плитку и перетащите ее в список активных плиток.

Пользователь также может в любой момент переместить или удалить вашу плитку.

Начиная с Android 13, вы можете использовать метод requestAddTileService() , чтобы значительно упростить пользователям добавление плитки на устройство. Этот метод предлагает пользователям быстро добавить плитку непосредственно на панель быстрых настроек. Запрос включает название приложения, предоставленную метку и значок.

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

Обратный вызов содержит информацию о том, была ли плитка добавлена, не добавлена, была ли она уже там или произошла какая-либо ошибка.

Решайте по своему усмотрению, когда и как часто запрашивать информацию у пользователей. Мы рекомендуем вызывать requestAddTileService() только в контексте, например, когда пользователь впервые взаимодействует с функцией, которую поддерживает ваша плитка.

Система может прекратить обработку запросов на указанный ComponentName , если пользователь уже отклонил запрос достаточное количество раз. Пользователь определяется по Context используемому для получения этой услуги, — он должен соответствовать текущему пользователю.