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

تهدف مكتبة دعم EmojiCompat إلى إبقاء أجهزة Android مُحدّثة بأحدث الرموز التعبيرية. ويمنع هذا الرمز تطبيقك من عرض رموز الإيموجي الناقصة على شكل ☐، ما يشير إلى أنّ جهازك لا يتضمّن خطًا لعرض النص. عند استخدام مكتبة دعم EmojiCompat، لن يحتاج مستخدمو تطبيقك إلى انتظار تحديثات نظام التشغيل Android للحصول على أحدث الرموز التعبيرية.

أجهزة تعرض رموزًا تعبيرية
الشكل 1. مقارنة الرموز التعبيرية

يمكنك الاطّلاع على المراجع التالية ذات الصلة:

  • نموذج تطبيق متوافق مع الرموز التعبيرية Java | Kotlin

ما هي آلية عمل EmojiCompat؟

توفّر مكتبة دعم EmojiCompat فئات لإتاحة الرموز التعبيرية المتوافقة مع الإصدارات القديمة على الأجهزة التي تعمل بنظام التشغيل Android 4.4 (المستوى 19 من واجهة برمجة التطبيقات) والإصدارات الأحدث. يمكنك ضبط EmojiCompat باستخدام خطوط مضمَّنة أو قابلة للتنزيل. لمزيد من المعلومات عن الإعداد، يمكنك الاطّلاع على الأقسام التالية:

يتعرَّف EmojiCompat على الرموز التعبيرية لـ CharSequence محدّد، ويستبدلها بـ EmojiSpans إذا لزم الأمر، ويعرض أخيرًا الرموز التعبيرية. يوضح الشكل 2 العملية.

عملية EmojiCompat
الشكل 2. عملية EmojiCompat

إعدادات الخطوط القابلة للتنزيل

تستخدم إعدادات الخطوط القابلة للتنزيل ميزة مكتبة دعم "الخطوط القابلة للتنزيل" لتنزيل خط الرموز التعبيرية. يعدّل أيضًا البيانات الوصفية الضرورية للرموز التعبيرية التي تحتاجها مكتبة دعم EmojiCompat لمواكبة أحدث إصدارات مواصفات يونيكود.

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

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

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

  1. افتح ملف build.gradle لتطبيقك.
  2. أضِف مكتبة الدعم إلى القسم dependencies.

رائع

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

Kotlin

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

جارٍ إعداد إعدادات الخط القابلة للتنزيل

يجب إعداد EmojiCompat لتحميل البيانات الوصفية والخط الطباعي. وبما أنّ عملية الإعداد قد تستغرق بعض الوقت، يتم تنفيذ عملية الإعداد على سلسلة محادثات في الخلفية.

لإعداد EmojiCompat باستخدام إعدادات الخط القابلة للتنزيل، اتّبِع الخطوات التالية:

  1. يمكنك إنشاء مثيل للفئة FontRequest وتقديم مرجع موفّر الخط وحزمة موفِّر الخط وطلب البحث الخاص بالخط وقائمة علامات التجزئة الخاصة بالشهادة. لمزيد من المعلومات حول FontRequest، يمكنك الاطّلاع على القسم استخدام الخطوط القابلة للتنزيل آليًا ضمن مستندات الخطوط القابلة للتنزيل.
  2. يمكنك إنشاء مثيل للدالة FontRequestEmojiCompatConfig وتقديم نسخة افتراضية من Context وFontRequest.
  3. عليك إعداد EmojiCompat من خلال استدعاء الطريقة init() وتمرير مثيل FontRequestEmojiCompatConfig.

    4. Kotlin

    class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        val fontRequest = FontRequest(
                "com.example.fontprovider",
                "com.example",
                "emoji compat Font Query",
                CERTIFICATES
        )
        val config = FontRequestEmojiCompatConfig(this, fontRequest)
        EmojiCompat.init(config)
    }
}

    Java

    public class MyApplication extends Application {
  @Override
   public void onCreate() {
     super.onCreate();
     FontRequest fontRequest = new FontRequest(
       "com.example.fontprovider",
       "com.example",
       "emoji compat Font Query",
       CERTIFICATES);
     EmojiCompat.Config config = new FontRequestEmojiCompatConfig(this, fontRequest);
     EmojiCompat.init(config);
   }
}
  4. استخدام تطبيقات EmojiCompat المصغّرة بتنسيق XML إذا كنت تستخدم AppCompat، يمكنك الرجوع إلى القسم استخدام تطبيقات EmojiCompat المصغّرة مع AppCompat. 
    5. <android.support.text.emoji.widget.EmojiTextView
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

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

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

لمزيد من المعلومات حول طريقة ضبط EmojiCompat باستخدام إعدادات الخطوط القابلة للتنزيل، انتقِل إلى نموذج تطبيق توافق الرموز التعبيرية Java | Kotlin.

مكونات المكتبة

مكوّنات المكتبة في عملية EmojiCompat
الشكل 3. مكوّنات المكتبة في عملية EmojiCompat
التطبيقات المصغّرة: EmojiEditText وEmojiTextView وEmojiButton
عمليات تنفيذ التطبيقات المصغّرة التلقائية لاستخدام EmojiCompat مع TextView وEditText وButton
EmojiCompat
العرض العام الرئيسي لمكتبة الدعم. وهو تُجري جميع الاتصالات الخارجية والإحداثيات مع الأجزاء الأخرى من النظام.
EmojiCompat.Config
يضبط هذا الإعداد المثيل الفردي الذي سيتم إنشاؤه.
EmojiSpan
فئة فرعية ReplacementSpan تحلّ محل الحرف (التسلسلات) وتعرض الحرف الرسومي
الخط "EmojiCompat"
يستخدم EmojiCompat خطًا لعرض الرموز التعبيرية. هذا الخط هو نسخة معدَّلة من خط رموز Android التعبيرية. يتم تعديل الخط على النحو التالي:
  • لإتاحة التوافق مع الأنظمة القديمة لعرض الرموز التعبيرية، يتم تمثيل جميع أحرف الرموز التعبيرية بنقطة رمز يونيكود واحدة في منطقة الاستخدام الخاص التكميلية الإضافية في يونيكود التي تبدأ بالرمز U+F0001.
  • يتم إدراج البيانات الوصفية الإضافية للرموز التعبيرية بتنسيق ثنائي في الخط ويتم تحليلها في وقت التشغيل من خلال EmojiCompat. يتم تضمين البيانات في جدول meta الخاص بالخط، مع العلامة الخاصة Emji.

خيارات الإعداد

يمكنك استخدام المثيل EmojiCompat لتعديل سلوك EmojiCompat. يمكنك استخدام الطرق التالية من الفئة الأساسية لضبط الإعدادات:

  • setReplaceAll(): لتحديد ما إذا كان يجب على EmojiCompat استبدال كل الرموز التعبيرية التي يعثر عليها باستخدام EmojiSpans. وحسب الإعدادات التلقائية، يبذل EmojiCompat قصارى جهده لمعرفة ما إذا كان النظام يمكنه عرض رموز تعبيرية ولا يحلّ محلّها. عند ضبط السياسة على القيمة true، تستبدل EmojiCompat كل الرموز التعبيرية التي يعثر عليها بـ EmojiSpans.
  • setEmojiSpanIndicatorEnabled(): يشير إلى ما إذا كان EmojiCompat قد استبدل رمزًا تعبيريًا برمز EmojiSpan. وعند ضبط السياسة على true، يرسم EmojiCompat خلفية للسمة EmojiSpan. تُستخدم هذه الطريقة بشكل أساسي لأغراض تصحيح الأخطاء.
  • setEmojiSpanIndicatorColor(): لضبط اللون للإشارة إلى EmojiSpan القيمة التلقائية هي GREEN.
  • registerInitCallback: تُبلغ هذه السياسة التطبيق بحالة إعداد EmojiCompat.

Kotlin

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

Java

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. أضِف مكتبة الدعم إلى قسم الموارد التابعة.

    رائع

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

    Kotlin

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

    رائع

          dependencies {
          implementation "androidx.emoji:emoji-appcompat:$version"
      }
  2. استخدام أدوات EmojiCompat AppCompat Widget في تنسيق XML
    3. <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"
}

Kotlin

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

استخدام خطوط مجمّعة لضبط إعدادات EmojiCompat

لاستخدام الخطوط المجمّعة لضبط EmojiCompat، اتّبِع الخطوات التالية:

  1. استخدِم BundledEmojiCompatConfig لإنشاء مثيل من EmojiCompat وتقديم مثيل Context.
  2. ويمكنك استدعاء طريقة init() لإعداد EmojiCompat وتمرير مثيل BundledEmojiCompatConfig.

Kotlin

class MyApplication : Application() {

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

Java

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. باستخدام هذه الطريقة، يمكنك معالجة المثيلات التي تمت معالجتها وتخزينها مؤقتًا بدلاً من السلسلة الأولية، ما يؤدي إلى تحسين أداء تطبيقك.

Kotlin

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

Java

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

استخدام EmojiCompat مع أدوات IME

باستخدام مكتبة دعم 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 فئات المساعدة التالية في التطبيقات المصغّرة كي يتيح لك تحسين التطبيقات المصغّرة المخصّصة التي تتيح استخدام الرموز التعبيرية بأقل جهد ممكن.

نموذج 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 من نظام التشغيل Android (المستوى 19 من واجهة برمجة التطبيقات) أو الإصدارات الأقدم؟

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

مصادر إضافية

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