إتاحة الرموز التعبيرية الحديثة

تتم إعادة تحميل المجموعة العادية من الرموز التعبيرية سنويًا باستخدام يونيكود، لأنّ استخدام الرموز التعبيرية يتزايد بسرعة لجميع أنواع التطبيقات.

إذا كان تطبيقك يعرض محتوى على الإنترنت أو يوفّر إدخالًا نصيًا، ننصحك بشدة بإتاحة استخدام أحدث خطوط الرموز التعبيرية. وبخلاف ذلك، قد يتم عرض الرموز التعبيرية اللاحقة على شكل مربّع مربّع صغير باسم tofu (☐) أو تسلسلات رموز تعبيرية يتم عرضها بشكل غير صحيح.

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

في ما يلي أمثلة على الرموز التعبيرية الحديثة.

وتوفر مكتبة androidx.emoji2:emoji2 توافقًا بسيطًا مع الإصدارات القديمة من Android. مكتبة emoji2 هي تابعة لمكتبة AppCompat ولا تتطلب أي إعدادات إضافية للعمل.

إتاحة الرموز التعبيرية في ميزة Compose

BOM آذار (مارس) 2023 (الإصدار 1.4 من واجهة Compose) هو توفير إمكانية استخدام أحدث إصدار من الرموز التعبيرية، بما في ذلك التوافق مع الإصدارات القديمة من Android وصولاً إلى واجهة برمجة التطبيقات 21. تتناول هذه الصفحة كيفية ضبط الرموز التعبيرية الحديثة في نظام العرض. يمكنك الاطّلاع على صفحة الرموز التعبيرية في "إنشاء" للتعرّف على مزيد من المعلومات.

المتطلّبات الأساسية

للتأكّد من أنّ تطبيقك يعرض الرموز التعبيرية الأحدث بشكل صحيح، يجب تشغيله على جهاز يعمل بالإصدار Android 10 (المستوى 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. يمكنك اختبار عملية الدمج من خلال تشغيل تطبيقك على جهاز يعمل بالإصدار 10 من نظام التشغيل Android أو إصدار أقدم وعرض سلسلة الاختبار التالية. تأكَّد من عرض كل الأحرف بشكل صحيح.

   • 14.0: 🫠، 🫱🏼 🫲🏿، 🫰🏽
   • 13.1: 📈 🌫️، 🧔 ♀️، 🧑🏿 ❤️ 🧑🏾
   • 13.0: 🥲، 🥷🏿، 🐻 ويتميز
   • 12.1: 🧑 🦰، 🧑🏿 🦯، 👩 🤝 👩🏼
   • 12.0: 🦩، 🦻🏿، 👩🏼 🤝 👩

يعرض تطبيقك تلقائيًا الرموز التعبيرية المتوافقة مع الإصدارات القديمة على جميع الأجهزة التي توفّر موفِّر خطوط قابلاً للتنزيل ومتوافق مع emoji2، مثل الأجهزة المستنِدة إلى خدمات Google Play.

إذا كان تطبيقك يستخدم AppCompat ولكنه يعرض التوفو (☐)

في بعض الحالات، قد يعرض تطبيقك التوفو بدلاً من الرموز التعبيرية المناسبة، حتى إذا أضفت مكتبة AppCompat. فيما يلي التفسيرات والحلول المحتملة.

إذا كنت تشغِّل التطبيق على جهاز تم تثبيت تثبيت أحدث إصدار منه مؤخرًا أو محاكي جديد

يمكنك محو بيانات "خدمات Google Play" الخاصة بالتطبيق لمحو أي تخزين مؤقت للخط قد يحدث أثناء بدء التشغيل. ويؤدي هذا عادةً إلى حل المشكلة بعد بضع ساعات.

لمحو بيانات التطبيق، يمكنك اتّباع الخطوات التالية:

1. افتح الإعدادات على جهازك الذي يعمل بنظام التشغيل Android.

2. انقر على التطبيقات والإشعارات.

3. انقر على عرض كل التطبيقات أو معلومات التطبيق.

4. تصفَّح التطبيقات وانقر على خدمات Google Play.

5. انقر على مساحة التخزين وذاكرة التخزين المؤقت.

6. انقر على محو ذاكرة التخزين المؤقت.

لا يستخدم تطبيقك صفًا مرتبطًا بالنص في AppCompat

وقد يحدث ذلك في حال عدم تمديد السمة AppCompatActivity أو إنشاء مثيل طريقة عرض في رمز، مثل TextView. تحقَّق ممّا يلي:

• يمتد النشاط لمدة AppCompatActivity.
• إذا كنت تنشئ طريقة العرض في رمز برمجي، استخدِم الفئة الفرعية AppCompat الصحيحة.

يعمل AppCompatActivity تلقائيًا على تضخيم AppCompatTextView بدلاً من TextView عند تضخيم XML، لذلك لن تحتاج إلى تعديل XML.

لا يتيح الهاتف الاختباري استخدام الخطوط القابلة للتنزيل

تأكَّد من أنّ DefaultEmojiCompatConfig.create يعرض إعدادات غير فارغة.

لم يعمد محاكي على مستوى واجهة برمجة تطبيقات سابق إلى ترقية "خدمات Google Play"

عند استخدام محاكي على مستوى واجهة برمجة تطبيقات سابق، قد تحتاج إلى تحديث "خدمات Google Play" المجمّعة في emoji2 للعثور على موفِّر الخط. للقيام بذلك، سجل الدخول إلى متجر Google Play على المحاكي.

للتأكّد من تثبيت إصدار متوافق، اتّبِع الخطوات التالية:

1. شغِّل الأمر التالي:

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

2. تأكَّد من أنّ قيمة versionCode أعلى من 211200000.

دعم الرموز التعبيرية بدون استخدام AppCompat

إذا تعذّر على تطبيقك تضمين AppCompat، يمكنه استخدام emoji2 مباشرةً. وتتطلب هذه الطريقة المزيد من العمل، لذا لا تستخدِم هذه الطريقة إلّا إذا كان تطبيقك لا يمكنه استخدام AppCompat.

لإتاحة الرموز التعبيرية بدون مكتبة "AppCompat"، عليك اتّباع الخطوات التالية:

1. في ملف 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 فئات فرعية من TextView وButton وEditText التي تطبّق EmojiCompat. لا تستخدِمه في تطبيق يتضمّن AppCompat لأنه ينفّذ EmojiCompat.

2. في تنسيق XML والرمز البرمجي، أينما كنت تستخدم TextView أو EditText أو Button، يمكنك استخدام EmojiTextView أو EmojiEditText أو EmojiButton بدلاً من ذلك.

   activity_main.xml
   
   <androidx.emoji2.widget.EmojiTextView ... />
   <androidx.emoji2.widget.EmojiEditText ... />
   <androidx.emoji2.widget.EmojiButton ... />
   

   من خلال تضمين وحدة emoji2، يستخدم النظام موفّر الخطوط التلقائي القابل للتنزيل من أجل تحميل خط الرمز التعبيري تلقائيًا بعد بدء تشغيل التطبيق بفترة قصيرة. ولا يلزم إجراء أي إعدادات أخرى.

3. لاختبار عملية الدمج، شغِّل تطبيقك على جهاز يعمل بالإصدار 11 من نظام التشغيل Android أو إصدار أقدم ويعرض سلاسل الاختبار التالية. تأكَّد من عرض كل الأحرف بشكل صحيح.

   • 14.0: 🫠، 🫱🏼 🫲🏿، 🫰🏽
   • 13.1: 📈 🌫️، 🧔 ♀️، 🧑🏿 ❤️ 🧑🏾
   • 13.0: 🥲، 🥷🏿، 🐻 ويتميز
   • 12.1: 🧑 🦰، 🧑🏿 🦯، 👩 🤝 👩🏼
   • 12.0: 🦩، 🦻🏿، 👩🏼 🤝 👩

استخدام ميزة EmojiCompat بدون التطبيقات المصغّرة

تستخدم ميزة "EmojiCompat" السمة EmojiSpan لعرض الصور الصحيحة. لذلك، يجب تحويل أي عنصر CharSequence محدّد إلى عنصر Spanned يحتوي على كائنات EmojiSpan. توفّر فئة EmojiCompat الطريقة process() لتحويل CharSequences إلى Spanned مثيل. وباستخدام هذه الطريقة، يمكنك استدعاء الدالة process() في الخلفية وتخزين النتائج في ذاكرة التخزين المؤقت، الأمر الذي يحسّن أداء تطبيقك.

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

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

استخدام EmojiCompat لتحرير أسلوب الإدخال

تتيح الفئة EmojiCompat للوحات المفاتيح عرض الرموز التعبيرية المتوافقة مع التطبيق الذي تتفاعل معه. بإمكان محرِّري أساليب الإدخال استخدام الطريقة getEmojiMatch() للتحقّق مما إذا كان مثيل EmojiCompat قادرًا على عرض رمز تعبيري. تستخدم هذه الطريقة CharSequence من الرمز التعبيري، وتعرض true إذا كان بإمكان EmojiCompat اكتشاف الرمز التعبيري وعرضه.

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

إضافة طرق عرض مخصّصة للتطبيقات التي لا تتوفّر لها منصّة AppCompat

إذا كان تطبيقك لا يستخدم AppCompat، استخدِم أدوات مساعدة دمج العرض في وحدة emoji2-views-helper المصمّمة للاستخدام في طرق العرض المخصّصة. وهذه هي الأدوات المساعدة التي تستخدمها مكتبة AppCompat لإتاحة الرموز التعبيرية.

أكمِل الخطوات التالية لإتاحة طرق العرض المخصّصة للتطبيقات التي لا تستخدم AppCompat.

1. إضافة مكتبة emoji2-views-helper:

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

2. اتّبِع التعليمات لتضمين EmojiTextViewHelper أو EmojiEditTextHelper في طرق العرض المخصّصة لتطبيقك.

3. يمكنك اختبار عملية الدمج من خلال تشغيل تطبيقك على جهاز يعمل بالإصدار 10 من نظام التشغيل Android أو إصدار أقدم وعرض سلسلة الاختبار التالية. تأكَّد من عرض كل الأحرف بشكل صحيح.

   • 14.0: 🫠، 🫱🏼 🫲🏿، 🫰🏽
   • 13.1: 📈 🌫️، 🧔 ♀️، 🧑🏿 ❤️ 🧑🏾
   • 13.0: 🥲، 🥷🏿، 🐻 ويتميز
   • 12.1: 🧑 🦰، 🧑🏿 🦯، 👩 🤝 👩🏼
   • 12.0: 🦩، 🦻🏿، 👩🏼 🤝 👩

ميزات اختيارية للتعامل مع الرموز التعبيرية 2

بعد تضمين مكتبة emoji2 في تطبيقك، يمكنك إضافة الميزات الاختيارية الموضّحة في هذا القسم.

إعداد رمز تعبيري 2 لاستخدام خط مختلف أو موفّر خطوط قابل للتنزيل

لضبط 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. نفّذ أيًا مما يلي:

   • يمكنك استخدام الإعدادات التلقائية من خلال استدعاء DefaultEmojiCompatConfiguration.create(context).

   • يمكنك إنشاء الإعدادات الخاصة بك لتحميل الخطوط من مصدر آخر باستخدام EmojiCompat.Config. توفّر هذه الفئة عدة خيارات لتعديل سلوك EmojiCompat كما هو موضّح في القسم التالي.

تعديل سلوك 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.

التوافق مع الخطوط المضمَّنة في الرموز التعبيرية 2

يمكنك استخدام عناصر "emoji2-bundled" لتجميع خط الرموز التعبيرية في تطبيقك. ومع ذلك، ننصح بشدة بأن يستخدم تطبيقك الخطوط القابلة للتنزيل متى أمكن نظرًا لأنّ حجم الخط NotoColorEmoji أكبر من 10 ميغابايت. إنّ عناصر emoji2-bundled مخصّصة للتطبيقات على الأجهزة التي لا تتيح الخطوط القابلة للتنزيل.

لاستخدام عنصر "emoji2-bundled"، اتّبِع الخطوات التالية:

1. تضمين emoji2-bundled وemoji2 عنصر:

   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. اختبِر عملية الدمج باتّباع الخطوات السابقة لتضمين emojicompat مع السمة AppCompat أو بدونها. تأكَّد من عرض سلسلة الاختبار بشكل صحيح

   • 14.0: 🫠، 🫱🏼 🫲🏿، 🫰🏽
   • 13.1: 📈 🌫️، 🧔 ♀️، 🧑🏿 ❤️ 🧑🏾
   • 13.0: 🥲، 🥷🏿، 🐻 ويتميز
   • 12.1: 🧑 🦰، 🧑🏿 🦯، 👩 🤝 👩🏼
   • 12.0: 🦩، 🦻🏿، 👩🏼 🤝 👩

تأثير ضبط EmojiCompat التلقائي

يطبِّق النظام الإعدادات التلقائية باستخدام مكتبة بدء التشغيل وEmojiCompatInitializer و DefaultEmojiCompatConfig.

بعد استئناف النشاط الأول في تطبيقك، تجدول أداة الإعداد تحميل خط الرموز التعبيرية. وتتيح هذه المهلة القصيرة لتطبيقك عرض المحتوى الأولي بدون أي وقت استجابة محتمل بسبب تحميل الخط في سلسلة محادثات في الخلفية.

يبحث DefaultEmojiCompatConfig عن موفِّر خطوط قابل للتنزيل مثبَّت من النظام ينفِّذ واجهة EmojiCompat، مثل خدمات Google Play. في الأجهزة المتوافقة مع "خدمات Google Play"، يؤدي هذا الإجراء إلى تحميل الخط باستخدام "خدمات Google Play".

ينشئ برنامج الإعداد سلسلة محادثات في الخلفية لتحميل خط الرموز التعبيرية، ويمكن أن يستغرق تنزيل الخط مدة تصل إلى 10 ثوانٍ قبل انتهاء المهلة. بعد تنزيل الخط، يستغرق إعداد EmojiCompat حوالي 150 مللي ثانية في سلسلة محادثات في الخلفية.

يمكنك تأجيل إعداد EmojiCompat حتى في حال إيقاف EmojiCompatInitializer. في حال ضبط إعدادات EmojiCompat يدويًا، يمكنك طلب الرقم EmojiCompat.load() بعد عرض الشاشة الأولى من تطبيقك لتجنّب حدوث تعارض في الخلفية مع أوّل تحميل للشاشة.

بعد التحميل، يستخدم EmojiCompat حوالي 300 كيلوبايت من ذاكرة الوصول العشوائي للاحتفاظ بالبيانات الوصفية للرموز التعبيرية.