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

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

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

راجع الموارد ذات الصلة التالية:

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

كيف تعمل ميزة EmojiCompat؟

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

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

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

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

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

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

لاستخدام مكتبة دعم 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);
       }
    }
    
  5. استخدِم تطبيقات EmojiCompat المصغّرة في ملفات XML الخاصة بالتنسيق. إذا كنت تستخدم AppCompat، راجِع القسم استخدام تطبيقات EmojiCompat المصغّرة مع AppCompat.
  6. <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 التعبيرية. يتم تعديل الخط على النحو التالي:
  • لتوفير التوافق مع الأنظمة القديمة لعرض الرموز التعبيرية، يتم تمثيل جميع أحرف الرموز التعبيرية بنقطة رمز Unicode واحدة في منطقة الاستخدام الخاص التكميلية من Unicode التي تبدأ بالرمز 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 لأدوات تحرير أسلوب الإدخال

وباستخدام مكتبة الدعم 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 لعرض نص مخصَّص؟
  • نعم. توفّر ميزة EmojiCompat دروسًا مساعِدة في التطبيقات المصغّرة المخصّصة. ومن الممكن أيضًا إجراء معالجة مسبقة لسلسلة معيّنة وتحويلها إلى Spanned. لمزيد من المعلومات حول صفوف مساعد التطبيقات المصغّرة، يُرجى الرجوع إلى القسم استخدام EmojiCombat مع تطبيقات مصغّرة مخصّصة.

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

مراجع إضافية

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