支持新式表情符号

重要提示 ：本页面介绍了 androidx.emoji2:emoji2 库， 取代了已废弃的 androidx.emoji:emoji 库。

标准表情符号集每年 Unicode，因为表情符号使用量在不断增加 都能快速加载

如果您的应用显示互联网内容或提供文本输入，我们强烈建议 建议支持最新的表情符号字体。否则，系统可能会显示 显示为名为“豆腐块” (☐) 或其他错误渲染的小方块 表情符号序列。

Android 版本 11（API 级别 30）及更低版本无法更新表情符号字体，因此 在这些版本上显示这些信息的应用必须手动更新。

以下是新式表情符号的示例。

示例	版本
🫠 🫱🏼‍🫲🏿 🫰🏽	14.0（2021 年 9 月）
😶‍🌫️ 🧔🏻‍♀️ 🧑🏿‍❤️‍🧑🏾	13.1（2020 年 9 月）
🥲 🥷🏿 🐻‍❄️	13.0（2020 年 3 月）
🧑🏻‍🦰 🧑🏿‍🦯 👩🏻‍🤝‍👩🏼	12.1（2019 年 10 月）
🦩 🦻🏿 👩🏼‍🤝‍👩🏻	12.0（2019 年 2 月）

androidx.emoji2:emoji2 库可让您更轻松地向后兼容较低的 Android 版本。emoji2 库是 AppCompat 库，并且不需要任何 进一步的配置才能生效。

Compose 中的表情符号支持

2023 年 3 月 BoM (Compose UI 1.4) 支持最新表情符号 包括对低至 Android 低至 API 21。本页将介绍如何在 View 系统中配置新式表情符号。请参阅 如需了解详情，请参阅 Compose 中的表情符号页面。

前提条件

如需确认您的应用能否正确显示较新的表情符号，请在设备上启动该应用 搭载 Android 10（API 级别 29）或更低版本。此页面包含你推荐的新表情符号 以便进行测试

使用 AppCompat 支持最新的表情符号

AppCompat 1.4 支持表情符号。

如需使用 AppCompat 支持表情符号，请执行以下操作：

1. 检查您的模块是否依赖 AppCompat 库版本 1.4.0-alpha01 或更高版本。

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

2. 确保显示文本的所有 activity 都扩展 AppCompatActivity 类。

   Kotlin

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

   Java

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

3. 通过在搭载 Android 10 的设备上启动应用来测试集成 或更低版本，并显示以下测试字符串。请确保所有字符 正确呈现。

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

您的应用会在所有符合以下条件的设备上自动显示向后兼容的表情符号： 提供与 emoji2 兼容的可下载字体提供程序，例如设备 由 Google Play 服务提供支持。

如果您的应用使用了 AppCompat，但是显示豆腐块 (□)

在某些情况下，即使 您需要添加 AppCompat 库。以下是可能的原因 解决方案。

您正在最近刷写的设备或新的模拟器上运行应用

清除应用的 Google Play 服务数据，以清除所有可能的字体缓存。 启动期间会发生崩溃这通常在几个小时后问题得到解决。

如需清除应用数据，请执行以下操作：

1. 在 Android 设备上打开设置。

2. 点按应用和通知。

3. 点按查看所有应用或应用信息。

4. 滚动浏览应用，然后点按 Google Play 服务。

5. 点按存储和缓存。

6. 点按清除缓存。

您的应用未使用 AppCompat 文本相关类

如果您不扩展 AppCompatActivity 或实例化 代码视图，例如 TextView。请检查以下各项：

• activity 会扩展 AppCompatActivity。
• 如果在代码中创建视图，请使用正确的 AppCompat 子类。

在膨胀 XML 时，AppCompatActivity 会自动膨胀 AppCompatTextView 而不是 TextView，因此您无需更新自己的 XML。

测试手机不支持可下载字体

请验证 DefaultEmojiCompatConfig.create 是否会返回非 null 配置。

较低 API 级别的模拟器尚未升级 Google Play 服务

使用 API 级别较低的模拟器时，您可能需要更新 捆绑的 Google Play 服务，供 emoji2 查找字体提供程序。为此， 在模拟器上登录 Google Play 商店。

如需验证是否安装了兼容版本，请执行以下操作：

1. 运行以下命令：

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

2. 检查 versionCode 是否高于 211200000。

在不使用 AppCompat 的情况下支持表情符号

如果您的应用无法包含 AppCompat，则可以直接使用 emoji2。这个 需要执行更多工作，因此请仅在您的应用无法使用 AppCompat 时使用此方法。

如需在不使用 AppCompat 库的情况下支持表情符号，请执行以下操作：

1. 在应用的 build.gradle 文件中，添加 emoji2 和 emoji2-views。

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

   emoji2-views 模块提供 的子类 TextView、Button 和 EditText，用于实现 EmojiCompat。不使用 包含 AppCompat 的应用，因为它已实现 EmojiCompat。

2. 在 XML 和代码中，无论您在何处使用 TextView、EditText 或 Button - 使用 EmojiTextView, EmojiEditText 或 EmojiButton。

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

   添加 emoji2 模块后，系统会使用默认的可下载项 字体提供程序加载表情符号字体 自动更新。否 需要进行进一步配置。

3. 如需测试您的集成，请在搭载 Android 11 或 并显示以下测试字符串。请确保所有字符 正确呈现。

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

不搭配微件使用 EmojiCompat

EmojiCompat 使用 EmojiSpan 来 呈现正确的图像。因此，必须将所有给定的 CharSequence 对象转换为 包含 EmojiSpan 对象的 Spanned 对象。 EmojiCompat 类提供 process() 方法，可将 CharSequences 转换为 Spanned 实例。使用此方法，您可以调用 process() 中的 后台并缓存结果，从而提高应用的性能。

Kotlin

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

Java

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

将 EmojiCompat 用于输入法

EmojiCompat 类可让键盘呈现应用支持的表情符号 互动过程输入法 (IME) 可以使用 getEmojiMatch() 方法，用于检查 EmojiCompat 的实例是否能够 表情符号。此方法接受 CharSequence 表情符号的样式；如果 EmojiCompat 可以检测到并呈现该表情符号，则返回 true。

键盘还可以检查应用支持的 EmojiCompat 版本，以确定要在 palette 中呈现的表情符号。如需检查版本（如果可用），键盘可以在 EditorInfo.extras 软件包中查找以下键：

• EDITOR_INFO_METAVERSION_KEY: 表示应用使用的表情符号元数据的版本。如果该键不存在，则说明应用未使用 EmojiCompat。
• EDITOR_INFO_REPLACE_ALL_KEY: 如果该键存在且设置为 true，则应用会配置 EmojiCompat 替换所有表情符号，即使系统中存在这些表情符号也是如此。

详细了解如何配置 EmojiCompat 的实例。

在自定义视图中使用表情符号

如果您的应用包含 TextView 的直接或间接子类，例如 Button、 Switch 或 EditText，这些视图可以显示由用户生成的 必须分别实现 EmojiCompat。

此过程取决于您的应用是否使用 AppCompat 库。

为使用 AppCompat 的应用添加自定义视图

如果您的应用使用 AppCompat，请扩展 AppCompat 实现，而不是 平台实现请参考下表 扩展 AppCompat 中的视图：

不要扩展…	扩展
TextView	AppCompatTextView
EditText	AppCompatEditText
ToggleButton	AppCompatToggleButton
Switch	SwitchCompat
Button	AppCompatButton
CheckedTextView	AppCompatCheckedTextView
RadioButton	AppCompatRadioButton
CheckBox	AppCompatCheckBox
AutoCompleteTextView	AppCompatAutoCompleteTextView
MultiAutoCompleteTextView	AppCompatMultiAutoCompleteTextView

为不用 AppCompat 的应用添加自定义视图

如果您的应用不使用 AppCompat，请使用 emoji2-views-helper 模块中旨在用于自定义视图的视图集成辅助程序。AppCompat 库正是使用这些辅助程序来实现表情符号支持。

完成以下步骤，以便针对不使用 AppCompat 的应用支持自定义视图。

1. 添加 emoji2-views-helper 库：

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

2. 按照说明添加 EmojiTextViewHelper 或 EmojiEditTextHelper 在应用的自定义视图中显示

3. 通过在搭载 Android 10 的设备上启动应用来测试集成 或更低版本，并显示以下测试字符串。请确保所有字符 正确呈现。

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

。

注意： 对于不使用 AppCompat 的应用，您可以扩展 EmojiCompat*View 类，或使用视图辅助程序类手动集成。

用于处理 emoji2 的可选功能

在应用中添加 emoji2 库后，就可以添加可选的 介绍这些功能

将 emoji2 配置为使用其他字体或可下载字体提供程序

如需将 emoji2 配置为使用其他字体或可下载字体提供程序，请执行以下操作：

1. 停用 EmojiCompatInitializer 方法是向清单中添加以下内容：

   <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. 执行以下其中一项操作：

   • 通过调用以下命令使用默认配置： DefaultEmojiCompatConfiguration.create(context)。

   • 创建您自己的配置，以使用 EmojiCompat.Config 从其他来源加载字体。此类提供了多个用于修改 EmojiCompat 的选项 行为，如下一部分所述。

。

注意： 如果您停用默认配置，请验证是否显示了表情符号 。在启动后不久调用 EmojiCompat.init。您可以 从 Application.onCreate() 安全地调用 init()，传入 LOAD_STRATEGY_MANUAL、 然后调用 EmojiCompat.load()起价： 后台线程。

修改 EmojiCompat 行为

您可以使用 EmojiCompat.Config 的实例来修改 EmojiCompat 行为

最重要的配置选项是 setMetadataLoadStrategy()，它控制着 EmojiCompat 何时加载字体。字体加载 系统会调用 EmojiCompat.load()，这会触发所有必要的下载。通过 系统会创建一个线程来下载字体，除非您的应用提供线程。

LOAD_STRATEGY_MANUAL 可让您控制何时调用 EmojiCompat.load()，以及 LOAD_STRATEGY_DEFAULT 在调用 EmojiCompat.init()。

大多数应用都使用 LOAD_STRATEGY_MANUAL，因此它们可以控制线程和时间 开始展示您的应用必须推迟到第一个屏幕显示后， 避免引入启动延迟EmojiCompatInitializer关注此频道 并推迟加载表情符号字体，直到第一个屏幕恢复显示。

使用基类中的以下方法设置 配置：

• setReplaceAll(): 确定 EmojiCompat 是否将其找到的所有表情符号替换为实例 共 EmojiSpan 个。默认情况下，当 EmojiCompat 推断系统可以 呈现表情符号时，并不会替换该表情符号设置为 true 时， EmojiCompat 会将所有表情符号替换为 EmojiSpan 对象。
• setEmojiSpanIndicatorEnabled(): 指示 EmojiCompat 是否将表情符号替换为 EmojiSpan 对象。设置为 true 时，EmojiCompat 会为 EmojiSpan 绘制背景。此方法主要用于调试目的。
• setEmojiSpanIndicatorColor: 设置颜色以指示 EmojiSpan。默认值为 GREEN。
• registerInitCallback(): 告知应用 EmojiCompat 初始化的状态。

添加初始化监听器

EmojiCompat 和 EmojiCompat.Config 类提供 registerInitCallback() 和 unregisterInitCallback() 方法注册和取消注册初始化回调。您的应用会使用这些信息 回调，以等待 EmojiCompat 完成初始化，然后再处理表情符号上的 后台线程或自定义视图中

如需使用这些方法，请创建 EmojiCompat.InitCallback 类的实例。调用这些方法并传入 EmojiCompat.InitCallback 类的实例。初始化成功时，EmojiCompat 类会调用 onInitialized() 方法。如果库初始化失败，EmojiCompat 类会调用 onFailed() 方法。

要随时检查初始化状态，请调用 getLoadState() 方法。此方法会返回以下某个值： LOAD_STATE_LOADING、 LOAD_STATE_SUCCEEDED, 或 LOAD_STATE_FAILED。

通过 emoji2 支持捆绑式字体

您可以使用 emoji2-bundled 工件将表情符号字体捆绑到应用中。 但是，由于 NotoColorEmoji 字体超过 10 MB，因此我们强烈建议 建议您的应用尽可能使用可下载字体。通过 emoji2-bundled 工件适用于不支持的设备上的应用 可下载字体

如需使用 emoji2-bundled 工件，请执行以下操作：

1. 添加了 emoji2-bundled 和 emoji2 工件：

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

   注意： 添加 emoji2-bundled 工件会停用 EmojiCompatInitializer，因此您的应用必须调用 EmojiCompat.init()。

2. 将 emoji2 配置为使用捆绑的配置：

   Kotlin

   EmojiCompat.init(BundledEmojiCompatConfig(context))
   

   Java

   EmojiCompat.init(new BundledEmojiCompatConfig(context));
   

3. 按照前面的步骤测试集成，添加 包含或不包含 AppCompat 的 emojicompat。请确保测试字符串 正确显示。

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

自动化 EmojiCompat 配置的影响

系统使用启动库来应用默认配置， EmojiCompatInitializer和 DefaultEmojiCompatConfig。

在应用中恢复第一个 activity 后，初始化程序会调度表情符号 字体加载。这种短暂的延迟可让您的应用显示其初始内容， 因在后台线程中加载字体而导致的任何潜在延迟。

DefaultEmojiCompatConfig 会查找系统安装的可下载字体 实现 EmojiCompat 接口的提供程序，例如 Google Play 服务。在采用 Google Play 服务的设备上，这将使用 Google Play 服务加载字体。

注意 ：默认的 emoji2 配置使用可下载字体来获取 兼容的字体文件。在采用 Google Play 服务的设备上 传递给 Google Play 服务系统会记录字体请求 （由 Google Play 服务提供）和可下载字体。

初始化程序会创建一个后台线程来加载表情符号字体和字体 最长可能需要 10 秒才会超时。下载字体后，在后台线程上初始化 EmojiCompat 大约需要 150 毫秒。

推迟 EmojiCompat 的初始化，即使您停用 EmojiCompatInitializer 也是如此。如果您手动配置 EmojiCompat 后，调用 EmojiCompat.load()。 避免与第一个屏幕发生后台争用 加载屏幕

加载后，EmojiCompat 会使用大约 300 KB 的 RAM 来存储表情符号 元数据。