Compatibilità con emoji

La raccolta di assistenza EmojiCompat mira a mantenere i dispositivi Android aggiornati con le emoji più recenti. Impedisce all'app di mostrare caratteri emoji mancanti sotto forma di Negativo, che indica che il dispositivo non dispone di un carattere per visualizzare il testo. Grazie alla libreria di supporto EmojiCompat, gli utenti delle tue app non dovranno aspettare gli aggiornamenti del sistema operativo Android per ricevere le emoji più recenti.

Dispositivi che mostrano emoji
Figura 1. Confronto di emoji

Fai riferimento alle seguenti risorse correlate:

  • Esempio di app per la compatibilità delle emoji Java | Kotlin

Come funziona EmojiCompat?

La libreria di supporto EmojiCompat fornisce classi per implementare il supporto di 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 maggiori informazioni sulla configurazione, consulta le sezioni seguenti:

EmojiCompat identifica le emoji per un determinato CharSequence, le sostituisce con EmojiSpans, se necessario, e infine visualizza i glifi delle emoji. La Figura 2 illustra il processo.

Procedura EmojiCompat
Figura 2. Procedura EmojiCompat

Configurazione dei caratteri scaricabili

La configurazione dei caratteri scaricabili utilizza la funzionalità della libreria di supporto dei caratteri scaricabili per scaricare un carattere emoji. Inoltre, aggiorna i metadati delle emoji necessari per la libreria di supporto di EmojiCompat per stare al passo con le versioni più recenti della specifica Unicode.

Aggiunta della dipendenza dalla libreria di supporto

Per utilizzare la libreria di supporto EmojiCompat, devi modificare le dipendenze 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.

trendy

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, il processo di inizializzazione viene eseguito su un thread in background.

Per inizializzare EmojiCompat con la configurazione dei caratteri scaricabili, svolgi i seguenti passaggi:

  1. Crea un'istanza della classe FontRequest e fornisci l'autorità del fornitore del carattere, il pacchetto del provider di caratteri, la query sui caratteri e un elenco di set di hash per il certificato. Per maggiori informazioni su FontRequest, consulta la sezione Utilizzare i caratteri scaricabili in modo programmatico nella documentazione relativa ai caratteri scaricabili.
  2. Crea un'istanza di FontRequestEmojiCompatConfig e fornisci le istanze di Context e FontRequest.
  3. Inizializza EmojiCompat chiamando il metodo init() e passa l'istanza di FontRequestEmojiCompatConfig.
  4. 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);
       }
    }
    
  5. Utilizza EmojiCompat widget nei file XML di layout. Se usi AppCompat, consulta la sezione Utilizzare i widget EmojiCompat con AppCompat.
  6. <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 maggiori informazioni su come configurare EmojiCompat con la configurazione dei caratteri scaricabili, vai all'app di esempio per la compatibilità delle emoji Java | Kotlin.

Componenti della libreria

Componenti della raccolta nel processo EmojiCompat
Figura 3. Componenti della raccolta nel processo EmojiCompat
Widget: EmojiEditText, EmojiTextView, EmojiButton
Implementazioni predefinite dei widget per utilizzare EmojiCompat con TextView, EditText e Button.
EmojiCompat
Piattaforma pubblica principale della libreria di supporto. Esegue tutte le chiamate esterne e le coordinate con le altre parti del sistema.
EmojiCompat.Config
Configura l'istanza singleton da creare.
EmojiSpan
Una sottoclasse ReplacementSpan che sostituisce il carattere (sequenze) e mostra il glifo.
Carattere EmojiCompat
EmojiCompat utilizza un carattere per visualizzare le emoji. Questo carattere è una versione modificata del caratteri Android Emoji. Il carattere viene modificato come segue:
  • Per garantire la compatibilità con le versioni precedenti delle emoji, tutti i caratteri delle emoji sono rappresentati con un singolo punto di codice Unicode nell'area A (Supplemental Private Use Area-A) di Unicode che inizia con U+F0001.
  • Gli altri metadati delle emoji vengono inseriti in formato binario nel carattere e analizzati durante l'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 base per impostare la configurazione:

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 dei listener di inizializzazione

Le classi EmojiCompat e EmojiCompat forniscono i metodi registerInitCallback() e unregisterInitCallback() per registrare un callback di inizializzazione. Per utilizzare questi metodi, crea un'istanza della classe EmojiCompat.InitCallback. Richiama questi metodi e passa l'istanza della classe EmojiCompat.InitCallback. Se l'inizializzazione della libreria di assistenza EmojiCompat ha esito positivo, 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 verificare 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 usi AppCompat widgets, puoi usare EmojiCompat widget che si estendono da AppCompat widgets.

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

    trendy

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

    Kotlin

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

    trendy

          dependencies {
              implementation "androidx.emoji:emoji-appcompat:$version"
          }
          
  2. Utilizza EmojiCompat widget AppCompat Widget nei file XML di layout.
  3. <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 di caratteri raggruppati

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

Nota: le dimensioni del carattere sono espresse in diversi megabyte.

Aggiunta della dipendenza dalla libreria di supporto

Per utilizzare la libreria di supporto EmojiCompat con la configurazione dei caratteri in bundle, devi modificare le dipendenze classpath del progetto dell'app all'interno dell'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.

trendy

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

Kotlin

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

Utilizzo di caratteri raggruppati 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. Richiama il metodo init() per inizializzare EmojiCompat e passare 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);
        ...
    }
}

Usare EmojiCompat senza widget

EmojiCompat utilizza EmojiSpan per visualizzare le immagini corrette. Di conseguenza, deve convertire qualsiasi elemento CharSequence in Spanned istanza 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, migliorando le prestazioni dell'applicazione.

Kotlin

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

Java

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

Utilizzare EmojiCompat per gli IME

Utilizzando la libreria di supporto EmojiCompat, le tastiere possono visualizzare le emoji supportate dall'applicazione con cui stanno interagendo. Gli IME possono usare il metodo hasEmojiGlyph() per verificare se EmojiCompat è in grado di visualizzare un'emoji. Questo metodo prende un CharSequence di un'emoji e restituisce true se EmojiCompat è in grado di rilevare e visualizzare l'emoji.

La tastiera può anche controllare la versione della libreria di supporto EmojiCompat supportata dall'app per determinare quali emoji visualizzare nella tavolozza. Per verificare la versione, se disponibile, la tastiera deve controllare se i seguenti tasti esistono nel bundle EditorInfo.extras:

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

Utilizzare EmojiCompat con widget personalizzati

Puoi sempre utilizzare il metodo process() per pre-elaborare CharSequence nella tua app e aggiungerlo a qualsiasi widget in grado di eseguire il rendering delle istanze Spanned, ad esempio TextView. Inoltre, EmojiCompat offre le seguenti classi helper per i widget per consentirti di arricchire i tuoi widget personalizzati con il supporto delle emoji con il minimo sforzo.

Visualizzazione testo 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() {
       ...
   }
}
Testo di modifica 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 delle 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 usa la raccolta supportata da EmojiCompat?
  • Attualmente, la struttura dei 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 supporto per i widget personalizzati. È anche possibile pre-elaborare una determinata stringa e convertirla in Spanned. Per ulteriori informazioni sulle classi helper dei widget, consulta la sezione Utilizzare EmojiCompat con widget personalizzati.

  • Che cosa succede se aggiungo widget nei file XML di layout su dispositivi che eseguono Android 4.4 (livello API 19) o versioni precedenti?
  • Puoi includere la libreria di supporto EmojiCompat o i relativi widget nelle applicazioni che supportano i dispositivi con Android 4.4 (livello API 19) o versioni precedenti. Tuttavia, se un dispositivo esegue 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; diventa immediatamente lo stato LOAD_STATE_SUCCEEDED quando chiami il metodo init().

Risorse aggiuntive

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