As Configurações rápidas são blocos exibidos no painel "Configurações rápidas",
representando ações em que os usuários podem tocar para concluir tarefas recorrentes rapidamente.
Seu app pode fornecer um bloco personalizado aos usuários com a classe
TileService
e usar um objeto Tile
para rastrear o estado do bloco. Por exemplo,
você pode criar um bloco que permita aos usuários ativar ou desativar uma VPN fornecida pelo seu app.
![Painel "Configurações rápidas" com o bloco VPN
ativado e desativado](https://developer.android.com/static/develop/ui/views/images/quick-settings-vpn-on-off.png?authuser=5&hl=pt)
Decidir quando criar um bloco
Recomendamos criar blocos para funcionalidades específicas que você espera que os usuários acessem com frequência ou que precisem de acesso rápido (ou ambos). Os blocos mais eficazes são aqueles que correspondem a essas duas qualidades, fornecendo acesso rápido às ações mais realizadas.
Por exemplo, você pode criar um bloco para um app fitness que permita aos usuários iniciar rapidamente uma sessão de treino. No entanto, não recomendamos criar um bloco para o mesmo app, permitindo que os usuários analisem todo o histórico de treino.
![Casos de uso do bloco do app fitness](https://developer.android.com/static/develop/ui/views/images/use-cases-fitness-tiles.png?authuser=5&hl=pt)
Para melhorar a capacidade de descoberta e facilidade de uso do Bloco, recomendamos evitar algumas práticas:
Evite usar blocos para iniciar um app. Use um atalho de apps ou uma tela de início padrão.
Evite usar blocos para ações únicas do usuário. Em vez disso, use um atalho de app ou uma notificação.
Evite criar muitos blocos. Recomendamos no máximo duas por app. Use um atalho de app.
Evite usar blocos que mostram informações, mas não são interativos para os usuários. Em vez disso, use uma notificação ou um widget.
Criar seu bloco
Para criar um bloco, primeiro é necessário criar um ícone de bloco apropriado e, em seguida,
criar e declarar o TileService
no arquivo de manifesto do app.
O exemplo de Configurações rápidas apresenta um exemplo de como criar e gerenciar um bloco.
Crie seu ícone personalizado
Será necessário fornecer um ícone personalizado, que será exibido no bloco do painel "Configurações
rápidas". Esse ícone será adicionado ao declarar o TileService
,
descrito na próxima seção. O ícone precisa ser branco sólido com um
plano de fundo transparente, medir 24 x 24 dp e estar no formato de um
VectorDrawable
.
![Exemplo de um drawable vetorial](https://developer.android.com/static/develop/ui/views/images/vector-drawable.png?authuser=5&hl=pt)
Crie um ícone que indique visualmente a finalidade do bloco. Isso ajuda os usuários a identificar facilmente se o Bloco atende às necessidades deles. Por exemplo, você pode criar um ícone de cronômetro para um bloco de um app fitness que permita aos usuários iniciar uma sessão de treino.
Criar e declarar o TileService
Crie um serviço para o bloco que estenda a classe 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(); } }
Declare o TileService
no arquivo de manifesto do app. Adicione o nome e o rótulo
da TileService
, o ícone personalizado que você criou na seção anterior
e a permissão adequada.
<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>
Gerenciar seu TileService
Depois de criar e declarar o TileService
no manifesto do app, é
necessário gerenciar o estado dele.
TileService
é um serviço vinculado. A TileService
será vinculada quando
solicitada pelo app ou se o sistema precisar se comunicar com ela. Um
ciclo de vida de serviço vinculado típico contém os quatro métodos de callback a seguir:
onCreate()
, onBind()
, onUnbind()
e
onDestroy()
. Esses métodos são invocados pelo sistema sempre que o
serviço entra em uma nova fase do ciclo de vida.
Visão geral do ciclo de vida do TileService
Além dos callbacks que controlam o ciclo de vida do serviço vinculado, é necessário
implementar outros métodos específicos para o ciclo de vida da TileService
. Esses métodos
podem ser chamados fora de onCreate()
e onDestroy()
porque os métodos de ciclo de vida Service
e TileService
são chamados em duas
linhas de execução assíncronas separadas.
O ciclo de vida da TileService
contém os seguintes métodos, que são invocados
pelo sistema sempre que a TileService
entra em uma nova fase do ciclo de vida:
onTileAdded()
: esse método é chamado somente quando o usuário adiciona o bloco pela primeira vez e quando ele é removido e adicionado novamente. Esse é o melhor momento para fazer qualquer inicialização única. No entanto, isso pode não atender a toda a inicialização necessária.onStartListening()
eonStopListening()
: esses métodos são chamados sempre que o app atualiza o bloco e são chamados com frequência. OTileService
permanece vinculado entreonStartListening()
eonStopListening()
, permitindo que o app modifique o bloco e envie atualizações.onTileRemoved()
: esse método será chamado somente se o usuário remover o bloco.
Selecione um modo de escuta
Seu TileService
detecta no modo ativo ou não ativo. Recomendamos
o uso do modo ativo, que você vai precisar declarar no manifesto do app. Caso contrário,
o TileService
será o modo padrão e não precisará ser declarado.
Não presuma que o TileService
vai ficar fora do par de métodos
onStartListening()
e onStopListening()
.
Modo ativo (recomendado)
Use o modo ativo para uma TileService
que detecta e monitora o estado no
próprio processo. Um TileService
no modo ativo está vinculado a eventos onTileAdded()
,
onTileRemoved()
, toque e quando solicitado pelo processo do app.
Recomendamos o modo ativo se a TileService
for notificada quando o estado do bloco
for atualizado pelo próprio processo. Os blocos ativos limitam a pressão no
sistema porque eles não precisam ser vinculados toda vez que o painel "Configurações rápidas"
fica visível para o usuário.
O método estático TileService.requestListeningState()
pode ser chamado para
solicitar o início do estado de detecção e receber um callback para
onStartListening()
.
Para declarar o modo ativo, adicione META_DATA_ACTIVE_TILE
ao
arquivo de manifesto do app.
<service ...>
<meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
android:value="true" />
...
</service>
Modo não ativo
O modo não ativo é o modo padrão. Um TileService
fica no modo não ativo se
está vinculado sempre que o Bloco estiver visível para o usuário. Isso significa que
TileService
pode ser criado e vinculado novamente às vezes além do controle dele. Ele
também pode ser desvinculado e destruído quando o usuário não estiver visualizando o bloco.
Seu app recebe um callback para onStartListening()
depois que o usuário abre o
painel "Configurações rápidas". É possível atualizar o objeto Tile
quantas vezes
você quiser entre onStartListening()
e onStopListening()
.
Não é necessário declarar o modo não ativo. Basta não adicionar o
META_DATA_ACTIVE_TILE
ao arquivo de manifesto do app.
Visão geral dos estados de bloco
Depois que um usuário adiciona seu bloco, ele sempre existe em um dos seguintes estados.
STATE_ACTIVE
: indica o estado ativado ou ativado. O usuário pode interagir com o Bloco nesse estado.Por exemplo, em um bloco de um app fitness que permite aos usuários iniciar uma sessão de treino cronometrada,
STATE_ACTIVE
significa que o usuário iniciou uma sessão de treino e que o timer está em execução.STATE_INACTIVE
: indica um estado desativado ou pausado. O usuário pode interagir com o Bloco nesse estado.Para usar o exemplo do bloco do app fitness novamente, um bloco em
STATE_INACTIVE
significa que o usuário não iniciou uma sessão de treino, mas pode fazer isso se quisesse.STATE_UNAVAILABLE
: indica um estado temporariamente indisponível. O usuário não pode interagir com o bloco nesse estado.Por exemplo, um bloco em
STATE_UNAVAILABLE
significa que ele não está disponível no momento para o usuário por algum motivo.
O sistema define apenas o estado inicial do objeto Tile
. O estado do objeto Tile
é definido por todo o restante do ciclo de vida.
O sistema pode colorir o ícone do bloco e o plano de fundo para refletir o estado do
objeto Tile
. Os objetos Tile
definidos como STATE_ACTIVE
são os mais escuros, com
STATE_INACTIVE
e STATE_UNAVAILABLE
cada vez mais claros. A tonalidade exata
é específica para o fabricante e a versão.
![Bloco de VPN colorido para refletir os estados dos objetos](https://developer.android.com/static/develop/ui/views/images/state-hues.png?authuser=5&hl=pt)
Atualizar seu bloco
É possível atualizar o Bloco assim que você receber um callback para onStartListening()
.
Dependendo do modo, ele pode ser atualizado pelo menos uma vez até
que você receba um callback para onStopListening()
.
No modo ativo, você pode atualizar o Bloco exatamente uma vez antes de receber um
callback para onStopListening()
. No modo inativo, você pode atualizar o bloco quantas
vezes quiser entre onStartListening()
e onStopListening()
.
Para recuperar o objeto Tile
, chame getQsTile()
. Para atualizar
campos específicos do objeto Tile
, chame estes métodos:
Você precisa chamar updateTile()
para atualizar o Bloco depois de definir os
campos do objeto Tile
com os valores corretos. Isso vai fazer o sistema
analisar os dados de blocos atualizados e atualizar a interface.
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(); }
Processar toques
Os usuários podem tocar no bloco para acionar uma ação se ele estiver em
STATE_ACTIVE
ou STATE_INACTIVE
. Em seguida, o sistema invoca o callback
onClick()
do app.
Quando o app recebe um callback para onClick()
, ele pode iniciar uma caixa de diálogo ou
atividade, acionar trabalhos em segundo plano ou mudar o estado do bloco.
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(); }
Abrir uma caixa de diálogo
O showDialog()
fecha o painel "Configurações rápidas" e mostra uma caixa de diálogo.
Use uma caixa de diálogo para adicionar contexto à sua ação se ela exigir mais entrada ou consentimento do usuário.
Iniciar uma atividade
startActivityAndCollapse()
inicia uma atividade ao recolher o
painel. As atividades são úteis quando há informações mais detalhadas para mostrar
do que em uma caixa de diálogo ou quando a ação é altamente interativa.
Se o app exigir uma interação significativa do usuário, ele precisará iniciar uma atividade apenas como último recurso. Em vez disso, use uma caixa de diálogo ou um botão de ativação.
Quando o usuário toca e mantém pressionado um bloco, a tela Informações do app é exibida. Para substituir
esse comportamento e iniciar uma atividade para definir preferências, adicione um
<intent-filter>
a uma das atividades com
ACTION_QS_TILE_PREFERENCES
.
A partir do nível 28 da API do Android, o PendingIntent
precisa
ter o Intent.FLAG_ACTIVITY_NEW_TASK
:
if (Build.VERSION.SDK_INT >= 28) {
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}
Como alternativa, é possível adicionar a sinalização em AndroidManifest.xml
na seção Activity
específica.
Marcar seu bloco como alternável
Recomendamos marcar o bloco como alternável se ele funcionar principalmente como uma chave de dois estados, que é o comportamento mais comum dos blocos. Isso ajuda a fornecer informações sobre o comportamento do bloco ao sistema operacional e melhorar a acessibilidade geral.
Defina os metadados TOGGLEABLE_TILE
como true
para marcar o Bloco como alternável.
<service ...>
<meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
android:value="true" />
</service>
Executar apenas ações seguras em dispositivos bloqueados com segurança
Seu bloco pode aparecer na parte de cima da tela de bloqueio em dispositivos bloqueados. Se o bloco
contiver informações sensíveis, confira o valor de isSecure()
para
determinar se o dispositivo está em um estado seguro e se o TileService
precisa
mudar o comportamento de acordo.
Se for seguro realizar a ação do bloco enquanto ela estiver bloqueada, use startActivity()
para iniciar uma atividade na tela de bloqueio.
Se a ação do bloco não for segura, use unlockAndRun()
para solicitar que o usuário
desbloqueie o dispositivo. Se bem-sucedido, o sistema executa o objeto
Runnable
que você transmite a esse
método.
Pedir que o usuário adicione seu bloco
Para adicionar seu bloco manualmente, os usuários precisam seguir várias etapas:
- Deslize para baixo para abrir o painel "Configurações rápidas".
- Toque no botão de edição.
- Percorra todos os blocos no dispositivo até localizar o bloco.
- Mantenha seu bloco pressionado e arraste-o para a lista de blocos ativos.
O usuário também pode mover ou remover seu bloco a qualquer momento.
No Android 13 e versões mais recentes, é possível usar o método requestAddTileService()
para facilitar a adição do Bloco a um dispositivo. Esse método
envia aos usuários uma solicitação para adicionar rapidamente seu bloco diretamente ao painel "Configurações
rápidas". O comando inclui o nome do aplicativo, o rótulo fornecido
e o ícone.
![Solicitação da API Quick Settings Placement](https://developer.android.com/static/develop/ui/views/images/placement-api-user-prompt.png?authuser=5&hl=pt)
public void requestAddTileService (
ComponentName tileServiceComponentName,
CharSequence tileLabel,
Icon icon,
Executor resultExecutor,
Consumer<Integer> resultCallback
)
O callback contém informações sobre se o bloco foi adicionado, não adicionado, se ele já estava lá ou se ocorreu algum erro.
Tenha critério ao decidir quando e com que frequência enviar solicitações aos usuários. Recomendamos
chamar requestAddTileService()
apenas no contexto, como
quando o usuário interage pela primeira vez com um recurso facilitado pelo seu Bloco.
O sistema pode optar por interromper o processamento de solicitações para um determinado
ComponentName
se ele tiver sido negado pelo usuário muitas vezes. O
usuário é determinado pelo Context
usado para recuperar esse
serviço. Ele precisa corresponder ao usuário atual.