توافق الرموز التعبيرية

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، يمكنك استخدام أدوات EmojiCompat التي تمتد من AppCompat widgets.

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. استخدِم عناصر واجهة المستخدم EmojiCompat AppCompat Widget في ملفات XML الخاصة بالتصميم.

<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حزمة مكتبة الدعم أيضًا في إصدار مجمَّع للخطوط. تتضمّن هذه الحزمة الخط مع البيانات الوصفية المضمّنة. تتضمّن الحزمة أيضًا BundledEmojiCompatConfig الذي يستخدم AssetManager لتحميل البيانات الوصفية والخطوط.

ملاحظة: يبلغ حجم الخط عدة ميغابايت.

إضافة تبعية مكتبة الدعم

لاستخدام EmojiCompat مكتبة الدعم مع إعدادات الخطوط المجمّعة، يجب تعديل ملحقات مسار الفئة في مشروع تطبيقك ضمن بيئة التطوير.

لإضافة مكتبة متوافقة إلى مشروع تطبيقك، اتّبِع الخطوات التالية:

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 لعرض الصور بشكل صحيح. لذلك، يجب أن يتم تحويل أي CharSequence إلى Spanned مثيل مع EmojiSpans. توفر الفئة EmojiCompat طريقة لتحويل CharSequences إلى مثيلات Spanned باستخدام EmojiSpans. باستخدام هذه الطريقة، يمكنك معالجة وتخزين النسخ المعالَجة مؤقتًا بدلاً من السلسلة الأولية، ما يؤدي إلى تحسين أداء تطبيقك.

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

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

استخدام EmojiCompat لطُرق الإدخال

باستخدام مكتبة التوافق EmojiCompat، يمكن للوحات المفاتيح عرض رموز الإيموجي المتوافقة مع التطبيق الذي تتفاعل معه. يمكن أن تستخدم برامج IME الطريقة hasEmojiGlyph() للتحقّق مما إذا كان EmojiCompat قادرًا على عرض إيموجي. تأخذ هذه الطريقة CharSequence إيموجي وتعرض true إذا كان بإمكان EmojiCompat رصد الإيموجي وعرضه.

يمكن للوحة المفاتيح أيضًا التحقّق من إصدار 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 المتوافقة؟

في الوقت الحالي، يتم تحميل بنية البيانات للعثور على الرموز التعبيرية في ذاكرة التطبيق، ويتم استخدام حوالي 200 كيلوبايت.

• هل يمكنني استخدام EmojiCompat مع عنصر TextView مخصّص؟

نعم. توفّر مكتبة EmojiCompat فئات مساعدة لعناصر واجهة المستخدم المخصّصة. من الممكن أيضًا إجراء معالجة مسبقة لسلسلة معيّنة وتحويلها إلى Spanned. لمزيد من المعلومات حول فئات أدوات المساعدة الخاصة بالعناصر، يُرجى الرجوع إلى قسم استخدام EmojiCompat مع عناصر واجهة مستخدم مخصّصة.

• ماذا يحدث إذا أضفتُ عناصر واجهة مستخدم في ملفات XML للتصميم على الأجهزة التي تعمل بالإصدار 4.4 (المستوى 19 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم من نظام التشغيل Android؟

يمكنك تضمين EmojiCompat مكتبة الدعم أو عناصرها في تطبيقاتك المتوافقة مع الأجهزة التي تعمل بالإصدار 4.4 (المستوى 19 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم من نظام التشغيل Android. ومع ذلك، إذا كان الجهاز يعمل بإصدار Android أقدم من مستوى واجهة برمجة التطبيقات 19، EmojiCompat وكانت أدواته في حالة "لا يوجد عملية". وهذا يعني أنّ EmojiTextView تتصرف تمامًا مثل TextView العادية. مثيل EmojiCompat، ويصبح على الفور في حالة LOAD_STATE_SUCCEEDED عند استدعاء الطريقة init().

مراجع إضافية

للحصول على معلومات إضافية حول استخدام مكتبة EmojiCompat ، شاهِد EmojiCompat.