תאימות לאמוג'י

זהירות: בסוף שנת 2021, הספרייה androidx.emoji:emoji הוצאה משימוש לטובת androidx.emoji2:emoji2, שמאפשרת שילוב ב-androidx.appcompat.

כדי לתמוך בסמלי אמוג'י מודרניים ולפשט את התאימות לאחור לגרסאות ישנות יותר של Android, מומלץ לעבור לספרייה androidx.emoji2:emoji2. פרטים על ההטמעה מופיעים במאמר תמיכה בסמלי אמוג'י מודרניים.

מטרת ספריית התמיכה EmojiCompat היא לוודא שמכשירי Android מעודכנים בסמלי האמוג'י החדשים ביותר. היא מונעת מהאפליקציה להציג תווים חסרים של אמוג'י בצורת ☐, שמציינת שאין במכשיר גופן להצגת הטקסט. כשמשתמשים בספריית התמיכה EmojiCompat, משתמשי האפליקציה לא צריכים להמתין לעדכונים של Android OS כדי לקבל את הסמלי ה-emoji העדכניים ביותר.

איור 1. השוואה בין אמוג'י

כדאי לעיין במקורות המידע הבאים:

• אפליקציית דוגמה לתאימות לסמלי אמוג'י Java | Kotlin

איך פועל EmojiCompat?

ספריית התמיכה EmojiCompat מספקת כיתות להטמעת תמיכה בסמלי אמוג'י עם תאימות לאחור במכשירים עם Android מגרסה 4.4 (API ברמה 19) ואילך. אפשר להגדיר את EmojiCompat עם גופנים בחבילה או גופנים שניתן להוריד. למידע נוסף על הגדרה, קראו את הקטע הבא:

• הגדרת גופנים שניתן להורדה
• הגדרת גופנים בחבילה

EmojiCompat מזהה אמוג'י עבור CharSequence נתון, מחליף אותם ב-EmojiSpans אם צריך, ובסוף מעבד את הגליפים של האמוג'י. איור 2 מדגים את התהליך.

איור 2. התהליך של EmojiCompat

הגדרת גופנים שניתן להורדה

ההגדרה של גופני ההורדה משתמשת בתכונה של ספריית התמיכה של גופני ההורדה כדי להוריד גופן אמוג'י. הוא גם מעדכן את המטא-נתונים הנדרשים של אמוג'י שספריית התמיכה EmojiCompat צריכה כדי לעמוד בגרסאות האחרונות של מפרט Unicode.

הוספת תלות בספריית תמיכה

כדי להשתמש בספריית התמיכה EmojiCompat, צריך לשנות את יחסי התלות של classpath בפרויקט האפליקציה בסביבת הפיתוח.

כדי להוסיף ספריית תמיכה לפרויקט האפליקציה:

1. פותחים את הקובץ build.gradle של האפליקציה.
2. מוסיפים את ספריית התמיכה לקטע dependencies.

Groovy

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. מפעילים את השיטה init() ומעבירים את המופע של FontRequestEmojiCompatConfig כדי לאתחל את EmojiCompat.

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.

<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 עם הגדרת הגופן שניתן להורדה זמין באפליקציית הדוגמה ל-Emoji Compatibility ב-Java | Kotlin.

רכיבי הספרייה

איור 3. רכיבי הספרייה בתהליך EmojiCompat

ווידג'טים: EmojiEditText,‏ EmojiTextView,‏ EmojiButton

הטמעות ברירת מחדל של ווידג'טים לשימוש ב-EmojiCompat עם TextView,‏ EditText ו-Button.

EmojiCompat

הדף הציבורי הראשי של ספריית התמיכה. הוא מבצע את כל הקריאות החיצוניות ומתאם עם החלקים האחרים במערכת.

EmojiCompat.Config

הגדרת המכונה היחידה (singleton) שתיווצר.

EmojiSpan

Subclass של ReplacementSpan שמחליף את התו (המחרוזות) ומעבד את הגליף.

EmojiCompat גופן

EmojiCompat משתמש בגופן כדי להציג אמוג'י. הגופן הזה הוא גרסה שונה של הגופן של אמוג'י ב-Android. הגופן משתנה באופן הבא:

• כדי לספק תאימות לאחור לעיבוד אמוג'י, כל תווים האמוג'י מיוצגים בנקודת קוד אחת ב-Unicode, באזור ה-A המשלים לשימוש פרטי, החל מ-U+F0001.
• מטא-נתונים נוספים של אמוג'י מוכנסים לפורמט בינארי בגופן, ומנותחים בסביבת זמן הריצה על ידי EmojiCompat. הנתונים מוטמעים בטבלה meta של הגופן, עם התג הפרטי Emji.

אפשרויות הגדרה

אפשר להשתמש במכונה EmojiCompat כדי לשנות את ההתנהגות של EmojiCompat. כדי להגדיר את ההגדרות, אפשר להשתמש בשיטות הבאות מהקלאס הבסיסי:

• setReplaceAll(): קובע אם EmojiCompat יחליף את כל האמוג'י שהוא מוצא ב-EmojiSpans. כברירת מחדל, הפונקציה EmojiCompat מנסה כמיטב יכולתה להבין אם המערכת יכולה להציג אמוג'י מסוים, ולא מחליפה את האמוג'י האלה. כשהערך של EmojiCompat מוגדר כ-true, הוא מחליף את כל סמלי האמוג'י שהוא מוצא ב-EmojiSpans.
• setEmojiSpanIndicatorEnabled(): מציין אם EmojiCompat החליף אמוג'י ב-EmojiSpan. כשהערך של true הוא true, ה-EmojiCompat מצייר רקע ל-EmojiSpan. השיטה הזו משמשת בעיקר למטרות ניפוי באגים.
• setEmojiSpanIndicatorColor(): הגדרת הצבע לציון EmojiSpan. ערך ברירת המחדל הוא GREEN.
• registerInitCallback: מעדכן את האפליקציה לגבי המצב של ה-initialization של 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() כדי לרשום קריאה חוזרת (callback) לצורך אתחול. כדי להשתמש בשיטות האלה, צריך ליצור מכונה של הכיתה 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 עם הגדרת גופן בחבילה, צריך לשנות את יחסי התלות של classpath בפרויקט האפליקציה בסביבת הפיתוח.

כדי להוסיף ספריית תמיכה לפרויקט האפליקציה:

1. פותחים את הקובץ build.gradle של האפליקציה.
2. מוסיפים את ספריית התמיכה לקטע dependencies.

Groovy

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

Kotlin

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

שימוש בגופנים בחבילה כדי להגדיר את EmojiCompat

כדי להשתמש בגופנים בחבילה כדי להגדיר את EmojiCompat:

1. משתמשים ב-BundledEmojiCompatConfig כדי ליצור מכונה של EmojiCompat ולספק מכונה של Context.
2. קוראים ל-method‏ 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, המקלדת יכולה להשתמש ב-method‏ hasEmojiGlyph(), כאשר metadataVersion הוא הערך של EDITOR_INFO_METAVERSION_KEY, כדי לבדוק אם האפליקציה יכולה להציג אמוג'י ספציפי.

שימוש ב-EmojiCompat עם ווידג'טים מותאמים אישית

תמיד אפשר להשתמש ב-method‏ 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() {
       ...
   }
}

שאלות נפוצות

• איך מתחילים את הורדת הגופן?

גופני האמוג'י מורידים בבקשה הראשונה, אם הם לא קיימים במכשיר. תזמון ההורדה שקוף לאפליקציה.

• כמה זמן נמשכת האינטוליזציה?

אחרי הורדת הגופן, נדרש זמן של כ-150 אלפיות שנייה כדי לאתחל את EmojiCompat.

• כמה זיכרון צורכת ספריית התמיכה של EmojiCompat?

נכון לעכשיו, מבנה הנתונים לחיפוש האמוג'י נטען בזיכרון של האפליקציה ומשתמש ב-200KB בערך.

• האם אפשר להשתמש ב-EmojiCompat ב-TextView בהתאמה אישית?

כן. EmojiCompat מספק כיתות עזר לווידג'טים מותאמים אישית. אפשר גם לעבד מחרוזת נתונה ולבצע לה המרה ל-Spanned. מידע נוסף על כיתות עזר של ווידג'טים זמין בקטע שימוש ב-EmojiCompat עם ווידג'טים מותאמים אישית.

• מה קורה אם מוסיפים ווידג'טים בקובצי XML של פריסה במכשירים שפועלת בהם מערכת Android מגרסה 4.4 (API ברמה 19) ומטה?

אפשר לכלול את ספריית התמיכה EmojiCompat או את הווידג'טים שלה באפליקציות שתומכות במכשירים עם Android מגרסה 4.4 (רמת API 19) ומטה. עם זאת, אם במכשיר פועלת גרסה של Android שקדמה לרמת API‏ 19, EmojiCompat והווידג'טים שלו נמצאים במצב 'אין פעולה'. כלומר, EmojiTextView מתנהג בדיוק כמו TextView רגיל. מכונה של EmojiCompat, והיא עוברת למצב LOAD_STATE_SUCCEEDED מיד כשקוראים לשיטה init().

מקורות מידע נוספים

למידע נוסף על השימוש בספרייה EmojiCompat, אפשר לצפות בסרטון EmojiCompat.