O conjunto padrão de emojis é atualizado anualmente pelo Unicode (link em inglês), e o uso de emojis pelos usuários está aumentando rapidamente para todos os tipos de apps.
Caso seu app mostre conteúdo da Internet ou permita a entrada de texto, recomendamos que você ofereça suporte para as fontes de emojis mais recentes. Caso contrário, novos emojis poderão ser mostrados como um pequeno quadrado chamado de tofu (☐) ou outras sequências de emojis renderizadas incorretamente.
O Android 11 (API de nível 30) e versões anteriores não podem atualizar a fonte de emojis, então os apps que as exibem nessas versões precisarão ser atualizados manualmente.
Veja a seguir alguns exemplos de emojis modernos.
Exemplos | Versão |
---|---|
🫠 🫱🏼🫲🏿 🫰🏽 | 14.0 (setembro de 2021) |
😶🌫️ 🧔🏻♀️ 🧑🏿❤️🧑🏾 | 13.1 (setembro de 2020) |
🥲 🥷🏿 🐻❄️ | 13.0 (março de 2020) |
🧑🏻🦰 🧑🏿🦯 👩🏻🤝👩🏼 | 12.1 (outubro de 2019) |
🦩 🦻🏿 👩🏼🤝👩🏻 | 12.0 (fevereiro de 2019) |
A biblioteca androidx.emoji2:emoji2
fornece compatibilidade mais simples
com versões anteriores do Android. A biblioteca emoji2
é uma dependência da
AppCompat
e não requer outras
configurações para funcionar.
Pré-requisitos
Para confirmar que seu app mostra corretamente os novos emojis, inicie-o em um dispositivo com uma versão do Android entre a 4.4 (API de nível 19) e 10 (API de nível 29). Esta página inclui emojis modernos que podem ser usados para testes.
Usar a AppCompat para oferecer suporte aos emojis mais recentes
A AppCompat 1.4 inclui suporte para emojis até o Android 4.4.
Se quiser usar a AppCompat para oferecer suporte aos emojis mais recentes, faça o seguinte:
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"
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 { … }
Para testar sua integração, inicie o app em um dispositivo com Android 10 ou versão anterior e use a string de teste a seguir. Confira se todos os caracteres são renderizados corretamente.
- 14.0: 🫠, 🫱🏼🫲🏿, 🫰🏽
- 13.1: 😶🌫️, 🧔🏻♀️, 🧑🏿❤️🧑🏾
- 13.0: 🥲, 🥷🏿, 🐻❄️
- 12.1: 🧑🏻🦰, 🧑🏿🦯, 👩🏻🤝👩🏼
- 12.0: 🦩, 🦻🏿, 👩🏼🤝👩🏻
Pronto! Seu app mostra automaticamente os emojis compatíveis com versões anteriores em todos os
dispositivos que oferecem um provedor de fontes para download compatíveis com emoji2
, como
dispositivos com tecnologia do Google Play
Services.
Se o app usa a AppCompat, mas mostra um tofu (☐)
Em alguns casos, seu app pode mostrar um tofu (☐) em vez do emoji adequado mesmo que você tenha adicionado a biblioteca AppCompat. Veja a seguir algumas possíveis explicações e soluções.
Você está executando o app em um dispositivo recém-atualizado ou em um novo emulador
Limpe os dados do Google Play Services para limpar o armazenamento em cache de fontes que possa ter ocorrido durante a inicialização. Depois de fazer isso, a situação costuma se resolver em algumas horas.
Para limpar os dados do app:
No dispositivo Android, abra Configurações.
Em Configurações, toque em Apps e notificações.
Toque em Ver todos os apps ou em Informações do app.
Role pelos apps e toque em Google Play Services.
Toque em Armazenamento e cache.
Toque em Limpar cache.
Seu app não está usando uma classe da AppCompat relacionada a texto
Isso poderá acontecer se você não estender a AppCompatActivity
ou se instanciar uma
visualização em código, como TextView
. É necessário fazer o seguinte:
- A atividade precisa estender a
AppCompatActivity
. - Se estiver criando a visualização em código, use a
appcompat subclass
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 de API mais antigo ainda não fez upgrade do Google Play Services
Ao usar um emulador em um nível de API mais antigo, o pacote do Google Play Services
pode precisar de um upgrade para que a emoji2
encontre o provedor de fontes. Para isso, faça login
na Google Play Store no emulador.
Se quiser verificar se uma versão adequada foi instalada, faça o seguinte:
Execute o comando:
adb shell dumpsys package com.google.android.gms | grep version
Confira se o
versionCode
é maior que211200000
.
Oferecer suporte a emojis sem a AppCompat
Se o app não incluir a appcompat
, a emoji2
poderá ser usada diretamente. Como
isso exige mais trabalho, use esse método somente se o app não puder
usar a appcompat
.
Para oferecer suporte a emojis sem a biblioteca AppCompat, faça o seguinte:
No arquivo
build.gradle
do seu app, incluaemoji2
eemoji2-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 deTextView
,Button
eEditText
que implementam aEmojiCompat
e não deve ser usado em um app que inclui aappcompat
porque já implementa aEmojiCompat
.Em XML ou código (onde você usaria
TextView
,EditText
ouButton
), useEmojiTextView
,EmojiEditText
ouEmojiButton
.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 padrão de fontes para download para carregar a fonte de emojis automaticamente logo após a inicialização do app, e não é necessária nenhuma outra configuração.Para testar sua integração, inicie o app em um dispositivo com Android 10 ou versão anterior e use as strings de teste a seguir. Confira se todos os caracteres são renderizados corretamente.
- 14.0: 🫠, 🫱🏼🫲🏿, 🫰🏽
- 13.1: 😶🌫️, 🧔🏻♀️, 🧑🏿❤️🧑🏾
- 13.0: 🥲, 🥷🏿, 🐻❄️
- 12.1: 🧑🏻🦰, 🧑🏿🦯, 👩🏻🤝👩🏼
- 12.0: 🦩, 🦻🏿, 👩🏼🤝👩🏻
Usar a EmojiCompat sem widgets
A EmojiCompat
usa
a classe EmojiSpan
para renderizar as imagens
corretas. Por isso, ela precisa converter todos os objetos [CharSequence
] em
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 o process()
em
segundo plano e armazenar em cache os resultados, o que melhora o desempenho do app.
Kotlin
val processed = EmojiCompat.get().process("neutral face \uD83D\uDE10")
Java
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 os emojis que têm suporte no app com que estão interagindo.
Editores de método de entrada (IME, na sigla em inglês) podem usar
o método hasEmojiGlyph()
para conferir se uma instância da EmojiCompat
é capaz de renderizar um
emoji. Esse método usa um objeto CharSequence
de um emoji e retorna o valor true
caso a EmojiCompat
possa 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 usada pelo app. Se essa tecla não existe, o app não está usando aEmojiCompat
.EDITOR_INFO_REPLACE_ALL_KEY
: se a tecla existe e está definida comotrue
, isso significa que o app configurou aEmojiCompat
para substituir todos os emojis, mesmo que estejam presentes no sistema.
Saiba mais sobre como configurar uma instância da EmojiCompat.
Usar emojis em visualizações personalizadas
Se o app tem visualizações personalizadas que são
subclasses diretas ou indiretas da TextView
(por exemplo, Button
, Switch
ou
EditText
) e pode mostrar conteúdo gerado pelo usuário, cada uma precisa implementar a
EmojiCompat.
O processo é diferente dependendo se o app usa ou não a biblioteca
appcompat
.
Adicionar visualizações personalizadas para apps com a AppCompat
Se o app usa a AppCompat, estenda a implementação dela em vez da implementação da plataforma. Use a tabela a seguir como guia para estender as visualizações na AppCompat:
Em vez de estender… | Estenda |
---|---|
TextView
|
AppCompatTextView
|
EditText
|
AppCompatEditText
|
ToggleButton
|
AppCompatToggleButton
|
Switch
|
SwitchCompat
|
Button
|
AppCompatButton
|
CheckedTextView
|
AppCompatCheckedTextView
|
RadioButton
|
AppCompatRadioButton
|
CheckBox
|
AppCompatCheckBox
|
AutoCompleteTextView
|
AppCompatAutoCompleteTextView
|
MultiAutoCompleteTextView
|
AppCompatMultiAutoCompleteTextView
|
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
.
Adicione a biblioteca
emoji2-views-helper
.implementation "androidx.emoji2:emoji2-views-helper:$emojiVersion"
Siga as instruções para incluir a classe EmojiTextViewHelper ou EmojiEditTextHelper nas visualizações personalizadas do app.
Para testar sua integração, inicie o app em um dispositivo com Android 10 ou versão anterior e use a string de teste a seguir. Confira se todos os caracteres são renderizados corretamente.
- 14.0: 🫠, 🫱🏼🫲🏿, 🫰🏽
- 13.1: 😶🌫️, 🧔🏻♀️, 🧑🏿❤️🧑🏾
- 13.0: 🥲, 🥷🏿, 🐻❄️
- 12.1: 🧑🏻🦰, 🧑🏿🦯, 👩🏻🤝👩🏼
- 12.0: 🦩, 🦻🏿, 👩🏼🤝👩🏻
Recursos opcionais para lidar com a emoji2
Depois de incluir a biblioteca emoji2
no seu app, é possível 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:
Desative a
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>
Realize uma destas açõ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 da EmojiCompat.
- Use a configuração padrão chamando
Modificar o comportamento da EmojiCompat
Você pode usar uma instância da
EmojiCompat.Config
para
modificar o comportamento da EmojiCompat
.
A opção de configuração mais importante é
setMetadataLoadStrategy()
,
que controla quando a EmojiCompat
carrega a fonte. O carregamento de fonte começa assim que a função
EmojiCompat.load()
é chamada, e isso aciona todos os downloads necessários.
O sistema cria uma linha de execução para o download de fontes, a menos que seu app ofereça uma.
A constante LOAD_STRATEGY_MANUAL
permite que você controle quando a EmojiCompat.load()
é chamada, e
LOAD_STRATEGY_DEFAULT
faz com que o carregamento seja iniciado de forma síncrona na chamada para
EmojiCompat.init()
.
A maioria dos apps precisa usar a LOAD_STRATEGY_MANUAL
para permitir o controle sobre a linha de execução e
o tempo de carregamento da fonte. Em especial, seu app precisa adiar até a
primeira tela ser exibida para evitar a introdução da latência na inicialização.
A EmojiCompatInitializer
segue essa prática e adia o carregamento da fonte de emojis
até que a primeira tela seja retomada.
Use os seguintes métodos da classe base para definir outros aspectos da configuração:
setReplaceAll()
: determina se aEmojiCompat
substituirá todos os emojis que encontrar por instâncias deEmojiSpan
. Por padrão, quando aEmojiCompat
infere que o sistema pode renderizar um emoji, ela não substitui esse emoji. Quando definido comotrue
, a EmojiCompat substitui todos os emojis por objetosEmojiSpan
.setEmojiSpanIndicatorEnabled()
: indica se aEmojiCompat
substituiu um emoji por um objetoEmojiSpan
. Quando definido comotrue
,EmojiCompat
desenha um plano de fundo para aEmojiSpan
. Esse método é usado principalmente para fins de depuração.setEmojiSpanIndicatorColor
: define a cor para indicar umEmojiSpan
. O valor padrão éGREEN
.registerInitCallback()
: informa um app sobre o estado de inicialização daEmojiCompat
.
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. Seu app usa esses
callbacks para aguardar até que a EmojiCompat
seja inicializada antes de você 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 chamará o
método
onFailed()
. Para conferir 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 incluir uma fonte de emojis no seu app.
No entanto, como a fonte NotoColorEmoji
atual tem mais de 10 MB, recomendamos que
o app use fontes para download quando possível. O artefato emoji2-
bundled
é destinado a apps em dispositivos não compatíveis com
fontes para download.
Para usar o artefato emoji2-bundled
, faça o seguinte:
Inclua os artefatos
emoji2-bundled
eemoji2
.implementation "androidx.emoji2:emoji2:$emojiVersion" implementation "androidx.emoji2:emoji2-bundled:$emojiVersion"
Defina a
emoji2
para usar a configuração do pacote.Kotlin
EmojiCompat.init(BundledEmojiCompatConfig(context))
Java
EmojiCompat.init(new BundledEmojiCompatConfig(context));
Teste a integração seguindo as etapas acima para incluir a
emojicompat
com ou sem aappcompat
, conferindo se a string de teste aparece corretamente.- 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.
Logo após a primeira atividade ser retomada no app, o inicializador programa o carregamento de fontes de emojis. Esse breve atraso permite que o app mostre o conteúdo inicial sem nenhuma possível latência devido ao carregamento de fontes em uma linha de execução em segundo plano.
A DefaultEmojiCompatConfig
procura um provedor de fontes para download
instalado pelo sistema que implemente a interface da 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 do emojis, 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 a EmojiCompat
manualmente, chame EmojiCompat.load()
depois da exibição da primeira tela
do app para evitar a contenção em segundo plano com o carregamento da primeira tela.
Após o carregamento, a EmojiCompat usa cerca de 300 KB de RAM para armazenar os metadados de emojis.