Supporto delle emoji moderne

Prova la funzionalità Scrivi

Jetpack Compose è il toolkit per l'interfaccia utente consigliato per Android. Scopri come supportare le emoji in Scrivi.

Supporta le emoji →

Importante: questa pagina descrive la libreria androidx.emoji2:emoji2, che sostituisce la libreria androidx.emoji:emoji deprecata.

L'insieme standard di emoji viene aggiornato annualmente da Unicode, poiché l'utilizzo delle emoji è in aumento rapido per tutti i tipi di app.

Se la tua app mostra contenuti di internet o consente di inserire testo, ti consigliamo vivamente di supportare i caratteri emoji più recenti. In caso contrario, le emoji successive potrebbero essere visualizzate come un piccolo riquadro quadrato chiamato tofu (☐) o altre sequenze di emoji visualizzate in modo errato.

Le versioni di Android 11 (livello API 30) e precedenti non possono aggiornare il carattere emoji, pertanto le app che le mostrano su queste versioni devono essere aggiornate manualmente.

Di seguito sono riportati alcuni esempi di emoji moderne.

Esempi	Versione
🫠 🫱🏼‍🫲🏿 🫰🏽	14.0 (settembre 2021)
😶‍🌫️ 🧔🏻‍♀️ 🧑🏿‍❤️‍🧑🏾	13.1 (settembre 2020)
🥲 🥷🏿 🐻‍❄️	13.0 (marzo 2020)
🧑🏻‍🦰 🧑🏿‍🦯 👩🏻‍🤝‍👩🏼	12.1 (ottobre 2019)
🦩 🦻🏿 👩🏼‍🤝‍👩🏻	12.0 (febbraio 2019)

La libreria androidx.emoji2:emoji2 offre una compatibilità con le versioni precedenti più semplice con le versioni precedenti di Android. La raccolta emoji2 è una dipendenza della raccolta AppCompat e non richiede ulteriori configurazioni per funzionare.

Supporto delle emoji in Scrivi

Il BOM di marzo 2023 (Compose UI 1.4) supporta la versione più recente delle emoji, inclusa la compatibilità con le versioni precedenti di Android fino all'API 21. Questa pagina spiega come configurare le emoji moderne nel sistema View. Per saperne di più, consulta la pagina Emoji in Scrivi.

Prerequisiti

Per verificare che la tua app mostri correttamente le emoji più recenti, avviala su un dispositivo con Android 10 (livello API 29) o versioni precedenti. Questa pagina include emoji moderne che puoi visualizzare per il test.

Utilizzare AppCompat per supportare le emoji più recenti

AppCompat 1.4 include il supporto per le emoji.

Per utilizzare AppCompat per supportare le emoji:

1. Verifica che il tuo modulo dipenda dalla versione della libreria AppCompat 1.4.0-alpha01 o superiore.

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

2. Assicurati che tutte le attività che mostrano testo estendano la classe AppCompatActivity.

   Kotlin

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

   Java

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

3. Testa l'integrazione avviando l'app su un dispositivo con Android 10 o versioni precedenti e visualizzando la seguente stringa di test. Assicurati che tutti i caratteri vengano visualizzati correttamente.

   • 14.0: 🫠, 🫱🏼‍🫲🏿, 🫰🏽
   • 13.1: 😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
   • 13.0: 🥲, 🥷🏿, 🐻‍❄️
   • 12.1: 🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
   • 12.0: 🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

L'app mostra automaticamente emoji compatibili con le versioni precedenti su tutti i dispositivi che forniscono un fornitore di caratteri scaricabili compatibile con emoji2, ad esempio i dispositivi con Google Play Services.

Se la tua app utilizza AppCompat, ma mostra tofu (☐)

In alcuni casi, l'app potrebbe mostrare il tofu anziché l'emoji corretta, anche se aggiungi la raccolta AppCompat. Di seguito sono riportate possibili spiegazioni e soluzioni.

L'app viene eseguita su un dispositivo su cui è stato eseguito il flashing di recente o su un nuovo emulatore

Cancella i dati di Google Play Services dell'app per eliminare eventuali cache dei caratteri che potrebbero verificarsi durante l'avvio. In genere il problema si risolve dopo alcune ore.

Per cancellare i dati dell'app:

1. Apri Impostazioni sul tuo dispositivo Android.

2. Tocca App e notifiche.

3. Tocca Mostra tutte le app o Informazioni app.

4. Scorri le app e tocca Google Play Services.

5. Tocca Spazio di archiviazione e cache.

6. Tocca Svuota cache.

La tua app non utilizza una classe relativa al testo di AppCompat

Questo può accadere se non estendi AppCompatActivity o se esegui l'inizializzazione di una vista nel codice, ad esempio TextView. Controlla quanto segue.

• L'attività si estende per AppCompatActivity.
• Se crei la visualizzazione nel codice, utilizza la AppCompat sottoclasse corretta.

AppCompatActivity espande automaticamente AppCompatTextView al posto di TextView durante l'espansione del file XML, quindi non devi aggiornare il file XML.

Lo smartphone di test non supporta i caratteri scaricabili

Verifica che DefaultEmojiCompatConfig.create restituisca una configurazione non null.

Un emulatore con un livello API precedente non ha eseguito l'upgrade di Google Play Services

Quando utilizzi un emulatore con un livello API precedente, potrebbe essere necessario aggiornare Google Play Services in bundle per emoji2 per trovare il provider di caratteri. Per farlo, accedi al Google Play Store sull'emulatore.

Per verificare che sia installata una versione compatibile:

1. Esegui il seguente comando:

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

2. Verifica che versionCode sia superiore a 211200000.

Supportare le emoji senza AppCompat

Se la tua app non può includere AppCompat, può utilizzare direttamente emoji2. Questa procedura richiede più lavoro, quindi utilizza questo metodo solo se la tua app non può utilizzare AppCompat.

Per supportare le emoji senza la libreria AppCompat:

1. Includi emoji2 e emoji2-views nel file build.gradle dell'app.

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

   Il modulo emoji2-views fornisce sottoclassi di TextView, Button e EditText che implementano EmojiCompat. Non utilizzarlo in un'app che include AppCompat, perché implementa già EmojiCompat.

2. In XML e nel codice, ovunque utilizzi TextView, EditText o Button, utilizza EmojiTextView, EmojiEditText o EmojiButton.

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

   Se includi il modulo emoji2, il sistema utilizza il fornitore di caratteri scaricabili predefinito per caricare automaticamente il carattere emoji poco dopo l'avvio dell'app. Non è necessaria alcuna configurazione aggiuntiva.

3. Per testare l'integrazione, avvia l'app su un dispositivo con Android 11 o versioni precedenti e visualizza le seguenti stringhe di test. Assicurati che tutti i caratteri vengano visualizzati correttamente.

   • 14.0: 🫠, 🫱🏼‍🫲🏿, 🫰🏽
   • 13.1: 😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
   • 13.0: 🥲, 🥷🏿, 🐻‍❄️
   • 12.1: 🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
   • 12.0: 🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

Utilizzare EmojiCompat senza widget

EmojiCompat utilizza EmojiSpan per riprodurre immagini corrette. Pertanto, deve convertire qualsiasi oggetto CharSequence in un oggetto Spanned con oggetti EmojiSpan. La classe EmojiCompat fornisce il metodo process() per convertire CharSequences in istanze Spanned. Con questo metodo, puoi chiamare process() in background e memorizzare nella cache i risultati, migliorando il rendimento della tua app.

Kotlin

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

Java

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

Utilizzare EmojiCompat per gli editor di metodi di inserimento

La classe EmojiCompat consente alle tastiere di visualizzare le emoji supportate dall'app con cui interagiscono. Gli editor di metodi di inserimento (IME) possono utilizzare il metodo getEmojiMatch() per verificare se un'istanza di EmojiCompat è in grado di visualizzare un'emoji. Questo metodo prende un CharSequence di un'emoji e restituisce true se EmojiCompat può rilevare e visualizzare l'emoji.

La tastiera può anche controllare la versione di EmojiCompat supportata dall'app per determinare quale emoji visualizzare nella tavolozza. Per controllare la versione, se disponibile, la tastiera può cercare le seguenti chiavi nel bundle EditorInfo.extras:

• EDITOR_INFO_METAVERSION_KEY: rappresenta la versione dei metadati delle emoji utilizzata dall'app. Se questa chiave non esiste, l'app non utilizza EmojiCompat.
• EDITOR_INFO_REPLACE_ALL_KEY: se la chiave esiste ed è impostata su true, l'app configura EmojiCompat per sostituire tutte le emoji, anche se sono presenti nel sistema.

Scopri di più su come configurare un'istanza di EmojiCompat.

Utilizzare le emoji nelle visualizzazioni personalizzate

Se la tua app ha visualizzazioni personalizzate che sono classi di TextView dirette o indirette, ad esempio Button, Switch o EditText, e queste visualizzazioni possono mostrare contenuti generati dagli utenti, ognuna deve implementare EmojiCompat.

La procedura varia a seconda che la tua app utilizzi la libreria AppCompat.

Aggiungere visualizzazioni personalizzate per le app con AppCompat

Se la tua app utilizza AppCompat, espandi l'implementazione di AppCompat anziché l'implementazione della piattaforma. Utilizza la seguente tabella come guida per estendere le visualizzazioni in AppCompat:

Invece di estendere…	Espandi
TextView	AppCompatTextView
EditText	AppCompatEditText
ToggleButton	AppCompatToggleButton
Switch	SwitchCompat
Button	AppCompatButton
CheckedTextView	AppCompatCheckedTextView
RadioButton	AppCompatRadioButton
CheckBox	AppCompatCheckBox
AutoCompleteTextView	AppCompatAutoCompleteTextView
MultiAutoCompleteTextView	AppCompatMultiAutoCompleteTextView

Aggiungere visualizzazioni personalizzate per le app senza AppCompat

Se la tua app non utilizza AppCompat, utilizza gli aiuti all'integrazione delle visualizzazioni nel modulo emoji2-views-helper progettati per l'utilizzo nelle visualizzazioni personalizzate. Questi sono gli aiuti utilizzati dalla libreria AppCompat per implementare il supporto delle emoji.

Completa i seguenti passaggi per supportare le visualizzazioni personalizzate per le app che non utilizzanoAppCompat.

1. Aggiungi la libreria emoji2-views-helper:

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

2. Segui le istruzioni per includere EmojiTextViewHelper o EmojiEditTextHelper nelle visualizzazioni personalizzate della tua app.

3. Testa l'integrazione avviando l'app su un dispositivo con Android 10 o versioni precedenti e visualizzando la seguente stringa di test. Assicurati che tutti i caratteri vengano visualizzati correttamente.

   • 14.0: 🫠, 🫱🏼‍🫲🏿, 🫰🏽
   • 13.1: 😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
   • 13.0: 🥲, 🥷🏿, 🐻‍❄️
   • 12.1: 🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
   • 12.0: 🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

Nota: per le app che non utilizzano AppCompat, puoi estendere le classi EmojiCompat*View o utilizzare le classi di helper di visualizzazione per l'integrazione manuale.

Funzionalità facoltative per la gestione delle emoji2

Dopo aver incluso la libreria emoji2 nella tua app, puoi aggiungere le funzionalità facoltative descritte in questa sezione.

Configura emoji2 per utilizzare un carattere diverso o un provider di caratteri scaricabili

Per configurare emoji2 in modo che utilizzi un carattere diverso o un fornitore di caratteri scaricabili, segui questi passaggi:

1. Disattiva EmojiCompatInitializer aggiungendo quanto segue al manifest:

   <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. Effettua una delle seguenti operazioni:

   • Utilizza la configurazione predefinita chiamando DefaultEmojiCompatConfiguration.create(context).

   • Crea la tua configurazione per caricare i caratteri da un'altra origine utilizzando EmojiCompat.Config. Questa classe fornisce diverse opzioni per modificare il comportamento di EmojiCompat, come descritto nella sezione seguente.

Attenzione: se disattivi la configurazione predefinita, verifica che le emoji vengano visualizzate correttamente nell'app. Chiama EmojiCompat.init poco dopo l'avvio. Puoi chiamare init() da Application.onCreate() passando LOAD_STRATEGY_MANUAL e poi chiamare EmojiCompat.load() da un thread in background.

Modificare il comportamento di EmojiCompat

Puoi utilizzare un'istanza di EmojiCompat.Config per modificare il comportamento di EmojiCompat.

L'opzione di configurazione più importante è setMetadataLoadStrategy(), che controlla quando EmojiCompat carica il carattere. Il caricamento dei caratteri inizia non appena viene chiamata la funzione EmojiCompat.load(), che attiva i download necessari. Il sistema crea un thread per il download dei caratteri, a meno che non ne fornisca uno la tua app.

LOAD_STRATEGY_MANUAL ti consente di controllare quando viene chiamato EmojiCompat.load() e LOAD_STRATEGY_DEFAULT avvia il caricamento in modo sincrono nella chiamata a EmojiCompat.init().

La maggior parte delle app utilizza LOAD_STRATEGY_MANUAL per poter controllare il thread e i tempi del caricamento dei caratteri. L'app deve essere posticipata fino a dopo la visualizzazione della prima schermata per evitare di introdurre latenza di avvio. EmojiCompatInitializer segue questa pratica e rimanda il caricamento del carattere emoji fino al riavvio della prima schermata.

Utilizza i seguenti metodi della classe di base per impostare altri aspetti della configurazione:

• setReplaceAll(): determina se EmojiCompat sostituisce tutte le emoji che trova con istanze di EmojiSpan. Per impostazione predefinita, quando EmojiCompat deduce che il sistema può visualizzare un'emoji, non la sostituisce. Se impostato su true, EmojiCompat sostituisce tutte le emoji con oggetti EmojiSpan.
• setEmojiSpanIndicatorEnabled(): indica se EmojiCompat sostituisce un'emoji con un oggetto EmojiSpan. Se impostato su true, EmojiCompat disegna uno sfondo per il EmojiSpan. Questo metodo viene utilizzato principalmente per il debug.
• setEmojiSpanIndicatorColor: imposta il colore per indicare un EmojiSpan. Il valore predefinito è GREEN.
• registerInitCallback(): informa un'app sullo stato dell'inizializzazione di EmojiCompat.

Aggiungi ascoltatori di inizializzazione

Le classi EmojiCompat e EmojiCompat.Config forniscono i metodi registerInitCallback() e unregisterInitCallback() per registrare e annullare la registrazione dei callback di inizializzazione. L'app utilizza questi callback per attendere l'inizializzazione di EmojiCompat prima di elaborare le emoji in un thread in background o in una visualizzazione personalizzata.

Per utilizzare questi metodi, crea un'istanza della classe EmojiCompat.InitCallback. Chiama questi metodi e passa l'istanza della classe EmojiCompat.InitCallback. Se l'inizializzazione è andata a buon fine, la classe EmojiCompat chiama il metodo onInitialized(). Se l'inizializzazione della libreria non va a buon fine, la classe EmojiCompat chiama il metodo onFailed().

Per controllare lo stato di inizializzazione in qualsiasi momento, chiama il metodo getLoadState(). Questo metodo restituisce uno dei seguenti valori: LOAD_STATE_LOADING, LOAD_STATE_SUCCEEDED o LOAD_STATE_FAILED.

Supporto dei caratteri in bundle con emoji2

Puoi utilizzare l'elemento emoji2-bundled per includere un carattere emoji nella tua app. Tuttavia, poiché il carattere NotoColorEmoji è superiore a 10 MB, ti consigliamo vivamente di utilizzare caratteri scaricabili nella tua app, se possibile. L'elemento emoji2-bundled è destinato alle app su dispositivi che non supportano i caratteri scaricabili.

Per utilizzare l'elemento emoji2-bundled:

1. Includi gli elementi emoji2-bundled e emoji2:

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

   Attenzione: l'inclusione dell'elemento emoji2-bundled disattivaEmojiCompatInitializer, pertanto la tua app deve chiamare EmojiCompat.init().

2. Configura emoji2 per utilizzare la configurazione in bundle:

   Kotlin

   EmojiCompat.init(BundledEmojiCompatConfig(context))

   Java

   EmojiCompat.init(new BundledEmojiCompatConfig(context));

3. Testa l'integrazione seguendo i passaggi precedenti per includere emojicompat con o senza AppCompat. Assicurati che la stringa di test sia visualizzata correttamente.

   • 14.0: 🫠, 🫱🏼‍🫲🏿, 🫰🏽
   • 13.1: 😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
   • 13.0: 🥲, 🥷🏿, 🐻‍❄️
   • 12.1: 🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
   • 12.0: 🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

Impatto della configurazione automatica di EmojiCompat

Il sistema applica la configurazione predefinita utilizzando la libreria di avvio,EmojiCompatInitializer e DefaultEmojiCompatConfig.

Dopo che la prima attività viene ripresa nell'app, l'inizializzatore pianifica il caricamento dei caratteri emoji. Questo breve ritardo consente all'app di visualizzare i contenuti iniziali senza alcuna potenziale latenza dovuta al caricamento dei caratteri in un thread in background.

DefaultEmojiCompatConfig cerca un fornitore di caratteri scaricabili installato sul sistema che implementa l'interfaccia EmojiCompat, ad esempio i servizi Google Play. Sui dispositivi con Google Play Services, il carattere viene caricato utilizzando Google Play Services.

Nota: la configurazione predefinita di emoji2 utilizza i caratteri scaricabili per recuperare un file di caratteri compatibile. Sui dispositivi con Google Play Services, l'app invia questa query all'avvio a Google Play Services. La richiesta di un carattere viene registrata da Google Play Services e dai caratteri scaricabili.

L'inizializzatore crea un thread in background per caricare il carattere emoji e il download del carattere può richiedere fino a 10 secondi prima del timeout. Dopo aver scaricato il carattere, sono necessari circa 150 millisecondi in un thread in background per inizializzare EmojiCompat.

Ritarda l'inizializzazione di EmojiCompat, anche se disattivi EmojiCompatInitializer. Se configuri manualmenteEmojiCompat, chiama EmojiCompat.load() dopo che viene visualizzata la prima schermata dell'app per evitare conflitti in background con il caricamento della prima schermata.

Dopo il caricamento, EmojiCompat utilizza circa 300 KB di RAM per contenere i metadati delle emoji.