Suporte para emojis modernos

Experimente trabalhar com o Compose

O Jetpack Compose é o kit de ferramentas de IU recomendado para Android. Saiba como oferecer suporte a emojis no Compose.

Emoji de apoio →

O conjunto padrão de emojis é atualizado anualmente pelo Unicode, já que o uso de emojis está aumentando rapidamente em todos os tipos de apps.

Se o app mostra conteúdo da Internet ou oferece entrada de texto, recomendamos que ele seja compatível com as fontes de emoji mais recentes. Caso contrário, os emojis mais recentes podem ser exibidos como uma pequena caixa quadrada chamada tofu (☐) ou outras sequências de emojis renderizadas incorretamente.

As versões do Android 11 (nível 30 da API) e anteriores não podem atualizar a fonte de emoji. Por isso, os apps que as mostram nessas versões precisam ser atualizados manualmente.

Veja a seguir exemplos de emojis modernos.

A biblioteca androidx.emoji2:emoji2 fornece compatibilidade mais simples com versões anteriores do Android. A biblioteca emoji2 é uma dependência da biblioteca AppCompat e não requer outras configurações para funcionar.

Suporte a emojis no Compose

A BOM de março de 2023 (Compose UI 1.4) oferece suporte à versão mais recente de emojis, incluindo compatibilidade com versões anteriores do Android até a API 21. Nesta página, explicamos como configurar emojis modernos no sistema de visualização. Consulte a página Emoji no Compose para mais informações.

Pré-requisitos

Para confirmar se o app mostra os novos emojis corretamente, inicie-o em um dispositivo com o Android 10 (nível 29 da API) ou uma versão anterior. Esta página inclui emojis modernos que podem ser mostrados para teste.

Usar a AppCompat para oferecer suporte aos emojis mais recentes

AppCompat 1.4 inclui suporte para emojis.

Para usar AppCompat para oferecer suporte a emojis, faça o seguinte:

1. Confira se o módulo depende da biblioteca AppCompat versão 1.4.0-alpha01 ou mais recente.

   build.gradle
   
   // Ensure version is 1.4.0-alpha01 or higher.
   implementation "androidx.appcompat:appcompat.$appcompatVersion"
   

2. Garanta que todas as atividades que mostram texto estendam a classe AppCompatActivity.

   Kotlin

   MyActivity.kt
   
   class MyActivity: AppCompatActivity {
   ...
   }

   Java

   MyActivity.java
   
   class MyActivity extends AppCompatActivity {
   ...
   }

3. Teste sua integração iniciando o app em um dispositivo com o Android 10 ou anterior e mostrando a seguinte string de teste. Confira se todos os caracteres são renderizados corretamente.

   • 16.0: 🫩, 🪉, 🇨🇶
   • 15.1: 🐦‍🔥, 🧑‍🧑‍🧒‍🧒, 👩🏽‍🦽‍➡️, 🇲🇶
   • 15.0: 🩷, 🫸🏼, 🐦‍⬛
   • 14.0: 🫠, 🫱🏼‍🫲🏿, 🫰🏽
   • 13.1: 😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
   • 13.0: 🥲, 🥷🏿, 🐻‍❄️
   • 12.1: 🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
   • 12.0: 🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

O app mostra automaticamente emojis compatíveis com versões anteriores em todos os dispositivos que oferecem um provedor de fontes para download compatível com emoji2, como dispositivos com o Google Play Services.

Se o app usa a AppCompat, mas mostra um tofu (☐)

Em alguns casos, o app pode mostrar tofu em vez do emoji correto, mesmo que você adicione a biblioteca AppCompat. Veja a seguir as possíveis explicações e soluções.

Você está executando o app em um dispositivo que foi atualizado recentemente ou em um novo emulador.

Limpe os dados do Google Play Services do app para limpar qualquer armazenamento em cache de fontes que possa ocorrer durante a inicialização. Isso normalmente resolve o problema após algumas horas.

Para limpar os dados do app, faça o seguinte:

1. Abra as Configurações no dispositivo Android.

2. Toque em Apps e notificações.

3. Toque em Mostrar todos os apps ou em Informações do app.

4. Role a lista de apps e toque em Google Play Services.

5. Toque em Armazenamento e cache.

6. Toque em Limpar cache.

Seu app não está usando uma classe da AppCompat relacionada a texto

Isso pode acontecer se você não estender AppCompatActivity ou se instanciar uma visualização no código, como TextView. Verifique:

• A atividade precisa estender a AppCompatActivity.
• Se você estiver criando a visualização no código, use a subclasse AppCompat correta.

Ao inflar o XML, a AppCompatActivity infla a AppCompatTextView automaticamente em vez da TextView, então você não precisa atualizar o XML.

O smartphone de teste não tem suporte a fontes para download

Verifique se DefaultEmojiCompatConfig.create retorna uma configuração não nula.

Um emulador em um nível da API anterior não fez upgrade do Google Play Services

Ao usar um emulador em um nível da API anterior, talvez seja necessário atualizar o Google Play Services incluído para que o emoji2 encontre o provedor de fontes. Para isso, faça login na Google Play Store no emulador.

Para verificar se uma versão compatível está instalada, faça o seguinte:

1. Execute este comando:

   adb shell dumpsys package com.google.android.gms | grep version
   

2. Confira se o versionCode é maior que 211200000.

Oferecer suporte a emojis sem a AppCompat

Se o app não puder incluir AppCompat, ele poderá usar emoji2 diretamente. Isso exige mais trabalho. Portanto, use esse método apenas se o app não puder usar AppCompat.

Para oferecer suporte a emojis sem a biblioteca AppCompat, faça o seguinte:

1. No arquivo build.gradle do seu app, inclua emoji2 e emoji2-views.

   build.gradle
   
   def emojiVersion = "1.0.0-alpha03"
   implementation "androidx.emoji2:emoji2:$emojiVersion"
   implementation "androidx.emoji2:emoji2-views:$emojiVersion"
   

   O módulo emoji2-views fornece subclasses de TextView, Button e EditText que implementam EmojiCompat. Não use em um app que inclua AppCompat, porque ele já implementa EmojiCompat.

2. Em XML e código, onde você usa TextView, EditText ou Button, use EmojiTextView, EmojiEditText ou EmojiButton.

   activity_main.xml
   
   <androidx.emoji2.widget.EmojiTextView ... />
   <androidx.emoji2.widget.EmojiEditText ... />
   <androidx.emoji2.widget.EmojiButton ... />
   

   Ao incluir o módulo emoji2, o sistema usa o provedor de fontes para download padrão para carregar a fonte de emoji automaticamente logo após a inicialização do app. Nenhuma outra configuração é necessária.

3. Para testar sua integração, inicie o app em um dispositivo com o Android 11 ou versão anterior e mostre as seguintes strings de teste. Confira se todos os caracteres são renderizados corretamente.

   • 16.0: 🫩, 🪉, 🇨🇶
   • 15.1: 🐦‍🔥, 🧑‍🧑‍🧒‍🧒, 👩🏽‍🦽‍➡️, 🇲🇶
   • 15.0: 🩷, 🫸🏼, 🐦‍⬛
   • 14.0: 🫠, 🫱🏼‍🫲🏿, 🫰🏽
   • 13.1: 😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
   • 13.0: 🥲, 🥷🏿, 🐻‍❄️
   • 12.1: 🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
   • 12.0: 🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

Usar a EmojiCompat sem widgets

O EmojiCompat usa EmojiSpan para renderizar as imagens corretas. Portanto, ele precisa converter qualquer objeto CharSequence em um objeto Spanned com objetos EmojiSpan. A classe EmojiCompat oferece o método process() para converter CharSequences em instâncias de Spanned. Com esse método, é possível chamar process() em segundo plano e armazenar os resultados em cache, o que melhora o desempenho do app.

val processed = EmojiCompat.get().process("neutral face \uD83D\uDE10")

CharSequence processed = EmojiCompat.get().process("neutral face \uD83D\uDE10");

Usar a EmojiCompat para editores de método de entrada

A classe EmojiCompat permite que os teclados renderizem o emoji compatível com o app com que estão interagindo. Os Editores de método de entrada (IMEs) podem usar o método getEmojiMatch() para verificar se uma instância de EmojiCompat é capaz de renderizar um emoji. Esse método usa uma CharSequence de um emoji e retorna true se a EmojiCompat puder detectar e renderizar o emoji.

O teclado também pode conferir a versão da EmojiCompat que é compatível com o app para determinar qual emoji renderizar na paleta. Para conferir a versão, se disponível, o teclado pode procurar as seguintes teclas no pacote EditorInfo.extras:

• EDITOR_INFO_METAVERSION_KEY: representa a versão dos metadados de emoji que o app usa. Se essa tecla não existe, o app não está usando a EmojiCompat.
• EDITOR_INFO_REPLACE_ALL_KEY: se a chave existir e estiver definida como true, o app vai configurar EmojiCompat para substituir todos os emojis, mesmo que eles estejam presentes no sistema.

Saiba mais sobre como configurar uma instância da EmojiCompat.

Usar emojis em visualizações personalizadas

Se o app tiver visualizações personalizadas que sejam subclasses diretas ou indiretas de TextView, por exemplo, Button, Switch ou EditText, e essas visualizações puderem mostrar conteúdo gerado pelo usuário, cada uma delas precisará implementar EmojiCompat.

O processo varia de acordo com o uso da biblioteca AppCompat pelo app.

Adicionar visualizações personalizadas para apps com a AppCompat

Se o app usa AppCompat, estenda a implementação de AppCompat em vez da implementação da plataforma. Use a tabela a seguir como guia para estender as visualizações no AppCompat:

Adicionar visualizações personalizadas para apps sem a AppCompat

Caso seu app não use a AppCompat, use os auxiliares de integração de visualização no módulo emoji2-views-helper que foram projetados para uso em visualizações personalizadas. Esses são os auxiliares que a biblioteca AppCompat usa para implementar o suporte a emojis.

Conclua as etapas a seguir para oferecer suporte a visualizações personalizadas para apps que não usam a AppCompat.

1. Adicione a biblioteca emoji2-views-helper:

   implementation "androidx.emoji2:emoji2-views-helper:$emojiVersion"
   

2. Siga as instruções para incluir EmojiTextViewHelper ou EmojiEditTextHelper nas visualizações personalizadas do app.

3. Teste sua integração iniciando o app em um dispositivo com o Android 10 ou anterior e mostrando a seguinte string de teste. Confira se todos os caracteres são renderizados corretamente.

   • 16.0: 🫩, 🪉, 🇨🇶
   • 15.1: 🐦‍🔥, 🧑‍🧑‍🧒‍🧒, 👩🏽‍🦽‍➡️, 🇲🇶
   • 15.0: 🩷, 🫸🏼, 🐦‍⬛
   • 14.0: 🫠, 🫱🏼‍🫲🏿, 🫰🏽
   • 13.1: 😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
   • 13.0: 🥲, 🥷🏿, 🐻‍❄️
   • 12.1: 🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
   • 12.0: 🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

Recursos opcionais para lidar com a emoji2

Depois de incluir a biblioteca emoji2 no app, você pode adicionar os recursos opcionais descritos nesta seção.

Configurar a emoji2 para usar uma fonte ou um provedor de fontes disponíveis para download diferente

Para configurar a emoji2 para usar uma fonte ou um provedor de fontes disponíveis para download diferente, faça o seguinte:

1. Desative o EmojiCompatInitializer adicionando o seguinte ao manifesto:

   <provider
   android:name="androidx.startup.InitializationProvider"
   android:authorities="${applicationId}.androidx-startup"
   android:exported="false"
   tools:node="merge">
   <meta-data android:name="androidx.emoji2.text.EmojiCompatInitializer"
              tools:node="remove" />
   </provider>

2. Escolha uma destas opções:

   • Use a configuração padrão chamando DefaultEmojiCompatConfiguration.create(context).

   • Crie sua própria configuração para carregar fontes de outra origem usando a EmojiCompat.Config. Essa classe oferece várias opções para modificar o comportamento do EmojiCompat, conforme descrito na seção a seguir.

Modificar o comportamento da EmojiCompat

É possível usar uma instância de EmojiCompat.Config para modificar o comportamento de EmojiCompat.

A opção de configuração mais importante é setMetadataLoadStrategy(), que controla quando a EmojiCompat carrega a fonte. O carregamento da fonte começa assim que EmojiCompat.load() é chamado, o que aciona os downloads necessários. O sistema cria uma linha de execução para o download de fontes, a menos que o app forneça uma.

O LOAD_STRATEGY_MANUAL permite controlar quando EmojiCompat.load() é chamado, e LOAD_STRATEGY_DEFAULT faz com que o carregamento seja iniciado de forma síncrona na chamada para EmojiCompat.init().

A maioria dos apps usa LOAD_STRATEGY_MANUAL para controlar a linha de execução e o tempo de carregamento da fonte. O app precisa adiar até que a primeira tela seja exibida para evitar a latência de inicialização. O EmojiCompatInitializer segue essa prática e adia o carregamento da fonte de emoji até que a primeira tela seja retomada.

Use os seguintes métodos da classe de base para definir outros aspectos da configuração:

• setReplaceAll(): determina se EmojiCompat substitui todos os emojis encontrados por instâncias de EmojiSpan. Por padrão, quando a EmojiCompat infere que o sistema pode renderizar um emoji, ela não o substitui. Quando definido como true, EmojiCompat substitui todos os emojis por objetos EmojiSpan.
• setEmojiSpanIndicatorEnabled(): indica se EmojiCompat substitui um emoji por um objeto EmojiSpan. Quando definido como true, EmojiCompat desenha um plano de fundo para a EmojiSpan. Esse método é usado principalmente para fins de depuração.
• setEmojiSpanIndicatorColor: define a cor para indicar um EmojiSpan. O valor padrão é GREEN.
• registerInitCallback(): informa um app sobre o estado da inicialização do EmojiCompat.

Adicionar listeners de inicialização

As classes EmojiCompat e EmojiCompat.Config fornecem os métodos registerInitCallback() e unregisterInitCallback() para registrar e cancelar o registro de callbacks de inicialização. O app usa esses callbacks para aguardar até que EmojiCompat seja inicializado antes de processar o emoji em uma linha de execução em segundo plano ou em uma visualização personalizada.

Para usar esses métodos, crie uma instância da classe EmojiCompat.InitCallback. Chame esses métodos e transmita a instância da classe EmojiCompat.InitCallback. Quando a inicialização for bem-sucedida, a classe EmojiCompat chamará o método onInitialized(). Se a biblioteca não for inicializada, a classe EmojiCompat vai chamar o método onFailed().

Para verificar o estado de inicialização a qualquer momento, chame o método getLoadState(). Esse método retorna um dos seguintes valores: LOAD_STATE_LOADING, LOAD_STATE_SUCCEEDED ou LOAD_STATE_FAILED.

Suporte para fontes incluídas na emoji2

Você pode usar o artefato emoji2-bundled para agrupar uma fonte de emoji no seu app. No entanto, como a fonte NotoColorEmoji tem mais de 10 MB, recomendamos que seu app use fontes para download sempre que possível. O artefato emoji2-bundled é destinado a apps em dispositivos que não oferecem suporte a fontes para download.

Para usar o artefato emoji2-bundled, faça o seguinte:

1. Inclua os artefatos emoji2-bundled e emoji2:

   implementation "androidx.emoji2:emoji2:$emojiVersion"
   implementation "androidx.emoji2:emoji2-bundled:$emojiVersion"
   

2. Configure o emoji2 para usar a configuração em pacote:

   Kotlin

   EmojiCompat.init(BundledEmojiCompatConfig(context))

   Java

   EmojiCompat.init(new BundledEmojiCompatConfig(context));

3. Teste a integração seguindo as etapas anteriores para incluir emojicompat com ou sem AppCompat. Verifique se a string de teste é exibida corretamente.

   • 16.0: 🫩, 🪉, 🇨🇶
   • 15.1: 🐦‍🔥, 🧑‍🧑‍🧒‍🧒, 👩🏽‍🦽‍➡️, 🇲🇶
   • 15.0: 🩷, 🫸🏼, 🐦‍⬛
   • 14.0: 🫠, 🫱🏼‍🫲🏿, 🫰🏽
   • 13.1: 😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
   • 13.0: 🥲, 🥷🏿, 🐻‍❄️
   • 12.1: 🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
   • 12.0: 🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

Impacto da configuração automática da EmojiCompat

O sistema aplica a configuração padrão usando a biblioteca de inicialização, EmojiCompatInitializer e DefaultEmojiCompatConfig.

Depois que a primeira atividade é retomada no app, o inicializador programa o carregamento da fonte de emojis. Esse breve atraso permite que o app mostre o conteúdo inicial sem possíveis latências devido ao carregamento de fontes em uma linha de execução em segundo plano.

O DefaultEmojiCompatConfig procura um provedor de fontes para download instalado no sistema que implemente a interface EmojiCompat, como o Google Play Services. Em dispositivos com o Google Play Services, a fonte é carregada usando esse serviço.

O inicializador cria uma linha de execução em segundo plano para carregar a fonte de emoji, e o download da fonte pode levar até 10 segundos antes de expirar. Depois do download, a inicialização da EmojiCompat leva aproximadamente 150 milissegundos em uma linha de execução em segundo plano.

Adie a inicialização da EmojiCompat, mesmo que você desative a EmojiCompatInitializer. Se você configurar manualmente EmojiCompat, chame EmojiCompat.load() depois que ele exibir a primeira tela do app para evitar a contenção em segundo plano com o primeiro carregamento de tela.

Após o carregamento, o EmojiCompat usa cerca de 300 KB de RAM para armazenar os metadados de emoji.