支援現代表情符號

因為所有應用程式類型的表情符號使用頻率迅速上升,所以標準表情符號每年都會由萬國碼 (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 程式庫,應用程式仍可能會顯示 Tofu 而非適當的表情符號。以下是可能的解釋與解決方案。

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

清除應用程式的 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 檔案中,加入 emoji2emoji2-views

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

    emoji2-views 模組提供實作 EmojiCompatTextViewButtonEditText子類別。請勿在包含 AppCompat 的應用程式中使用,因為它已經實作 EmojiCompat

  2. 在 XML 和程式碼中,無論您在何處使用 TextViewEditTextButton,都請改用 EmojiTextViewEmojiEditTextEmojiButton

    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 轉譯正確的圖片。因此,必須使用 EmojiSpan 物件將任何指定的 CharSequence 物件轉換為 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 的直接或間接子類別 (例如 ButtonSwitchEditText),且這些檢視畫面可顯示使用者產生的內容,則這些檢視畫面都必須實作 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. 按照操作說明將 EmojiTextViewHelperEmojiEditTextHelper 納入應用程式的自訂檢視畫面中。

  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. 請執行下列任一步驟:

修改 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 的初始化狀態。

新增初始化事件監聽器

EmojiCompatEmojiCompat.Config 類別提供 registerInitCallback()unregisterInitCallback() 方法,用於註冊及取消註冊初始化回呼。應用程式會使用這些回呼,等到 EmojiCompat 初始化後,再在背景執行緒或自訂檢視畫面中處理表情符號。

如要使用這些方法,請建立 EmojiCompat.InitCallback 類別的例項。呼叫這些方法,並傳遞 EmojiCompat.InitCallback 類別的例項。初始化成功後,EmojiCompat 類別會呼叫 onInitialized() 方法。如果程式庫無法初始化,EmojiCompat 類別會呼叫 onFailed() 方法。

如要在任何時間點查看初始化狀態,請呼叫 getLoadState() 方法。這個方法會傳回下列其中一個值:LOAD_STATE_LOADINGLOAD_STATE_SUCCEEDEDLOAD_STATE_FAILED

使用 emoji2 支援套裝組合字型

您可以使用 emoji2-bundled 構件將表情符號字型整合至應用程式。不過,由於 NotoColorEmoji 字型超過 10 MB,強烈建議您盡可能讓應用程式使用可下載的字型。emoji2-bundled 構件適用於裝置不支援可下載字型的裝置。

如要使用 emoji2-bundled 構件,請按照下列步驟操作:

  1. 加入 emoji2-bundledemoji2 構件:

    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. 測試整合,方法是按照上述步驟加入具有或不具有 AppCompatemojicompat。確認測試字串可以正確顯示。

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

自動 EmojiCompat 設定的影響

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

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

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

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

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

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