支援現代表情符號

隨著各類型應用程式的使用者對表情符號的使用量不斷迅速增加，這套標準表情符號每年都會由 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 程式庫的依附元件，不需要進一步設定。

必要條件

為確認您的應用程式可正確顯示較新的表情符號，請在搭載 Android 4.4 (API 級別 19) 至 Android 10 (API 級別 29) (內含) 之間版本的裝置上啟動應用程式。此頁面包含可用於顯示測試的現代表情符號。

使用 AppCompat 支援最新表情符號

AppCompat 1.4 支援低至 Android 4.4 版本的表情符號。

如何使用 AppCompat 支援最新表情符號：

確認您的模組依賴於 appcompat 程式庫版本 1.4.0-alpha01 或以上版本。

build.gradle

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

確保顯示文字的所有活動都擴充 AppCompatActivity 類別。

Kotlin

MyActivity.kt

class MyActivity: AppCompatActivity {
   …
}

Java

MyActivity.java

class MyActivity extends AppCompatActivity {
   …
}

如要測試整合結果，請在搭載 Android 10 或以下版本的裝置上啟動應用程式，並顯示下列測試字串。確保所有字元都能正確顯示。
- 14.0：🫠, 🫱🏼‍🫲🏿, 🫰🏽
- 13.1：😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
- 13.0：🥲, 🥷🏿, 🐻‍❄️
- 12.1：🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
- 12.0：🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

大功告成！只要裝置提供與 emoji2 相容的可下載字型供應程式 (例如由 Google Play 服務技術提供的裝置)，應用程式就會自動顯示具有回溯相容性的表情符號。

如果您的應用程式使用 AppCompat，但顯示 tofu (☐)

在某些情況下，即使您已新增 AppCompat 程式庫，應用程式仍可能顯示 tofu (☐)，而不是正確的表情符號。以下是一些可能的情況說明和解決方案。

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

清除 Google Play 服務的應用程式資料，以清除可能在啟動期間發生的任何字型快取。執行此操作後，這種情況通常會在幾個小時後自行解決。

如何清除應用程式資料：

在 Android 裝置上開啟「設定」。
在「設定」中，輕觸「應用程式和通知」。
輕觸「查看所有應用程式」或「應用程式資訊」。
捲動瀏覽應用程式，然後輕觸「Google Play 服務」。
輕觸「儲存空間和快取」。
輕觸「清除快取」。

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

如未擴充 AppCompatActivity，或對程式碼中的檢視畫面進行了執行個體化 (如 TextView)，就有可能發生這種情況。確保執行以下操作：

活動擴充 AppCompatActivity。
如要在程式碼中建立檢視畫面，請使用正確的 appcompat subclass。

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

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

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

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

在舊版 API 級別上使用模擬器時，隨附的 Google Play 服務可能需要升級，才能讓 emoji2 找到字型供應程式。如要執行此操作，請登入模擬器上的 Google Play 商店。

如要驗證是否已安裝足夠新的版本，請按照下列步驟操作：

執行下列指令：

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

檢查 versionCode 是否高於 211200000。

在不使用 AppCompat 的情況下支援表情符號

如果您的應用程式不含 appcompat，則可直接使用 emoji2。這樣需要執行更多工作，因此只有在應用程式無法使用 appcompat 時，才使用此方法。

如要在不使用 AppCompat 程式庫的情況下支援表情符號，請按照下列步驟操作：

在應用程式的 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。
在 XML 或程式碼 (您將使用 TextView、EditText 或 Button 的位置) 中，改為使用 EmojiTextView、EmojiEditText 或 EmojiButton。
```
activity_main.xml

<androidx.emoji2.widget.EmojiTextView … />
<androidx.emoji2.widget.EmojiEditText … />
<androidx.emoji2.widget.EmojiButton … />
```
加入 emoji2 模組後，系統會使用預設可下載的字型提供者，在應用程式啟動後不久自動載入表情符號字型，因此無需進行進一步設定。
如要測試整合結果，請在搭載 Android 10 或以下版本的裝置上啟動應用程式，並顯示下列測試字串確保所有字元都能正確顯示。
- 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) 可以使用 hasEmojiGlyph() 方法檢查 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 的應用程式，請完成下列步驟，以支援自訂檢視畫面。

新增 emoji2-views-helper 程式庫。

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

按照操作說明，在應用程式的自訂檢視畫面中加入 EmojiTextViewHelper 或 EmojiEditTextHelper。
如要測試整合結果，請在搭載 Android 10 或以下版本的裝置上啟動應用程式，並顯示下列測試字串。確保所有字元都能正確顯示。
- 14.0：🫠, 🫱🏼‍🫲🏿, 🫰🏽
- 13.1：😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
- 13.0：🥲, 🥷🏿, 🐻‍❄️
- 12.1：🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
- 12.0：🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

用於處理 emoji2 的選用功能

在應用程式中加入 emoji2 程式庫後，您可以選擇新增本節所述的選用功能。

將 emoji2 設定為使用其他字型或可下載字型提供者

如要將 emoji2 設定為使用其他字型或可下載字型提供者，請按照下列步驟操作：

在資訊清單中新增以下內容，停用 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>

請執行下列任一步驟：
- 呼叫 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 構件，請按照下列步驟操作：

加入 emoji2-bundled 和 emoji2 構建。
```
implementation "androidx.emoji2:emoji2:$emojiVersion"
implementation "androidx.emoji2:emoji2-bundled:$emojiVersion"
```
注意：加入 emoji2-bundled 構件會停用 EmojiCompatInitializer，因此您的應用程式必須呼叫 EmojiCompat.init()。

將 emoji2 設為使用套裝組合設定。

Kotlin

EmojiCompat.init(BundledEmojiCompatConfig(context))

Java

EmojiCompat.init(new BundledEmojiCompatConfig(context));

測試整合的方式為：根據上述步驟加入具有或不具有 appcompat 的 emojicompat，然後確保測試字串可以正確顯示。
- 14.0：🫠, 🫱🏼‍🫲🏿, 🫰🏽
- 13.1：😶‍🌫️, 🧔🏻‍♀️, 🧑🏿‍❤️‍🧑🏾
- 13.0：🥲, 🥷🏿, 🐻‍❄️
- 12.1：🧑🏻‍🦰, 🧑🏿‍🦯, 👩🏻‍🤝‍👩🏼
- 12.0：🦩, 🦻🏿, 👩🏼‍🤝‍👩🏻

自動 EmojiCompat 設定的影響

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

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

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

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

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

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