Supporto delle emoji moderne

Il set standard di emoji viene aggiornato ogni anno da Unicode, in quanto l'utilizzo delle emoji sta aumentando rapidamente per tutti i tipi di app.

Se la tua app mostra contenuti internet o fornisce input di testo, consigliamo vivamente di supportare i caratteri emoji più recenti. In caso contrario, le emoji successive potrebbero essere visualizzate come una piccola casella quadrata denominata tofu (☐) o altre sequenze di emoji visualizzate in modo errato.

Le versioni Android 11 (livello API 30) e precedenti non possono aggiornare il carattere delle emoji, quindi le app che le visualizzano in queste versioni devono essere aggiornate manualmente.

Di seguito sono riportati alcuni esempi di emoji moderne.

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

Supporto delle emoji in Compose

BOM marzo 2023 (Compose UI 1.4) offre il supporto per la versione più recente di emoji, inclusa la compatibilità con le versioni precedenti di Android fino all'API 21. In questa pagina viene spiegato come configurare le emoji moderne nel sistema di visualizzazione. Per saperne di più, visita 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 a scopo di test.

Usa AppCompat per supportare le ultime emoji

AppCompat 1.4 include il supporto delle emoji.

Per usare AppCompat a supporto delle emoji, procedi nel seguente modo:

1. Controlla che il modulo dipende dalla libreria AppCompat versione 1.4.0-alpha01 o successiva.

   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: 🦩, 🦻🏿, 👩🏼 🤝 👩🏻

La tua 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, la tua app potrebbe mostrare tofu anziché l'emoji corretta, anche se aggiungi la raccolta AppCompat. Di seguito sono riportate alcune possibili spiegazioni e soluzioni.

Stai eseguendo l'app su un dispositivo flash di recente o un nuovo emulatore

Cancella i dati di Google Play Services dell'app per cancellare l'eventuale memorizzazione nella cache dei caratteri che potrebbe verificarsi durante l'avvio. In genere questa operazione risolve il problema dopo alcune ore.

Per cancellare i dati dell'app, svolgi i seguenti passaggi:

1. Apri Impostazioni sul 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 AppCompat correlata al testo

Ciò può verificarsi se non estendi AppCompatActivity o se crei un'istanza di una vista nel codice, ad esempio TextView. Controlla quanto segue.

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

AppCompatActivity gonfia automaticamente AppCompatTextView al posto di TextView quando gonfia il codice XML, quindi non devi aggiornare il file XML.

Il telefono di prova non supporta i caratteri scaricabili

Verifica che DefaultEmojiCompatConfig.create restituisca una configurazione non null.

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

Se utilizzi un emulatore in un livello API precedente, potresti dover aggiornare i servizi Google Play in bundle per emoji2 al fine di trovare il fornitore di caratteri. Per farlo, accedi al Google Play Store dall'emulatore.

Per verificare che sia installata una versione compatibile:

1. Esegui questo comando:

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

2. Verifica che il valore versionCode sia superiore a 211200000.

Supporta emoji senza AppCompat

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

Per supportare le emoji senza la raccolta AppCompat:

1. Nel file build.gradle dell'app, includi emoji2 e emoji2-views.

   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 usarlo in un'app che include AppCompat, perché implementa già EmojiCompat.

2. In XML e codice, ovunque usi TextView, EditText o Button, usa invece EmojiTextView, EmojiEditText o EmojiButton.

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

   Includendo il modulo emoji2, il sistema utilizza il provider di caratteri scaricabili predefinito per caricare automaticamente il carattere emoji poco dopo l'avvio dell'app. Non sono necessarie ulteriori configurazioni.

3. Per testare l'integrazione, avvia l'app su un dispositivo con Android 11 o versioni precedenti che mostra 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 visualizzare le 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, per migliorare le prestazioni dell'app.

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

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

Utilizzare EmojiCompat per gli editor dei metodi di inserimento

La classe EmojiCompat consente alle tastiere di visualizzare l'emoji supportata dall'app con cui stanno interagendo. Gli editor dei metodi di input (IME) possono utilizzare il metodo getEmojiMatch() per verificare se un'istanza di EmojiCompat è in grado di eseguire il rendering di un'emoji. Questo metodo prende l'elemento CharSequence di un'emoji e restituisce true se EmojiCompat è in grado di 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 i seguenti tasti nel bundle EditorInfo.extras:

• EDITOR_INFO_METAVERSION_KEY: rappresenta la versione dei metadati delle emoji utilizzate dall'app. Se questa chiave non esiste, significa che 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 sottoclassi dirette o indirette di TextView, ad esempio Button, Switch o EditText, e queste viste possono mostrare contenuti generati dagli utenti, ciascuna deve implementare EmojiCompat.

La procedura varia a seconda che la tua app utilizzi o meno la raccolta AppCompat.

Aggiungi visualizzazioni personalizzate per le app con AppCompat

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

Aggiungi visualizzazioni personalizzate per le app senza AppCompat

Se la tua app non utilizza AppCompat, usa gli assistenti per l'integrazione delle visualizzazioni nel modulo emoji2-views-helper, progettati per essere utilizzati nelle viste personalizzate. Questi sono gli assistenti utilizzati dalla raccolta AppCompat per implementare il supporto delle emoji.

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

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: 🦩, 🦻🏿, 👩🏼 🤝 👩🏻

Funzionalità facoltative per la gestione di 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 fornitore di caratteri scaricabile

Per configurare emoji2 in modo che utilizzi un carattere diverso o un fornitore di caratteri scaricabile, procedi nel seguente modo:

1. Disattiva EmojiCompatInitializer aggiungendo quanto segue al file 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. Svolgere 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. Questo corso offre diverse opzioni per modificare il comportamento di EmojiCompat, come descritto nella sezione seguente.

Modifica 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 del carattere inizia non appena viene chiamato EmojiCompat.load() e attiva i download necessari. Il sistema crea un thread per il download del carattere, a meno che la tua app non ne fornisca uno.

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

La maggior parte delle app utilizza LOAD_STRATEGY_MANUAL per controllare il thread e la tempistica del caricamento dei caratteri. L'app deve rimandare fino a dopo la visualizzazione della prima schermata per evitare l'introduzione della latenza di avvio. EmojiCompatInitializer segue questa pratica e rinvia il caricamento del carattere emoji fino al riavvio della prima schermata.

Utilizza i seguenti metodi della classe 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 EmojiSpan oggetti.
• setEmojiSpanIndicatorEnabled(): indica se EmojiCompat sostituisce un'emoji con un oggetto EmojiSpan. Se impostato su true, EmojiCompat disegna uno sfondo per EmojiSpan. Questo metodo viene utilizzato principalmente per scopi di debug.
• setEmojiSpanIndicatorColor: imposta il colore per indicare un EmojiSpan. Il valore predefinito è GREEN.
• registerInitCallback(): informa un'app sullo stato dell'inizializzazione di EmojiCompat.

Aggiungi listener di inizializzazione

Le classi EmojiCompat e EmojiCompat.Config forniscono i metodi registerInitCallback() e unregisterInitCallback() per registrare e annullare la registrazione dei callback di inizializzazione. La tua 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. Richiama questi metodi e passa all'istanza della classe EmojiCompat.InitCallback. Se l'inizializzazione va a buon fine, la classe EmojiCompat chiama il metodo onInitialized(). Se la libreria non viene inizializzata, 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 raggruppati con emoji2

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

Per utilizzare l'artefatto emoji2-bundled:

1. Includi elementi emoji2-bundled e emoji2:

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

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 venga visualizzata correttamente.

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

Impatto della configurazione automatica EmojiCompat

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

Dopo che la prima attività riprende nell'app, l'inizializzatore pianifica il caricamento dei caratteri emoji. Questo breve ritardo consente alla tua app di visualizzare i contenuti iniziali senza potenziale latenza a causa del caricamento dei caratteri in un thread in background.

DefaultEmojiCompatConfig cerca un provider di caratteri scaricabili installato dal sistema che implementa l'interfaccia EmojiCompat, come Google Play Services. Sui dispositivi con Google Play Services, il carattere viene caricato utilizzando Google Play Services.

L'inizializzatore crea un thread in background per caricare il carattere dell'emoji; il download del carattere può richiedere fino a 10 secondi prima del timeout. Una volta scaricato il carattere, l'inizializzazione di EmojiCompat richiede circa 150 millisecondi su un thread in background.

Rimanda l'inizializzazione di EmojiCompat, anche se disattivi EmojiCompatInitializer. Se configuri manualmente EmojiCompat, chiama EmojiCompat.load() dopo aver visualizzato la prima schermata dell'app per evitare conflitti in background con il primo caricamento della schermata.

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