表情符號相容性

val config = FontRequestEmojiCompatConfig(...)
        .setReplaceAll(true)
        .setEmojiSpanIndicatorEnabled(true)
        .setEmojiSpanIndicatorColor(Color.GREEN)
        .registerInitCallback(object: EmojiCompat.InitCallback() {
            ...
        })

EmojiCompat.Config config = new FontRequestEmojiCompatConfig(...)
       .setReplaceAll(true)
       .setEmojiSpanIndicatorEnabled(true)
       .setEmojiSpanIndicatorColor(Color.GREEN)
       .registerInitCallback(new InitCallback() {...})

新增初始化事件監聽器

EmojiCompat 和 EmojiCompat 類別提供 registerInitCallback() 和 unregisterInitCallback() 方法，用於註冊初始化回呼。如要使用這些方法，請建立 EmojiCompat.InitCallback 類別的例項。呼叫這些方法，並傳遞 EmojiCompat.InitCallback 類別的例項。當 EmojiCompat 支援程式庫的初始化成功時，EmojiCompat 類別會呼叫 onInitialized() 方法。如果資料庫無法初始化，EmojiCompat 類別會呼叫 onFailed() 方法。

如要在任何時間點查看初始化狀態，請呼叫 getLoadState() 方法。此方法會傳回下列其中一個值：LOAD_STATE_LOADING、LOAD_STATE_SUCCEEDED 或 LOAD_STATE_FAILED。

搭配使用 EmojiCompat 與 AppCompat 小工具

如果您使用的是 AppCompat widgets，可以使用從 AppCompat widgets 延伸而來的 EmojiCompat 小工具。

1. 將支援資料庫新增至依附元件區段。

   Groovy

   dependencies {
       ...
       implementation "androidx.emoji:emoji-bundled:$version"
   }

   Kotlin

         dependencies {
             implementation("androidx.emoji:emoji-appcompat:$version")
         }
         

   Groovy

         dependencies {
             implementation "androidx.emoji:emoji-appcompat:$version"
         }
         

2. 在版面配置 XML 中使用 EmojiCompat AppCompat Widget 小工具。

<android.support.text.emoji.widget.EmojiAppCompatTextView
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

<android.support.text.emoji.widget.EmojiAppCompatEditText
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

<android.support.text.emoji.widget.EmojiAppCompatButton
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

套裝字型設定

EmojiCompat 支援資料庫也提供套裝字型版本。這個套件包含內嵌中繼資料的字型，也包含使用 AssetManager 載入中繼資料和字型的 BundledEmojiCompatConfig。

注意：字型大小以 MB 為單位。

新增支援資料庫依附元件

如要使用搭配套裝字型設定的 EmojiCompat 支援資料庫，您「必須」在開發環境中修改應用程式專案的 classpath 依附元件。

如何在應用程式專案中新增支援資料庫：

1. 開啟應用程式的 build.gradle 檔案。
2. 將支援資料庫新增至 dependencies 區段。

dependencies {
    ...
    implementation "androidx.emoji:emoji:28.0.0"
}

dependencies {
    ...
    implementation("androidx.emoji:emoji:28.0.0")
}

使用套裝字型設定 EmojiCompat

如要使用套裝字型設定 EmojiCompat，請執行下列步驟：

1. 使用 BundledEmojiCompatConfig 建立 EmojiCompat 的例項，並提供 Context 的例項。
2. 呼叫 init() 方法以初始化 EmojiCompat，並傳遞 BundledEmojiCompatConfig 的例項。

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        val config = BundledEmojiCompatConfig(this)
        EmojiCompat.init(config)
    }
}

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        EmojiCompat.Config config = new BundledEmojiCompatConfig(this);
        EmojiCompat.init(config);
        ...
    }
}

不搭配小工具使用 EmojiCompat

EmojiCompat 使用 EmojiSpan 來轉譯正確的圖片，因此必須使用 EmojiSpans 將提供的任一 CharSequence 轉換為 Spanned 例項。EmojiCompat 類別提供一種方法，以使用 EmojiSpans 將 CharSequences 轉換為 Spanned 例項。您可以使用此方法處理及快取例項 (而非原始字串)，進而提升應用程式的效能。

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

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

將 EmojiCompat 用於輸入法編輯器

使用 EmojiCompat 支援資料庫時，鍵盤可轉譯其互動的應用程式所支援的表情符號。輸入法編輯器可以使用 hasEmojiGlyph() 方法檢查 EmojiCompat 是否能轉譯表情符號。這個方法會擷取表情符號的 CharSequence，且如果 EmojiCompat 能偵測到及顯示表情符號，則會傳回 true。

鍵盤也可以檢查應用程式支援的 EmojiCompat 支援資料庫版本，以判斷要在區塊面板轉譯哪個表情符號。為了確認版本 (如果有的話)，鍵盤必須檢查 EditorInfo.extras 套件中是否有下列索引鍵：

• EDITOR_INFO_METAVERSION_KEY

如果套件中有該索引鍵，該值代表應用程式使用的表情符號中繼資料版本。如果這組索引鍵不存在，就表示應用程式未使用 EmojiCompat。

• EDITOR_INFO_REPLACE_ALL_KEY

如果索引鍵存在且設為 true，表示應用程式已呼叫 SetReplaceAll() 方法。如要進一步瞭解 EmojiCompat 設定，請參閱設定選項一節。

收到 EditorInfo.extras 套件中的索引鍵後，鍵盤可以使用 hasEmojiGlyph() 方法 (其中 metadataVersion 是 EDITOR_INFO_METAVERSION_KEY 的值) 檢查應用程式是否能轉譯特定表情符號。

搭配使用 EmojiCompat 與自訂小工具

您隨時可以使用 process() 方法，在應用程式中預先處理 CharSequence，並將其加入任何可轉譯 Spanned 例項的小工具；例如 TextView。此外，EmojiCompat 提供下列小工具輔助類別，讓您以最輕鬆的方式支援表情符號，使自訂小工具更豐富。

• EmojiTextViewHelper
• EmojiEditTextHelper

TextView 範例

Kotlin

class MyTextView(context: Context) : AppCompatTextView(context) {

    private val emojiTextViewHelper: EmojiTextViewHelper by lazy(LazyThreadSafetyMode.NONE) {
        EmojiTextViewHelper(this).apply {
            updateTransformationMethod()
        }
    }

    override fun setFilters(filters: Array<InputFilter>) {
        super.setFilters(emojiTextViewHelper.getFilters(filters))
    }

    override fun setAllCaps(allCaps: Boolean) {
        super.setAllCaps(allCaps)
        emojiTextViewHelper.setAllCaps(allCaps)
    }
}

Java

public class MyTextView extends AppCompatTextView {
   ...
   public MyTextView(Context context) {
       super(context);
       init();
   }
   ...
   private void init() {
       getEmojiTextViewHelper().updateTransformationMethod();
   }

   @Override
   public void setFilters(InputFilter[] filters) {
       super.setFilters(getEmojiTextViewHelper().getFilters(filters));
   }

   @Override
   public void setAllCaps(boolean allCaps) {
       super.setAllCaps(allCaps);
       getEmojiTextViewHelper().setAllCaps(allCaps);
   }

   private EmojiTextViewHelper getEmojiTextViewHelper() {
       ...
   }
}

EditText 範例

Kotlin

class MyEditText(context: Context) : AppCompatEditText(context) {

    private val emojiEditTextHelper: EmojiEditTextHelper by lazy(LazyThreadSafetyMode.NONE) {
        EmojiEditTextHelper(this).also {
            super.setKeyListener(it.getKeyListener(keyListener))
        }
    }

    override fun setKeyListener(input: KeyListener?) {
        input?.also {
            super.setKeyListener(emojiEditTextHelper.getKeyListener(it))
        }
    }

    override fun onCreateInputConnection(outAttrs: EditorInfo): InputConnection {
        val inputConnection: InputConnection = super.onCreateInputConnection(outAttrs)
        return emojiEditTextHelper.onCreateInputConnection(
                inputConnection,
                outAttrs
        ) as InputConnection
    }
}

Java

public class MyEditText extends AppCompatEditText {
   ...
   public MyEditText(Context context) {
       super(context);
       init();
   }
   ...
   private void init() {
       super.setKeyListener(getEmojiEditTextHelper().getKeyListener(getKeyListener()));
   }

   @Override
   public void setKeyListener(android.text.method.KeyListener keyListener) {
       super.setKeyListener(getEmojiEditTextHelper().getKeyListener(keyListener));
   }

   @Override
   public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
       InputConnection inputConnection = super.onCreateInputConnection(outAttrs);
       return getEmojiEditTextHelper().onCreateInputConnection(inputConnection, outAttrs);
   }

   private EmojiEditTextHelper getEmojiEditTextHelper() {
       ...
   }
}

常見問題

• 如何開始下載字型？

如果裝置中沒有表情符號字型，裝置會在初次收到要求時加以下載。應用程式會知道下載時間。

• 初始化需要多久？

字型下載完畢後，初始化 EmojiCompat 約需 150 毫秒。

• EmojiCompat 支援資料庫會使用多少記憶體？

目前，用於尋找表情符號的資料結構已載入應用程式的記憶體中，約使用 200KB。

• 可以使用 EmojiCompat 建立自訂 TextView 嗎？

可以。EmojiCompat 提供自訂小工具適用的輔助類別 您也可以預先處理特定字串，並將其轉換為 Spanned。如要進一步瞭解小工具輔助類別，請參閱搭配使用 EmojiCompat 與自訂小工具一節。

• 如果在搭載 Android 4.4 (API 級別 19) 以下版本的裝置上，於版面配置 XML 中新增小工具，會發生什麼事？

您可以在支援 Android 4.4 (API 級別 19) 以下版本裝置的應用程式中，加入 EmojiCompat 支援資料庫或其小工具。不過，如果裝置執行的 Android 版本早於 API 級別 19，EmojiCompat 及其小工具就會處於「無法運作」狀態。這表示 EmojiTextView 的行為就像一般的 TextView.EmojiCompat 例項；在您呼叫 init() 方法後，會立即進入 LOAD_STATE_SUCCEEDED 狀態。

其他資源

如要進一步瞭解如何使用 EmojiCompat 資料庫，請觀看 EmojiCompat 影片。