Se o seu app puder executar uma ação que pode ser útil para outro app, prepare-o para responder a solicitações de ação especificando o filtro de intent apropriado na sua atividade.
Por exemplo, se você
criar um aplicativo social que possa compartilhar mensagens ou fotos com os amigos do usuário, precisará
oferecer suporte para a intent ACTION_SEND
.
Assim, quando os usuários iniciarem uma ação de "compartilhamento" em outro app, seu app aparecerá como uma opção na
caixa de diálogo seletora (também conhecida como caixa de diálogo de desambiguação), como mostrado na figura 1.
Para permitir que outros apps iniciem sua atividade dessa maneira, é preciso adicionar um elemento <intent-filter>
ao seu arquivo de manifesto para o elemento <activity>
correspondente.
Quando seu app for instalado em um dispositivo, o sistema identificará seus filtros
de intent e adicionará as informações a um catálogo interno de intents compatíveis com todos os apps instalados.
Quando um app chamar startActivity()
ou startActivityForResult()
com uma intent implícita, o sistema vai verificar se há atividades que possam responder à
intent.
Adicionar um filtro de intent
Para definir adequadamente quais intents sua atividade poderá processar, faça com que cada filtro de intent adicionado seja o mais específico possível em termos de tipo de ação e dados aceitos pela atividade.
O sistema poderá enviar um Intent
para uma atividade se ela tiver
um filtro de intent que atenda os seguintes critérios do objeto Intent
:
- Ação
- String que dá nome à ação a ser executada. Geralmente, um dos valores definidos pela plataforma,
como
ACTION_SEND
ouACTION_VIEW
.Especifique-a no seu filtro de intents com o elemento
<action>
. O valor especificado nesse elemento precisa ser o nome completo da string para a ação, e não a constante da API, conforme mostrado nos exemplos desta página. - Dados
- A descrição dos dados associados à intent.
Especifique-a no seu filtro de intents com o elemento
<data>
. Usando um ou mais atributos nesse elemento, você pode especificar o tipo MIME, um prefixo de URI, um esquema de URI ou uma combinação desses e de outros elementos que indicam o tipo de dados aceito.Observação: se você não precisar declarar detalhes sobre os dados
Uri
(por exemplo, quando sua atividade processar outros tipos de dados "extra", em vez de um URI), especifique somente o atributoandroid:mimeType
para declarar o tipo de dados que a atividade processa, comotext/plain
ouimage/jpeg
. - Categoria
- Oferece uma outra forma de caracterizar a atividade que processa a intent, geralmente relacionada
ao gesto do usuário ou ao local onde ela foi iniciada. Há diversas categorias
compatíveis com o sistema, mas a maioria raramente é usada. No entanto, todas as intents implícitas são definidas com
CATEGORY_DEFAULT
por padrão.Especifique-a no seu filtro de intents com o elemento
<category>
.
No filtro de intents, informe quais critérios serão aceitos
pela atividade declarando cada um deles com elementos XML correspondentes aninhados no elemento
<intent-filter>
.
Este é um exemplo de atividade com filtro de intent que processa a intent ACTION_SEND
quando o tipo de dado é texto ou imagem:
<activity android:name="ShareActivity"> <intent-filter> <action android:name="android.intent.action.SEND"/> <category android:name="android.intent.category.DEFAULT"/> <data android:mimeType="text/plain"/> <data android:mimeType="image/*"/> </intent-filter> </activity>
Dica: se quiser que o ícone na caixa de diálogo seletora seja diferente
do padrão da atividade, adicione android:icon
no elemento
<intent-filter>
.
Cada intent recebida especifica apenas uma ação e um tipo de dado, mas é possível declarar várias
instâncias dos elementos <action>
, <category>
e <data>
em cada
<intent-filter>
.
Se dois pares de ação e dados forem mutuamente exclusivos no comportamento, crie filtros de intent separados para especificar quais ações são aceitáveis quando pareadas com cada tipo de dado.
Suponha que a atividade processe texto e imagens para as intents ACTION_SEND
e ACTION_SENDTO
. Nesse caso, é preciso definir dois
filtros de intent para as duas ações porque uma intent ACTION_SENDTO
precisa usar os dados de Uri
para especificar
o endereço do destinatário usando o esquema de URI send
ou sendto
. Isso é mostrado neste exemplo:
<activity android:name="ShareActivity"> <!-- Filter for sending text; accepts SENDTO action with sms URI schemes --> <intent-filter> <action android:name="android.intent.action.SENDTO"/> <category android:name="android.intent.category.DEFAULT"/> <data android:scheme="sms" /> <data android:scheme="smsto" /> </intent-filter> <!-- Filter for sending text or images; accepts SEND action and text or image data --> <intent-filter> <action android:name="android.intent.action.SEND"/> <category android:name="android.intent.category.DEFAULT"/> <data android:mimeType="image/*"/> <data android:mimeType="text/plain"/> </intent-filter> </activity>
Observação: para receber intents implícitas, inclua a categoria
CATEGORY_DEFAULT
no filtro de intents. Os métodos startActivity()
e startActivityForResult()
tratam todas as intents como se elas
declarassem a categoria CATEGORY_DEFAULT
. Se você não fizer a declaração
no filtro de intent, nenhuma intent implícita será resolvida para sua atividade.
Para ter mais informações sobre o envio e o recebimento de intents ACTION_SEND
que realizam comportamentos de compartilhamento social, consulte Como receber dados simples de outros apps.
Você também pode encontrar informações úteis sobre o compartilhamento de dados em
Como compartilhar dados simples e
Como compartilhar arquivos.
Processar a intent na sua atividade
Para decidir qual ação realizar na sua atividade, leia o
Intent
que foi usado para iniciá-la.
Quando a atividade iniciar, chame getIntent()
para recuperar o
Intent
que iniciou a atividade. Você pode fazer isso a qualquer momento durante o
ciclo de vida da atividade, mas é recomendável usar o recurso em callbacks iniciais, como
onCreate()
ou onStart()
.
Isso é mostrado neste exemplo:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.main) val data: Uri? = intent?.data // Figure out what to do based on the intent type if (intent?.type?.startsWith("image/") == true) { // Handle intents with image data } else if (intent?.type == "text/plain") { // Handle intents with text } }
Java
@Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); // Get the intent that started this activity Intent intent = getIntent(); Uri data = intent.getData(); // Figure out what to do based on the intent type if (intent.getType().indexOf("image/") != -1) { // Handle intents with image data } else if (intent.getType().equals("text/plain")) { // Handle intents with text } }
Retornar um resultado
Se você quiser retornar um resultado para a atividade que invocou a sua, chame setResult()
para especificar o código do resultado e o Intent
de resultado. Quando a operação for concluída e o usuário precisar retornar à atividade
original, chame finish()
para
fechar e destruir a atividade. Isso é mostrado neste exemplo:
Kotlin
// Create intent to deliver some kind of result data Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri")).also { result -> setResult(Activity.RESULT_OK, result) } finish()
Java
// Create intent to deliver some kind of result data Intent result = new Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri")); setResult(Activity.RESULT_OK, result); finish();
Sempre especifique um código de resultado com o resultado. Geralmente, é RESULT_OK
ou RESULT_CANCELED
. É possível
fornecer dados adicionais com um Intent
, caso seja necessário.
Observação: o resultado é definido como RESULT_CANCELED
por padrão. Portanto, se o usuário pressionar o botão
Voltar antes de concluir a ação e de você definir o resultado, a atividade original vai receber
o resultado "cancelado".
Se precisar simplesmente retornar um número inteiro que indica uma das várias opções de resultado, você poderá definir
o código de resultado como qualquer valor maior que 0. Se usar o código de resultado para entregar um número inteiro e
não tiver necessidade de incluir o Intent
, você poderá chamar setResult()
e passar apenas um código de resultado.
Kotlin
setResult(RESULT_COLOR_RED) finish()
Java
setResult(RESULT_COLOR_RED); finish();
Nesse caso, talvez existam apenas alguns poucos resultados possíveis. Portanto, o código do resultado é um número inteiro definido localmente (maior que 0). Isso funciona bem ao retornar um resultado para uma atividade no seu app, porque a atividade que receber o resultado poderá fazer uma referência à constante pública para determinar o valor do código de resultado.
Observação: não é necessário verificar se a atividade foi iniciada
com startActivity()
ou startActivityForResult()
. Basta chamar setResult()
se a intent que iniciou sua atividade
puder esperar um resultado. Se a atividade inicial chama startActivityForResult()
, o sistema fornece o
resultado para setResult()
. Caso contrário,
o resultado é ignorado.