Os atalhos mostram tipos específicos de conteúdo para os usuários, ajudando-os a acessar rapidamente partes do app.
![Uma imagem mostrando a diferença entre os atalhos de apps e os atalhos fixados](https://developer.android.com/static/images/guide/topics/ui/shortcuts/pinned-shortcuts.png?authuser=6&hl=pt)
A forma como você envia conteúdo com atalhos depende do seu caso de uso e se o contexto do atalho é orientado pelo app ou pelo usuário. Embora o contexto de um atalho estático não mude e o contexto de um atalho dinâmico mude constantemente, seu app orienta o contexto nos dois casos. Nos casos em que um usuário escolhe como seu app entrega conteúdo, como com um atalho fixado, o contexto é definido pelo usuário. Os cenários abaixo descrevem alguns casos de uso para cada tipo de atalho:
- Atalhos estáticos são melhores para apps que vinculam conteúdo usando uma estrutura consistente durante todo o ciclo de vida da interação do usuário com o app. Como a maioria das telas de início mostra apenas quatro atalhos por vez, os atalhos estáticos são úteis para realizar uma tarefa rotineira de maneira consistente, por exemplo, quando o usuário quer conferir a agenda ou o e-mail de uma forma específica .
- Atalhos dinâmicos são usados para ações em apps sensíveis ao contexto. Os atalhos sensíveis ao contexto são personalizados para as ações que os usuários realizam no app. Por exemplo, se você criar um jogo que permite que o usuário comece do nível atual na inicialização, é necessário atualizar o atalho com frequência. O uso de um atalho dinâmico permite que você o atualize sempre que o usuário terminar uma fase.
- Os atalhos fixados são usados para ações específicas do usuário. Por exemplo, um usuário pode querer fixar um site específico na tela de início. Isso é útil porque permite que o usuário realize uma ação personalizada, como navegar até o site em uma etapa, mais rapidamente do que usar uma instância padrão de um navegador.
Criar atalhos estáticos
Os atalhos estáticos oferecem links para ações genéricas no seu app. Essas ações precisam permanecer consistentes durante o ciclo de vida da versão atual do app. Boas opções para atalhos estáticos incluem visualizar mensagens enviadas, definir um alarme e exibir a atividade física do usuário para o dia.
Para criar um atalho estático, faça o seguinte:
-
No arquivo
AndroidManifest.xml
do app, encontre a atividade com filtros de intent definidos para a açãoandroid.intent.action.MAIN
e a categoriaandroid.intent.category.LAUNCHER
. -
Adicione um elemento
<meta-data>
a essa atividade que faça referência ao arquivo de recursos em que os atalhos do app estão definidos:<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.myapplication"> <application ... > <activity android:name="Main"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> <meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" /> </activity> </application> </manifest>
-
Crie um novo arquivo de recursos com o nome
res/xml/shortcuts.xml
. -
No novo arquivo de recursos, adicione um elemento raiz
<shortcuts>
que contenha uma lista de elementos<shortcut>
. Em cada elemento<shortcut>
, inclua informações sobre um atalho estático, incluindo o ícone, as etiquetas de descrição e as intents que ele inicia no app:<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <shortcut android:shortcutId="compose" android:enabled="true" android:icon="@drawable/compose_icon" android:shortcutShortLabel="@string/compose_shortcut_short_label1" android:shortcutLongLabel="@string/compose_shortcut_long_label1" android:shortcutDisabledMessage="@string/compose_disabled_message1"> <intent android:action="android.intent.action.VIEW" android:targetPackage="com.example.myapplication" android:targetClass="com.example.myapplication.ComposeActivity" /> <!-- If your shortcut is associated with multiple intents, include them here. The last intent in the list determines what the user sees when they launch this shortcut. --> <categories android:name="android.shortcut.conversation" /> <capability-binding android:key="actions.intent.CREATE_MESSAGE" /> </shortcut> <!-- Specify more shortcuts here. --> </shortcuts>
Personalizar valores de atributos
A lista a seguir inclui descrições para os diferentes atributos em
um atalho estático. Forneça um valor para android:shortcutId
e
android:shortcutShortLabel
. Todos os outros valores são opcionais.
-
android:shortcutId
-
Um literal de string que representa o atalho quando um objeto
ShortcutManager
executa operações nele. -
android:shortcutShortLabel
-
Uma frase concisa que descreve a finalidade do atalho. Quando possível, limite essa descrição breve a 10 caracteres.
Para saber mais, consulte
setShortLabel()
. -
android:shortcutLongLabel
-
Uma frase estendida que descreve a finalidade do atalho. Se houver espaço suficiente, a tela de início exibirá esse valor em vez de
android:shortcutShortLabel
. Quando possível, limite essa descrição longa a 25 caracteres.Para saber mais, consulte
setLongLabel()
. -
android:shortcutDisabledMessage
-
Mensagem que aparece em uma tela de início compatível quando o usuário tenta iniciar um atalho desativado. A mensagem precisa explicar ao usuário por que o atalho está desativado. O valor desse atributo não terá efeito se
android:enabled
fortrue
. -
android:enabled
-
Determina se o usuário pode interagir com o atalho em uma tela de início compatível. O valor padrão de
android:enabled
étrue
. Se você defini-lo comofalse
, defina umandroid:shortcutDisabledMessage
que explique por que você está desativando o atalho. Se você acha que não precisa enviar essa mensagem, remova totalmente o atalho do arquivo XML. -
android:icon
-
O bitmap ou ícone adaptativo que a tela de início usa ao mostrar o atalho para o usuário. Esse valor pode ser o caminho para uma imagem ou o arquivo de recursos que contém a imagem. Use ícones adaptativos sempre que possível para melhorar o desempenho e a consistência.
Configurar elementos internos
O arquivo XML que lista os atalhos estáticos de um app oferece suporte aos seguintes
elementos dentro de cada elemento <shortcut>
. É
necessário incluir um elemento interno intent
para cada
atalho estático definido.
-
intent
-
A ação iniciada pelo sistema quando o usuário seleciona o atalho. Essa intent precisa fornecer um valor para o atributo
android:action
.É possível fornecer várias intents para um único atalho. Consulte Gerenciar várias intents e atividades, Definir uma intent e a referência de classe
TaskStackBuilder
para saber mais. -
categories
-
Oferece um agrupamento dos tipos de ações realizadas pelos atalhos do seu app, como a criação de novas mensagens de chat.
Para ver uma lista de categorias de atalhos compatíveis, consulte a referência de classe
ShortcutInfo
. -
capability-binding
-
Declara o recurso vinculado ao atalho.
No exemplo anterior, o atalho está vinculado a um recurso declarado para
CREATE_MESSAGE
, que é uma intent integrada das Ações no app. Essa vinculação de capability permite que os usuários usem comandos falados com o Google Assistente para invocar um atalho.
Criar atalhos dinâmicos
Os atalhos dinâmicos oferecem links para ações específicas e contextuais no seu app. Essas ações podem mudar entre o uso do app e enquanto ele está em execução. Os atalhos dinâmicos podem ser usados para chamar uma pessoa específica, navegar até um local específico e carregar um jogo a partir do último ponto salvo do usuário. Você também pode usar atalhos dinâmicos para abrir uma conversa.
A biblioteca
ShortcutManagerCompat
do Jetpack é um auxiliar da API
ShortcutManager
, que permite gerenciar atalhos dinâmicos no seu app. O uso da
biblioteca ShortcutManagerCompat
reduz o código boilerplate e ajuda
a garantir que os atalhos funcionem de forma consistente nas versões do Android. Essa
biblioteca também é necessária para enviar atalhos dinâmicos para que eles possam
aparecer nas plataformas do Google, como o Google Assistente, com a
Biblioteca de integração Google Shortcuts.
A API ShortcutManagerCompat
permite que o app execute as seguintes
operações com atalhos dinâmicos:
-
Enviar e atualizar: use o
pushDynamicShortcut()
para publicar e atualizar seus atalhos dinâmicos. Se já houver atalhos dinâmicos ou fixados com o mesmo ID, todos os atalhos mutáveis serão atualizados. -
Remover:remova um conjunto de atalhos dinâmicos usando
removeDynamicShortcuts()
. Remova todos os atalhos dinâmicos usandoremoveAllDynamicShortcuts()
.
Para mais informações sobre como executar operações em atalhos, consulte
Gerenciar atalhos
e a
referência
ShortcutManagerCompat
.
Confira um exemplo de como criar um atalho dinâmico e associá-lo ao app:
Kotlin
val shortcut = ShortcutInfoCompat.Builder(context, "id1") .setShortLabel("Website") .setLongLabel("Open the website") .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website)) .setIntent(Intent(Intent.ACTION_VIEW, Uri.parse("https://www.mysite.example.com/"))) .build() ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)
Java
ShortcutInfoCompat shortcut = new ShortcutInfoCompat.Builder(context, "id1") .setShortLabel("Website") .setLongLabel("Open the website") .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website)) .setIntent(new Intent(Intent.ACTION_VIEW, Uri.parse("https://www.mysite.example.com/"))) .build(); ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);
Adicionar a biblioteca de integração do Google Shortcuts
A biblioteca de integração do Google Shortcuts é uma biblioteca opcional do Jetpack. Ele permite enviar atalhos dinâmicos que podem ser mostrados nas plataformas do Android, como a tela de início, e nas plataformas do Google, como o Google Assistente. O uso dessa biblioteca ajuda os usuários a descobrir seus atalhos para acessar rapidamente conteúdo específico ou repetir ações no app.
Por exemplo, um app de mensagens pode enviar um atalho dinâmico para um contato chamado "Alex" depois que um usuário enviar uma mensagem para essa pessoa. Depois que o atalho dinâmico for enviado, se o usuário perguntar ao Google Assistente "Ok Google, envie uma mensagem para o Alex no ExampleApp", o Google Assistente poderá iniciar o ExampleApp e configurá-lo automaticamente para enviar uma mensagem para Alex.
Os atalhos dinâmicos enviados com essa biblioteca não estão sujeitos aos limites de atalhos aplicados por dispositivo. Isso permite que o app envie um atalho sempre que um usuário concluir uma ação associada no app. Enviar atalhos frequentes dessa forma permite que o Google entenda os padrões de uso do usuário e sugira atalhos contexto relevantes para ele.
Por exemplo, ele pode aprender com atalhos enviados pelo app de monitoramento de condicionamento físico que um usuário normalmente executa todas as manhãs e sugerir proativamente um atalho "iniciar uma corrida" quando o usuário pegar o smartphone de manhã.
A biblioteca de integração Google Shortcuts não oferece nenhuma funcionalidade
endereçável. A adição dessa biblioteca ao app permite que as plataformas do Google usem
os atalhos que o app envia usando ShortcutManagerCompat
.
Para usar essa biblioteca no seu app, siga estas etapas:
-
Atualize o arquivo
gradle.properties
para oferecer compatibilidade com as bibliotecas AndroidX:android.useAndroidX=true # Automatically convert third-party libraries to use AndroidX android.enableJetifier=true
-
Em
app/build.gradle
, adicione dependências para a Biblioteca de integração Google Shortcuts eShortcutManagerCompat
:dependencies { implementation "androidx.core:core:1.6.0" implementation 'androidx.core:core-google-shortcuts:1.0.0' ... }
Com as dependências de biblioteca adicionadas ao projeto Android, o app pode usar
o método pushDynamicShortcut()
de
ShortcutManagerCompat
para enviar atalhos dinâmicos qualificados
para exibição na tela de início e nas plataformas do Google participantes.
Criar atalhos fixados
No Android 8.0 (nível 26 da API) ou versões posteriores, é possível criar atalhos fixados. Ao contrário dos atalhos estáticos e dinâmicos, os atalhos fixados aparecem nas telas de início compatíveis como ícones separados. A Figura 1 mostra a diferença entre esses dois tipos de atalhos.
Para fixar um atalho em uma tela de início compatível usando seu app, siga estas etapas:
-
Use
isRequestPinShortcutSupported()
para verificar se a tela de início padrão do dispositivo oferece suporte à fixação de atalhos no app. -
Crie um objeto
ShortcutInfo
de uma das duas maneiras, dependendo da existência do atalho:-
Se o atalho existir, crie um objeto
ShortcutInfo
que contenha apenas o ID do atalho existente. O sistema encontra e fixa automaticamente todas as outras informações relacionadas ao atalho. -
Se você estiver fixando um novo atalho, crie um objeto
ShortcutInfo
que contenha um ID, uma intent e um rótulo curto para o novo atalho.
-
Se o atalho existir, crie um objeto
-
Fixe o atalho na tela de início do dispositivo chamando
requestPinShortcut()
. Durante esse processo, você pode transmitir um objetoPendingIntent
, que notifica seu app somente quando o atalho é fixado.Depois que um atalho é fixado, seu app pode atualizar o conteúdo usando o método
updateShortcuts()
. Para saber mais, leia Atualizar atalhos.
O snippet de código a seguir demonstra como criar um atalho fixado.
Kotlin
val shortcutManager = getSystemService(ShortcutManager::class.java) if (shortcutManager!!.isRequestPinShortcutSupported) { // Enable the existing shortcut with the ID "my-shortcut". val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build() // Create the PendingIntent object only if your app needs to be notified // that the user let the shortcut be pinned. If the pinning operation fails, // your app isn't notified. Assume here that the app implements a method // called createShortcutResultIntent() that returns a broadcast intent. val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo) // Configure the intent so that your app's broadcast receiver gets the // callback successfully. For details, see PendingIntent.getBroadcast(). val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0, pinnedShortcutCallbackIntent, /* flags */ 0) shortcutManager.requestPinShortcut(pinShortcutInfo, successCallback.intentSender) }
Java
ShortcutManager shortcutManager = context.getSystemService(ShortcutManager.class); if (shortcutManager.isRequestPinShortcutSupported()) { // Enable the existing shortcut with the ID "my-shortcut". ShortcutInfo pinShortcutInfo = new ShortcutInfo.Builder(context, "my-shortcut").build(); // Create the PendingIntent object only if your app needs to be notified // that the user let the shortcut be pinned. If the pinning operation fails, // your app isn't notified. Assume here that the app implements a method // called createShortcutResultIntent() that returns a broadcast intent. Intent pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo); // Configure the intent so that your app's broadcast receiver gets the // callback successfully. For details, see PendingIntent.getBroadcast(). PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0, pinnedShortcutCallbackIntent, /* flags */ 0); shortcutManager.requestPinShortcut(pinShortcutInfo, successCallback.getIntentSender()); }
Criar uma atividade de atalho personalizada
![Uma imagem mostrando a atividade da caixa de diálogo personalizada que mostra a solicitação "Quer adicionar o ícone de inicialização do Gmail à sua tela inicial?" As opções
personalizadas são "Agora não" e "Adicionar ícone".](https://developer.android.com/static/images/guide/topics/ui/shortcuts/pinned-shortcuts-dialog.png?authuser=6&hl=pt)
Você também pode criar uma atividade especializada que ajuda os usuários a criar atalhos, com opções personalizadas e um botão de confirmação. A Figura 2 mostra um exemplo desse tipo de atividade no app Gmail.
No arquivo de manifesto do app, adicione
ACTION_CREATE_SHORTCUT
ao elemento
<intent-filter>
da atividade. Essa declaração define o seguinte comportamento quando o usuário tenta
criar um atalho:
- O sistema inicia a atividade especializada do app.
- O usuário define opções para o atalho.
- O usuário seleciona o botão de confirmação.
-
Seu app cria o atalho usando o
método
createShortcutResultIntent()
. Esse método retorna umIntent
, que o app redireciona para a atividade em execução anteriormente usandosetResult()
. -
Seu app chama
finish()
na atividade usada para criar o atalho personalizado.
Da mesma forma, seu app pode solicitar que os usuários adicionem atalhos fixados à tela inicial após a instalação ou na primeira vez que o app for iniciado. Esse método é eficaz porque ajuda os usuários a criar um atalho como parte do fluxo de trabalho comum.
Testar atalhos
Para testar os atalhos, instale o app em um dispositivo com uma tela de início compatível com atalhos. Em seguida, faça o seguinte:
- Toque no ícone do app na tela de início e pressione para conferir os atalhos que você definiu para ele.
- Arraste um atalho para fixá-lo na tela de início do dispositivo.