支援現代表情符號

我們每年都會更新多種標準表情符號， 萬國碼 (Unicode)，因為表情符號使用日漸增加 且能在各種應用程式中快速部署

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

Android 11 (API 級別 30) 以下版本無法更新表情符號字型， 如果在這些版本中顯示您的應用程式，就必須手動更新。

以下是現代表情符號的範例。

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 子類別。

AppCompatActivity 會自動加載 AppCompatTextView 來取代 TextView 加載 XML 時，這樣就不需要更新 XML。

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

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

舊版 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 的應用程式中，因為此 SDK 已經實作 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 或 Android 版本的裝置上啟動應用程式 並列出下列測試字串請確認所有字元 能否正確轉譯)。

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

不搭配小工具使用 EmojiCompat

EmojiCompat 使用 EmojiSpan 執行以下動作： 生成正確的圖片因此必須轉換任何指定的 CharSequence 物件轉換為 Spanned 物件，其中包含 EmojiSpan 物件。 EmojiCompat 類別提供 process() 方法，用於轉換 CharSequences 複製到 Spanned 例項中。使用這個方法時，您可以在以下位置呼叫 process()： 並快取結果，藉此改善應用程式效能。

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

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 中的檢視畫面：

在不使用 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：🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

用於處理 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 行為

您可以使用 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"
   

2. 將 emoji2 設為使用套裝組合設定：

   Kotlin

   EmojiCompat.init(BundledEmojiCompatConfig(context))
   

   Java

   EmojiCompat.init(new BundledEmojiCompatConfig(context));
   

3. 請按照下列步驟測試整合作業： emojicompat (無論是否包含 AppCompat)。請確定測試字串 正確顯示。

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

自動 EmojiCompat 設定的影響

系統會使用啟動程式庫套用預設設定。 EmojiCompatInitializer和 DefaultEmojiCompatConfig。

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

「DefaultEmojiCompatConfig」會尋找系統安裝的可下載字型 實作 EmojiCompat 介面的供應商，例如 Google Play 免費 Google Cloud 服務在搭載 Google Play 服務的裝置上，這會透過 Google Play 服務載入字型。

初始化工具會建立背景執行緒，以載入表情符號字型和字型 下載作業可能需要 10 秒才會逾時。下載字型後，背景執行緒需要大約 150 毫秒來初始化 EmojiCompat。

即使停用 EmojiCompatInitializer，系統仍會延後 EmojiCompat 的初始化作業。如果您手動設定 EmojiCompat，在顯示後呼叫 EmojiCompat.load() 第一個畫面，即可避免第一個畫面的背景爭用情況 載入畫面。

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