Compatibilità con emoji

Attenzione: a partire dalla fine del 2021, la libreria androidx.emoji:emoji è stata ritirata a favore di androidx.emoji2:emoji2, che offre l'integrazione in androidx.appcompat.

Per supportare le emoji moderne e semplificare la compatibilità con le versioni precedenti di Android, ti consigliamo di eseguire la migrazione alla libreria androidx.emoji2:emoji2. Per informazioni dettagliate sull'implementazione, consulta Supportare le emoji moderne.

Lo scopo della libreria di supporto EmojiCompat è mantenere aggiornati i dispositivi Android con le emoji più recenti. Impedisce all'app di mostrare i caratteri emoji mancanti sotto forma di ☐, il che indica che il dispositivo non dispone di un carattere per visualizzare il testo. Se utilizzi la libreria di supporto EmojiCompat, gli utenti della tua app non devono attendere gli aggiornamenti del sistema operativo Android per ricevere le emoji più recenti.

Figura 1. Confronto delle emoji

Consulta le seguenti risorse correlate:

• App di esempio di compatibilità con le emoji Java | Kotlin

Come funziona EmojiCompat?

La libreria di supporto EmojiCompat fornisce classi per implementare il supporto delle emoji compatibili con le versioni precedenti sui dispositivi con Android 4.4 (livello API 19) e versioni successive. Puoi configurare EmojiCompat con caratteri in bundle o scaricabili. Per ulteriori informazioni sulla configurazione, consulta le seguenti sezioni:

• Configurazione dei caratteri scaricabili
• Configurazione dei caratteri in bundle

EmojiCompat identifica le emoji per un determinato CharSequence, le sostituisce con EmojiSpans, se necessario, e infine esegue il rendering dei glifi emoji. La Figura 2 mostra la procedura.

Figura 2. Procedura EmojiCompat

Configurazione dei caratteri scaricabili

La configurazione dei caratteri scaricabili utilizza la funzionalità della raccolta di supporto dei caratteri scaricabili per scaricare un carattere emoji. Aggiorna inoltre i metadati necessari per le emoji che la libreria di supporto EmojiCompat deve mantenere aggiornati in base alle ultime versioni della specifica Unicode.

Aggiunta della dipendenza dalla libreria di supporto

Per utilizzare la libreria di supporto EmojiCompat, devi modificare le dipendenze del classpath del progetto dell'app all'interno del tuo ambiente di sviluppo.

Per aggiungere una libreria di supporto al progetto dell'applicazione:

1. Apri il file build.gradle della tua applicazione.
2. Aggiungi la libreria di supporto alla sezione dependencies.

Groovy

dependencies {
    ...
    implementation "androidx.emoji:emoji:28.0.0"
}

Kotlin

dependencies {
    ...
    implementation("androidx.emoji:emoji:28.0.0")
}

Inizializzazione della configurazione dei caratteri scaricabili

Devi inizializzare EmojiCompat per caricare i metadati e il carattere. Poiché l'inizializzazione può richiedere del tempo, la procedura di inizializzazione viene eseguita in un thread in background.

Per inizializzare EmojiCompat con la configurazione dei caratteri scaricabili, segui questi passaggi:

1. Crea un'istanza della classe FontRequest e fornisci l'autorità del fornitore di caratteri, il pacchetto del fornitore di caratteri, la query dei caratteri e un elenco di insiemi di hash per il certificato. Per ulteriori informazioni su FontRequest, consulta la sezione Utilizzare i caratteri scaricabili tramite programmazione nella documentazione relativa ai caratteri scaricabili.
2. Crea un'istanza di FontRequestEmojiCompatConfig e fornisci istanze di Context e FontRequest.
3. Inizializza EmojiCompat chiamando il metodo init() e passa l'istanza di FontRequestEmojiCompatConfig.

Kotlin

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        val fontRequest = FontRequest(
                "com.example.fontprovider",
                "com.example",
                "emoji compat Font Query",
                CERTIFICATES
        )
        val config = FontRequestEmojiCompatConfig(this, fontRequest)
        EmojiCompat.init(config)
    }
}

Java

public class MyApplication extends Application {
  @Override
   public void onCreate() {
     super.onCreate();
     FontRequest fontRequest = new FontRequest(
       "com.example.fontprovider",
       "com.example",
       "emoji compat Font Query",
       CERTIFICATES);
     EmojiCompat.Config config = new FontRequestEmojiCompatConfig(this, fontRequest);
     EmojiCompat.init(config);
   }
}

4. Utilizza i widget EmojiCompat nei file XML di layout. Se utilizzi AppCompat, consulta la sezione Utilizzare i widget EmojiCompat con AppCompat.

<android.support.text.emoji.widget.EmojiTextView
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

<android.support.text.emoji.widget.EmojiEditText
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

<android.support.text.emoji.widget.EmojiButton
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

Per ulteriori informazioni su come configurare EmojiCompat con la configurazione del carattere scaricabile, vai all'app di esempio Emoji Compatibility Java | Kotlin.

Componenti della raccolta

Figura 3. Componenti della libreria nel processo EmojiCompat

Widget: EmojiEditText, EmojiTextView, EmojiButton

Implementazioni dei widget predefinite da utilizzare EmojiCompat con TextView, EditText e Button.

EmojiCompat

Interfaccia pubblica principale della libreria di assistenza. Esegue tutte le chiamate esterne e si coordina con le altre parti del sistema.

EmojiCompat.Config

Configura l'istanza singleton da creare.

EmojiSpan

Una sottoclasse di ReplacementSpan che sostituisce il carattere (le sequenze) e esegue il rendering del glifo.

Carattere EmojiCompat

EmojiCompat utilizza un carattere per visualizzare emoji. Questo carattere è una versione modificata del carattere Emoji di Android. Il carattere viene modificato come segue:

• Per garantire la compatibilità con le versioni precedenti per il rendering delle emoji, tutti i caratteri emoji sono rappresentati da un singolo punto di codice Unicode nell'area di uso privato aggiuntiva di Unicode, iniziando con U+F0001.
• I metadati emoji aggiuntivi vengono inseriti in un formato binario nel carattere e analizzati in fase di esecuzione da EmojiCompat. I dati sono incorporati nella tabella meta del carattere, con il tag privato Emji.

Opzioni di configurazione

Puoi utilizzare l'istanza EmojiCompat per modificare il comportamento di EmojiCompat. Puoi utilizzare i seguenti metodi della classe di base per impostare la configurazione:

• setReplaceAll(): determina se EmojiCompat deve sostituire tutte le emoji che trova con EmojiSpans. Per impostazione predefinita, EmojiCompat fa del suo meglio per capire se il sistema può visualizzare un'emoji e non le sostituisce. Se impostato su true, EmojiCompat sostituisce tutte le emoji che trova con EmojiSpans.
• setEmojiSpanIndicatorEnabled(): indica se EmojiCompat ha sostituito un'emoji con un'altra EmojiSpan. Se impostato su true, EmojiCompat disegna uno sfondo per il EmojiSpan. Questo metodo viene utilizzato principalmente per scopi di debug.
• setEmojiSpanIndicatorColor(): imposta il colore per indicare un EmojiSpan. Il valore predefinito è GREEN.
• registerInitCallback: informa l'app sullo stato dell'inizializzazione di EmojiCompat.

Kotlin

val config = FontRequestEmojiCompatConfig(...)
        .setReplaceAll(true)
        .setEmojiSpanIndicatorEnabled(true)
        .setEmojiSpanIndicatorColor(Color.GREEN)
        .registerInitCallback(object: EmojiCompat.InitCallback() {
            ...
        })

Java

EmojiCompat.Config config = new FontRequestEmojiCompatConfig(...)
       .setReplaceAll(true)
       .setEmojiSpanIndicatorEnabled(true)
       .setEmojiSpanIndicatorColor(Color.GREEN)
       .registerInitCallback(new InitCallback() {...})

Aggiunta di ascoltatori di inizializzazione

Le classi EmojiCompat e EmojiCompat forniscono metodi registerInitCallback() e unregisterInitCallback() per registrare un callback di inizializzazione. Per utilizzare questi metodi, crea un'istanza della classe EmojiCompat.InitCallback. Chiama questi metodi e passa l'istanza della classe EmojiCompat.InitCallback. Quando l'inizializzazione della libreria di supporto EmojiCompat è 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(). Restituisce uno dei seguenti valori: LOAD_STATE_LOADING, LOAD_STATE_SUCCEEDED o LOAD_STATE_FAILED.

Utilizzare EmojiCompat con i widget AppCompat

Se utilizzi AppCompat widgets, puoi utilizzare i widget EmojiCompat che si estendono da AppCompat widgets.

1. Aggiungi la libreria di supporto alla sezione delle dipendenze.

   Groovy

   dependencies {
       ...
       implementation "androidx.emoji:emoji-bundled:$version"
   }

   Kotlin

         dependencies {
             implementation("androidx.emoji:emoji-appcompat:$version")
         }
         

   Groovy

         dependencies {
             implementation "androidx.emoji:emoji-appcompat:$version"
         }
         

2. Utilizza i widget EmojiCompat AppCompat Widget nei file XML di layout.

<android.support.text.emoji.widget.EmojiAppCompatTextView
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

<android.support.text.emoji.widget.EmojiAppCompatEditText
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

<android.support.text.emoji.widget.EmojiAppCompatButton
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

Configurazione dei caratteri in bundle

La libreria di supporto EmojiCompat è disponibile anche in una versione del carattere in bundle. Questo pacchetto include il carattere con i metadati incorporati. Il pacchetto include anche un BundledEmojiCompatConfig che utilizza AssetManager per caricare i metadati e i caratteri.

Nota: le dimensioni del carattere sono espresse in più megabyte.

Aggiunta della dipendenza dalla libreria di supporto

Per utilizzare la EmojiCompat libreria di supporto con la configurazione dei caratteri in bundle, devi modificare le dipendenze del percorso di classe del progetto dell'app nell'ambiente di sviluppo.

Per aggiungere una libreria di supporto al progetto dell'applicazione:

1. Apri il file build.gradle della tua applicazione.
2. Aggiungi la libreria di supporto alla sezione dependencies.

Groovy

dependencies {
    ...
    implementation "androidx.emoji:emoji:28.0.0"
}

Kotlin

dependencies {
    ...
    implementation("androidx.emoji:emoji:28.0.0")
}

Utilizzo dei caratteri in bundle per configurare EmojiCompat

Per utilizzare i caratteri in bundle per configurare EmojiCompat, segui questi passaggi:

1. Utilizza BundledEmojiCompatConfig per creare un'istanza di EmojiCompat e fornire un'istanza di Context.
2. Chiama il metodo init() per inizializzare EmojiCompat e passa l'istanza di BundledEmojiCompatConfig.

Kotlin

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        val config = BundledEmojiCompatConfig(this)
        EmojiCompat.init(config)
    }
}

Java

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        EmojiCompat.Config config = new BundledEmojiCompatConfig(this);
        EmojiCompat.init(config);
        ...
    }
}

Utilizzare EmojiCompat senza widget

EmojiCompat utilizza EmojiSpan per eseguire il rendering di immagini corrette. Pertanto, deve convertire qualsiasi CharSequence in istanze Spanned con EmojiSpans. La classe EmojiCompat fornisce un metodo per convertire CharSequences in istanze Spanned con EmojiSpans. Con questo metodo, puoi elaborare e memorizzare nella cache le istanze elaborate anziché la stringa non elaborata, il che migliora le prestazioni dell'applicazione.

Kotlin

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

Java

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

Utilizzo di EmojiCompat per gli IME

Utilizzando la libreria di supporto EmojiCompat, le tastiere possono visualizzare le emoji supportate dall'applicazione con cui interagiscono. Gli IME possono utilizzare il metodo hasEmojiGlyph() per verificare se EmojiCompat è in grado di eseguire il rendering di 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 della biblioteca di supporto EmojiCompat supportata dall'app per determinare quali emoji visualizzare nella tavolozza. Per controllare la versione, se disponibile, la tastiera deve verificare se le seguenti chiavi esistono nel EditorInfo.extras bundle:

• EDITOR_INFO_METAVERSION_KEY

Se la chiave esiste nel bundle, il valore 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, indica che l'app ha chiamato il metodo SetReplaceAll(). Per ulteriori informazioni sulla configurazione di EmojiCompat, consulta la sezione Opzioni di configurazione.

Dopo aver ricevuto le chiavi nel bundle EditorInfo.extras, la tastiera può utilizzare il metodo hasEmojiGlyph(), dove metadataVersion è il valore per EDITOR_INFO_METAVERSION_KEY, per verificare se l'app può visualizzare un'emoji specifica.

Utilizzo di EmojiCompat con widget personalizzati

Puoi sempre utilizzare il metodo process() per eseguire la preelaborazione del CharSequence nella tua app e aggiungerlo ad qualsiasi widget in grado di eseguire il rendering di istanze Spanned, ad esempioTextView. Inoltre, EmojiCompat fornisce le seguenti classi di helper per i widget per consentirti di arricchire i widget personalizzati con il supporto delle emoji con minimo sforzo.

• EmojiTextViewHelper
• EmojiEditTextHelper

TextView di esempio

Kotlin

class MyTextView(context: Context) : AppCompatTextView(context) {

    private val emojiTextViewHelper: EmojiTextViewHelper by lazy(LazyThreadSafetyMode.NONE) {
        EmojiTextViewHelper(this).apply {
            updateTransformationMethod()
        }
    }

    override fun setFilters(filters: Array<InputFilter>) {
        super.setFilters(emojiTextViewHelper.getFilters(filters))
    }

    override fun setAllCaps(allCaps: Boolean) {
        super.setAllCaps(allCaps)
        emojiTextViewHelper.setAllCaps(allCaps)
    }
}

Java

public class MyTextView extends AppCompatTextView {
   ...
   public MyTextView(Context context) {
       super(context);
       init();
   }
   ...
   private void init() {
       getEmojiTextViewHelper().updateTransformationMethod();
   }

   @Override
   public void setFilters(InputFilter[] filters) {
       super.setFilters(getEmojiTextViewHelper().getFilters(filters));
   }

   @Override
   public void setAllCaps(boolean allCaps) {
       super.setAllCaps(allCaps);
       getEmojiTextViewHelper().setAllCaps(allCaps);
   }

   private EmojiTextViewHelper getEmojiTextViewHelper() {
       ...
   }
}

EditText di esempio

Kotlin

class MyEditText(context: Context) : AppCompatEditText(context) {

    private val emojiEditTextHelper: EmojiEditTextHelper by lazy(LazyThreadSafetyMode.NONE) {
        EmojiEditTextHelper(this).also {
            super.setKeyListener(it.getKeyListener(keyListener))
        }
    }

    override fun setKeyListener(input: KeyListener?) {
        input?.also {
            super.setKeyListener(emojiEditTextHelper.getKeyListener(it))
        }
    }

    override fun onCreateInputConnection(outAttrs: EditorInfo): InputConnection {
        val inputConnection: InputConnection = super.onCreateInputConnection(outAttrs)
        return emojiEditTextHelper.onCreateInputConnection(
                inputConnection,
                outAttrs
        ) as InputConnection
    }
}

Java

public class MyEditText extends AppCompatEditText {
   ...
   public MyEditText(Context context) {
       super(context);
       init();
   }
   ...
   private void init() {
       super.setKeyListener(getEmojiEditTextHelper().getKeyListener(getKeyListener()));
   }

   @Override
   public void setKeyListener(android.text.method.KeyListener keyListener) {
       super.setKeyListener(getEmojiEditTextHelper().getKeyListener(keyListener));
   }

   @Override
   public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
       InputConnection inputConnection = super.onCreateInputConnection(outAttrs);
       return getEmojiEditTextHelper().onCreateInputConnection(inputConnection, outAttrs);
   }

   private EmojiEditTextHelper getEmojiEditTextHelper() {
       ...
   }
}

Domande frequenti

• Come faccio ad avviare il download dei caratteri?

I caratteri emoji vengono scaricati alla prima richiesta, se non esistono sul dispositivo. La pianificazione dei download è trasparente per l'app.

• Quanto tempo è necessario per l'inizializzazione?

Dopo aver scaricato il carattere, sono necessari circa 150 millisecondi per inizializzare EmojiCompat.

• Quanta memoria utilizza la libreria di supporto EmojiCompat?

Attualmente, la struttura di dati per trovare l'emoji viene caricata nella memoria dell'app e utilizza circa 200 KB.

• Posso utilizzare EmojiCompat per un TextView personalizzato?

Sì. EmojiCompat fornisce classi di assistenza per i widget personalizzati. È anche possibile eseguire la preelaborazione di una determinata stringa e convertirla in Spanned. Per ulteriori informazioni sulle classi di helper per i widget, consulta la sezione Utilizzare EmojiCompat con i widget personalizzati.

• Cosa succede se aggiungo widget nei file XML di layout su dispositivi con Android 4.4 (livello API 19) o versioni precedenti?

Puoi includere la EmojiCompat libreria di supporto o i relativi widget nelle tue applicazioni che supportano i dispositivi con Android 4.4 (livello API 19) o versioni precedenti. Tuttavia, se un dispositivo funziona su una versione di Android precedente al livello API 19, EmojiCompat e i relativi widget sono in stato "Nessuna operazione". Ciò significa che EmojiTextView si comporta esattamente come un normale TextView. EmojiCompat. Immediatamente assume uno stato LOAD_STATE_SUCCEEDED quando chiami il metodo init().

Risorse aggiuntive

Per ulteriori informazioni sull'utilizzo della libreria EmojiCompat, guarda EmojiCompat.