Compatibilité avec les emoji

Attention:Depuis fin 2021, la bibliothèque androidx.emoji:emoji est obsolète et remplacée par androidx.emoji2:emoji2, qui permet l'intégration dans androidx.appcompat.

Pour prendre en charge les emoji modernes et simplifier la rétrocompatibilité avec les versions antérieures d'Android, nous vous recommandons de migrer vers la bibliothèque androidx.emoji2:emoji2. Pour savoir comment procéder, consultez la section Compatibilité avec les emoji modernes.

La bibliothèque d'assistance EmojiCompat vise à mettre à jour les appareils Android avec les derniers emoji. Cela empêche votre application d'afficher les caractères emoji manquants sous la forme de ☐, ce qui indique que votre appareil ne dispose pas de police pour afficher le texte. En utilisant la bibliothèque d'assistance EmojiCompat, les utilisateurs de votre application n'ont pas besoin d'attendre les mises à jour de l'OS Android pour obtenir les derniers emoji.

Figure 1. Comparaison des emoji

Consultez les ressources associées suivantes :

• Application exemple de compatibilité avec les emoji Java | Kotlin

Comment fonctionne EmojiCompat ?

La bibliothèque d'assistance EmojiCompat fournit des classes permettant d'implémenter la compatibilité ascendante des emoji sur les appareils exécutant Android 4.4 (niveau d'API 19) ou version ultérieure. Vous pouvez configurer EmojiCompat avec des polices groupées ou téléchargeables. Pour en savoir plus sur la configuration, consultez les sections suivantes:

• Configuration des polices téléchargeables
• Configuration des polices groupées

EmojiCompat identifie les emoji pour un CharSequence donné, les remplace par EmojiSpans, le cas échéant, et affiche enfin les glyphes emoji. La figure 2 illustre ce processus.

Figure 2. Processus EmojiCompat

Configuration des polices téléchargeables

La configuration des polices téléchargeables utilise la fonctionnalité de bibliothèque de compatibilité des polices téléchargeables pour télécharger une police emoji. Il met également à jour les métadonnées d'emoji nécessaires que la bibliothèque d'assistance EmojiCompat doit utiliser pour suivre les dernières versions de la spécification Unicode.

Ajouter une dépendance de bibliothèque d'assistance

Pour utiliser la bibliothèque de compatibilité EmojiCompat, vous devez modifier les dépendances de chemin de classe de votre projet d'application dans votre environnement de développement.

Pour ajouter une bibliothèque d'assistance à votre projet d'application:

1. Ouvrez le fichier build.gradle de votre application.
2. Ajoutez la bibliothèque d'assistance à la section dependencies.

Groovy

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

Kotlin

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

Initialisation de la configuration de la police téléchargeable

Vous devez initialiser EmojiCompat pour charger les métadonnées et la police de caractères. Étant donné que l'initialisation peut prendre un certain temps, le processus d'initialisation s'exécute sur un thread en arrière-plan.

Pour initialiser EmojiCompat avec la configuration de police téléchargeable, procédez comme suit:

1. Créez une instance de la classe FontRequest et fournissez l'autorité du fournisseur de polices, le package du fournisseur de polices, la requête de police et une liste d'ensembles de hachages pour le certificat. Pour en savoir plus sur FontRequest, consultez la section Utiliser des polices téléchargeables de manière programmatique dans la documentation sur les polices téléchargeables.
2. Créez une instance de FontRequestEmojiCompatConfig et fournissez des instances de Context et FontRequest.
3. Initialisez EmojiCompat en appelant la méthode init() et en transmettant l'instance de 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. Utilisez des widgets EmojiCompat dans les fichiers XML de mise en page. Si vous utilisez AppCompat, consultez la section Utiliser des widgets EmojiCompat avec 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"/>

Pour savoir comment configurer EmojiCompat avec la configuration de la police téléchargeable, consultez l'application exemple de compatibilité avec les emoji Java | Kotlin.

Composants de la bibliothèque

Figure 3. Composants de bibliothèque dans le processus EmojiCompat

Widgets: EmojiEditText, EmojiTextView, EmojiButton

Implémentations de widgets par défaut à utiliser avec EmojiCompat avec TextView, EditText et Button.

EmojiCompat

Principale surface publique de la bibliothèque d'assistance. Il effectue tous les appels externes et coordonne les autres parties du système.

EmojiCompat.Config

Configure l'instance singleton à créer.

EmojiSpan

Sous-classe ReplacementSpan qui remplace le caractère (séquences) et affiche le glyphe.

Police EmojiCompat

EmojiCompat utilise une police pour afficher les emoji. Cette police est une version modifiée de la police Emoji Android. La police est modifiée comme suit :

• Pour assurer la rétrocompatibilité de l'affichage des emoji, tous les caractères emoji sont représentés par un seul point de code Unicode dans la zone d'utilisation privée supplémentaire A d'Unicode, à partir de U+F0001.
• Des métadonnées emoji supplémentaires sont insérées au format binaire dans la police et sont analysées au moment de l'exécution par EmojiCompat. Les données sont intégrées à la table meta de la police, avec la balise privée Emji.

Options de configuration

Vous pouvez utiliser l'instance EmojiCompat pour modifier le comportement de EmojiCompat. Vous pouvez utiliser les méthodes suivantes de la classe de base pour définir la configuration:

• setReplaceAll() : détermine si EmojiCompat doit remplacer tous les emoji qu'il trouve par EmojiSpans. Par défaut, EmojiCompat s'efforce de comprendre si le système peut afficher un emoji et ne le remplace pas. Lorsque cette valeur est définie sur true, EmojiCompat remplace tous les emoji qu'il trouve par EmojiSpans.
• setEmojiSpanIndicatorEnabled(): indique si EmojiCompat a remplacé un emoji par un EmojiSpan. Lorsque ce paramètre est défini sur true, EmojiCompat dessine un arrière-plan pour EmojiSpan. Cette méthode est principalement utilisée à des fins de débogage.
• setEmojiSpanIndicatorColor() : définit la couleur pour indiquer un EmojiSpan. La valeur par défaut est GREEN.
• registerInitCallback : informe l'application de l'état de l'initialisation de 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() {...})

Ajouter des écouteurs d'initialisation

Les classes EmojiCompat et EmojiCompat fournissent des méthodes registerInitCallback() et unregisterInitCallback() pour enregistrer un rappel d'initialisation. Pour utiliser ces méthodes, créez une instance de la classe EmojiCompat.InitCallback. Appelez ces méthodes et transmettez l'instance de la classe EmojiCompat.InitCallback. Une fois l'initialisation de la bibliothèque d'assistance EmojiCompat réussie, la classe EmojiCompat appelle la méthode onInitialized(). Si l'initialisation de la bibliothèque échoue, la classe EmojiCompat appelle la méthode onFailed().

Pour vérifier l'état d'initialisation à tout moment, appelez la méthode getLoadState(). Il renvoie l'une des valeurs suivantes : LOAD_STATE_LOADING, LOAD_STATE_SUCCEEDED ou LOAD_STATE_FAILED.

Utiliser EmojiCompat avec les widgets AppCompat

Si vous utilisez AppCompat widgets, vous pouvez utiliser des widgets EmojiCompat qui s'étendent à partir de AppCompat widgets.

1. Ajoutez la bibliothèque d'assistance à la section "Dépendances".

   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. Utilisez des widgets EmojiCompat AppCompat Widget dans les fichiers XML de mise en page.

<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"/>

Configuration des polices groupées

La bibliothèque d'assistance EmojiCompat est également disponible dans une version de police groupée. Ce package inclut la police avec les métadonnées intégrées. Le package inclut également un BundledEmojiCompatConfig qui utilise AssetManager pour charger les métadonnées et les polices.

Remarque:La taille de la police est exprimée en mégaoctets.

Ajouter une dépendance de bibliothèque d'assistance

Pour utiliser la bibliothèque de compatibilité EmojiCompat avec la configuration de polices groupée, vous devez modifier les dépendances de chemin de classe de votre projet d'application dans votre environnement de développement.

Pour ajouter une bibliothèque d'assistance à votre projet d'application:

1. Ouvrez le fichier build.gradle de votre application.
2. Ajoutez la bibliothèque d'assistance à la section dependencies.

Groovy

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

Kotlin

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

Utiliser des polices groupées pour configurer EmojiCompat

Pour utiliser des polices groupées pour configurer EmojiCompat, procédez comme suit:

1. Utilisez BundledEmojiCompatConfig pour créer une instance de EmojiCompat et fournir une instance de Context.
2. Appelez la méthode init() pour initialiser EmojiCompat et transmettre l'instance de 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);
        ...
    }
}

Utiliser EmojiCompat sans widgets

EmojiCompat utilise EmojiSpan pour afficher des images correctes. Par conséquent, il doit convertir tout CharSequence donné en instances Spanned avec EmojiSpans. La classe EmojiCompat fournit une méthode permettant de convertir CharSequences en instances Spanned avec EmojiSpans. Grâce à cette méthode, vous pouvez traiter et mettre en cache les instances traitées au lieu de la chaîne brute, ce qui améliore les performances de votre application.

Kotlin

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

Java

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

Utiliser EmojiCompat pour les IME

À l'aide de la bibliothèque d'assistance EmojiCompat, les claviers peuvent afficher les emoji compatibles avec l'application avec laquelle ils interagissent. Les IME peuvent utiliser la méthode hasEmojiGlyph() pour vérifier si EmojiCompat est capable d'afficher un emoji. Cette méthode accepte un CharSequence d'un emoji et renvoie true si EmojiCompat peut détecter et afficher l'emoji.

Le clavier peut également vérifier la version de la bibliothèque d'assistance EmojiCompat compatible avec l'application pour déterminer les emoji à afficher dans la palette. Pour vérifier la version, le clavier doit vérifier si les clés suivantes existent dans le bundle EditorInfo.extras:

• EDITOR_INFO_METAVERSION_KEY

Si la clé existe dans le bundle, la valeur représente la version des métadonnées d'emoji que l'application utilise. Si cette clé n'existe pas, l'application n'utilise pas EmojiCompat.

• EDITOR_INFO_REPLACE_ALL_KEY

Si la clé existe et est définie sur true, cela indique que l'application a appelé la méthode SetReplaceAll(). Pour en savoir plus sur la configuration de EmojiCompat, consultez la section Options de configuration.

Après avoir reçu les clés dans le bundle EditorInfo.extras, le clavier peut utiliser la méthode hasEmojiGlyph(), où metadataVersion est la valeur de EDITOR_INFO_METAVERSION_KEY, pour vérifier si l'application peut afficher un emoji spécifique.

Utiliser EmojiCompat avec des widgets personnalisés

Vous pouvez toujours utiliser la méthode process() pour prétraiter le CharSequence dans votre application et l'ajouter à n'importe quel widget pouvant afficher des instances Spanned, par exemple TextView. De plus, EmojiCompat fournit les classes d'assistance de widget suivantes pour vous permettre d'enrichir vos widgets personnalisés avec la prise en charge des emoji avec un minimum d'effort.

• EmojiTextViewHelper
• EmojiEditTextHelper

Exemple de TextView

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() {
       ...
   }
}

Exemple d'EditText

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() {
       ...
   }
}

Questions fréquentes

• Comment lancer le téléchargement de la police ?

Les polices d'emoji sont téléchargées à la première requête, si elles n'existent pas sur l'appareil. La planification des téléchargements est transparente pour l'application.

• Combien de temps faut-il pour l'initialiser ?

Une fois la police téléchargée, l'initialisation de EmojiCompat prend environ 150 millisecondes.

• Combien de mémoire la bibliothèque d'assistance EmojiCompat utilise-t-elle ?

Actuellement, la structure de données permettant de trouver l'emoji est chargée dans la mémoire de l'application et utilise environ 200 ko.

• Puis-je utiliser EmojiCompat pour un TextView personnalisé ?

Oui. EmojiCompat fournit des classes d'assistance pour les widgets personnalisés. Il est également possible de prétraiter une chaîne donnée et de la convertir en Spanned. Pour en savoir plus sur les classes d'aide des widgets, consultez la section Utiliser EmojiCompat avec des widgets personnalisés.

• Que se passe-t-il si j'ajoute des widgets dans des fichiers XML de mise en page sur des appareils équipés d'Android 4.4 (niveau d'API 19) ou version antérieure ?

Vous pouvez inclure la bibliothèque d'assistance EmojiCompat ou ses widgets dans vos applications compatibles avec les appareils exécutant Android 4.4 (niveau d'API 19) ou version antérieure. Toutefois, si un appareil exécute une version d'Android antérieure au niveau d'API 19, EmojiCompat et ses widgets sont à l'état "aucune opération". Cela signifie que EmojiTextView se comporte exactement comme un TextView standard. instance EmojiCompat. Elle passe immédiatement à l'état LOAD_STATE_SUCCEEDED lorsque vous appelez la méthode init().

Ressources supplémentaires

Pour en savoir plus sur l'utilisation de la bibliothèque EmojiCompat, regardez la vidéo EmojiCompat.