支援現代表情符號

試用 Compose

Jetpack Compose 是 Android 推薦的 UI 工具包。瞭解如何在 Compose 中支援表情符號。

支援表情符號 →

重要事項： 本頁說明 androidx.emoji2:emoji2 程式庫，用於取代已淘汰的 androidx.emoji:emoji 程式庫。

由於所有類型的應用程式的表情符號用量越來越快速，因此標準表情符號組合每年都會由萬國碼 (Unicode) 更新。

如果應用程式會顯示網際網路內容或提供文字輸入，強烈建議支援最新的表情符號字型。否則，後續表情符號可能會顯示為名為「tofu」的小正方形方塊 (☐)，或其他以錯誤方式呈現的表情符號序列。

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. 確保顯示文字的所有活動都擴充 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，但顯示 tofu (☐)

在某些情況下，即使您新增 AppCompat 程式庫，應用程式仍可能顯示豆腐，而非適當的表情符號。以下是可能的原因和解決方法。

您正在最近刷新的裝置或新的模擬器上執行應用程式

清除應用程式的 Google Play 服務資料，以清除可能在啟動期間發生的任何字型快取。這麼做通常會在幾小時後解決這個問題。

如要清除應用程式資料，請按照下列步驟操作：

1. 在 Android 裝置上開啟「設定」。

2. 輕觸 [應用程式和通知]。

3. 輕觸「查看所有應用程式」或「應用程式資訊」。

4. 捲動瀏覽應用程式，然後輕觸「Google Play 服務」。

5. 輕觸「儲存空間和快取」。

6. 輕觸 [清除快取]。

您的應用程式未使用 AppCompat 文字相關類別

如果您未擴充 AppCompatActivity，或對程式碼中的檢視畫面執行個體化 (例如 TextView)，就可能發生這種情況。檢查以下項目：

• 活動擴充 AppCompatActivity。
• 如要在程式碼中建立檢視畫面，請使用正確的 AppCompat 子類別。

加載 XML 時，AppCompatActivity 會自動加載 AppCompatTextView 來取代 TextView，因此您不需要更新 XML。

測試手機不支援可下載字型

確認 DefaultEmojiCompatConfig.create 傳回非空值設定。

舊版 API 級別上的模擬器尚未升級 Google Play 服務

在舊版 API 級別上使用模擬器時，可能需要更新 emoji2 的隨附 Google Play 服務，才能尋找字型供應程式。方法是在模擬器上登入 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 模組提供實作 EmojiCompat 的 TextView、Button 和 EditText 子類別。請勿在包含 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 版本，以決定在區塊面板中顯示哪個表情符號。如要確認版本 (如果有的話)，鍵盤可在 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 套用預設設定。

在應用程式中繼續執行第一次活動後，初始化器會安排載入表情符號字型。這段短暫延遲可讓應用程式顯示初始內容，而不會因為在背景執行緒中載入字型而產生任何可能的延遲時間。

DefaultEmojiCompatConfig 會尋找系統安裝的可下載字型提供者，該提供者實作 EmojiCompat 介面，如 Google Play 服務。在搭載 Google Play 服務的裝置上，這會透過 Google Play 服務載入字型。

注意：預設 emoji2 設定使用可下載的字型擷取相容的字型檔案。在搭載 Google Play 服務的裝置上，應用程式會在啟動時將這個查詢傳送至 Google Play 服務。Google Play 服務和可下載字型會記錄字型要求。

初始化器會建立背景執行緒來載入表情符號字型，字型下載作業最多可持續 10 秒鐘，之後則會逾時。下載字型後，背景執行緒需要大約 150 毫秒來初始化 EmojiCompat。

即使停用 EmojiCompatInitializer，系統仍會延後 EmojiCompat 的初始化作業。如果您要手動設定 EmojiCompat，請在應用程式顯示第一個畫面後再呼叫 EmojiCompat.load()，以避免在載入第一個畫面時出現背景爭用的情形。

載入後，EmojiCompat 會使用約 300 KB 的 RAM 來存放表情符號中繼資料。