سازگاری Emoji

احتیاط: از اواخر سال 2021، کتابخانه androidx.emoji:emoji به نفع androidx.emoji2:emoji2 منسوخ شده است، که ادغام با androidx.appcompat را فراهم می کند.

برای پشتیبانی از ایموجی‌های مدرن و ساده‌سازی سازگاری با نسخه‌های پایین‌تر اندروید، توصیه می‌شود به کتابخانه androidx.emoji2:emoji2 مهاجرت کنید. برای جزئیات در مورد نحوه پیاده سازی، به پشتیبانی از شکلک مدرن مراجعه کنید.

هدف کتابخانه پشتیبانی EmojiCompat این است که دستگاه های اندرویدی را با جدیدترین شکلک ها به روز نگه دارد. از نشان دادن کاراکترهای ایموجی گمشده به شکل ☐ که نشان می‌دهد دستگاه شما فونتی برای نمایش متن ندارد، از نمایش برنامه شما جلوگیری می‌کند. با استفاده از کتابخانه پشتیبانی EmojiCompat ، کاربران برنامه شما برای دریافت جدیدترین ایموجی نیازی به انتظار برای به روز رسانی سیستم عامل اندروید ندارند.

شکل 1. مقایسه ایموجی

به منابع مرتبط زیر مراجعه کنید:

• نمونه برنامه سازگاری ایموجی جاوا | کاتلین

EmojiCompat چگونه کار می کند؟

کتابخانه پشتیبانی EmojiCompat کلاس‌هایی را برای پیاده‌سازی پشتیبانی از شکلک‌های سازگار با عقب در دستگاه‌های دارای Android 4.4 (سطح API 19) و بالاتر ارائه می‌دهد. می توانید EmojiCompat با فونت های همراه یا قابل دانلود پیکربندی کنید. برای اطلاعات بیشتر در مورد پیکربندی، به بخش های زیر مراجعه کنید:

• پیکربندی فونت های قابل دانلود
• پیکربندی فونت های همراه

EmojiCompat ایموجی‌ها را برای یک CharSequence مشخص می‌کند، در صورت لزوم با EmojiSpans جایگزین می‌کند و در نهایت شکلک‌های اموجی را رندر می‌کند. شکل 2 روند را نشان می دهد.

شکل 2. فرآیند EmojiCompat

پیکربندی فونت های قابل دانلود

پیکربندی فونت‌های قابل دانلود از ویژگی کتابخانه پشتیبانی از فونت‌های دانلود برای دانلود فونت ایموجی استفاده می‌کند. همچنین فراداده‌های Emoji ضروری را که کتابخانه پشتیبانی EmojiCompat برای همگام شدن با آخرین نسخه‌های مشخصات یونیکد به آن نیاز دارد، به‌روزرسانی می‌کند.

افزودن وابستگی به کتابخانه پشتیبانی

برای استفاده از کتابخانه پشتیبانی 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. نمونه ای از کلاس FontRequest ایجاد کنید و مرجع ارائه دهنده فونت، بسته ارائه دهنده فونت، پرس و جو فونت و لیستی از مجموعه های هش را برای گواهی ارائه دهید. برای اطلاعات بیشتر در مورد FontRequest ، به بخش استفاده از فونت های دانلودی به صورت برنامه ای در مستندات فونت های دانلودی مراجعه کنید.
2. یک نمونه از FontRequestEmojiCompatConfig ایجاد کنید و نمونه هایی از Context و FontRequest را ارائه دهید.
3. EmojiCompat با فراخوانی متد init() راه اندازی کنید و نمونه FontRequestEmojiCompatConfig را ارسال کنید.

کاتلین

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)
    }
}

جاوا

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 استفاده می کنید، به بخش Using EmojiCompat widgets with 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 | کاتلین .

اجزای کتابخانه

شکل 3. اجزای کتابخانه در فرآیند EmojiCompat

ابزارک ها: EmojiEditText ، EmojiTextView ، EmojiButton

اجرای پیش‌فرض ویجت برای استفاده از EmojiCompat با TextView ، EditText و Button .

EmojiCompat

سطح عمومی اصلی برای کتابخانه پشتیبانی. تمام تماس های خارجی را انجام می دهد و با سایر قسمت های سیستم هماهنگ می شود.

EmojiCompat.Config

نمونه singleton را برای ایجاد پیکربندی می کند.

EmojiSpan

یک زیرکلاس ReplacementSpan که جایگزین کاراکتر (دنباله ها) می شود و گلیف را رندر می کند.

قلم EmojiCompat

EmojiCompat از یک فونت برای نمایش ایموجی استفاده می کند. این فونت نسخه اصلاح شده فونت ایموجی اندروید است. فونت به صورت زیر اصلاح می شود:

• برای ارائه سازگاری به عقب برای ارائه ایموجی، همه کاراکترهای ایموجی با یک نقطه کد یونیکد در منطقه استفاده خصوصی تکمیلی یونیکد-A که با U+F0001 شروع می‌شود، نشان داده می‌شوند.
• فراداده اضافی emoji در قالب باینری در فونت درج می شود و در زمان اجرا توسط EmojiCompat تجزیه می شود. داده ها در جدول meta فونت با برچسب خصوصی Emji جاسازی شده است.

گزینه های پیکربندی

می توانید از نمونه EmojiCompat برای تغییر رفتار EmojiCompat استفاده کنید. برای تنظیم پیکربندی می توانید از روش های زیر از کلاس پایه استفاده کنید:

• setReplaceAll() : تعیین می کند که آیا EmojiCompat باید همه ایموجی هایی را که پیدا می کند با EmojiSpans جایگزین کند یا خیر. به‌طور پیش‌فرض، EmojiCompat تمام تلاش خود را می‌کند تا بفهمد آیا سیستم می‌تواند یک ایموجی را ارائه کند و جایگزین آن شکلک‌ها نمی‌شود. وقتی روی true تنظیم شود، EmojiCompat همه شکلک‌هایی را که پیدا می‌کند با EmojiSpans جایگزین می‌کند.
• setEmojiSpanIndicatorEnabled() : نشان می دهد که آیا EmojiCompat یک ایموجی را با EmojiSpan جایگزین کرده است یا خیر. هنگامی که روی true تنظیم می شود، EmojiCompat یک پس زمینه برای EmojiSpan ترسیم می کند. این روش عمدتاً برای اهداف اشکال زدایی استفاده می شود.
• setEmojiSpanIndicatorColor() : رنگ را برای نشان دادن EmojiSpan تنظیم می کند. مقدار پیش فرض GREEN است.
• registerInitCallback : به برنامه در مورد وضعیت اولیه سازی EmojiCompat اطلاع می دهد.

کاتلین

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. کتابخانه پشتیبانی را به بخش وابستگی ها اضافه کنید.

   شیار

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

   کاتلین

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

   شیار

         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. برای مقداردهی اولیه EmojiCompat و ارسال نمونه BundledEmojiCompatConfig متد init() را فراخوانی کنید.

کاتلین

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 با EmojiSpans به نمونه‌های Spanned تبدیل کند. کلاس EmojiCompat روشی برای تبدیل CharSequences به نمونه های Spanned با EmojiSpans ارائه می دهد. با استفاده از این روش، می‌توانید نمونه‌های پردازش‌شده را به‌جای رشته خام پردازش و ذخیره کنید، که باعث بهبود عملکرد برنامه شما می‌شود.

کاتلین

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

جاوا

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

استفاده از EmojiCompat برای IME

با استفاده از کتابخانه پشتیبانی EmojiCompat ، صفحه‌کلیدها می‌توانند شکلک‌هایی را که توسط برنامه‌ای که در حال تعامل با آن هستند، پشتیبانی می‌کنند. IME ها می توانند از متد hasEmojiGlyph() برای بررسی اینکه آیا EmojiCompat قادر به ارائه ایموجی است یا خیر استفاده کنند. این روش یک CharSequence از یک ایموجی را می گیرد و اگر EmojiCompat بتواند ایموجی را شناسایی و رندر کند، true را برمی گرداند.

صفحه‌کلید همچنین می‌تواند نسخه کتابخانه پشتیبانی 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 نمونه

کاتلین

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)
    }
}

جاوا

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() {
       ...
   }
}

ویرایش متن نمونه

کاتلین

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
    }
}

جاوا

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 از چه مقدار حافظه استفاده می کند؟

در حال حاضر، ساختار داده برای یافتن ایموجی در حافظه برنامه بارگذاری شده است و از حدود 200 کیلوبایت استفاده می کند.

• آیا می توانم از EmojiCompat برای TextView سفارشی استفاده کنم؟

بله EmojiCompat کلاس های کمکی را برای ویجت های سفارشی ارائه می دهد. همچنین امکان پیش پردازش یک رشته داده شده و تبدیل آن به Spanned وجود دارد. برای اطلاعات بیشتر در مورد کلاس های کمکی ویجت، به بخش استفاده از EmojiCompat با ابزارک های سفارشی مراجعه کنید.

• اگر ویجت‌ها را در طرح‌بندی XML در دستگاه‌هایی که دارای Android نسخه 4.4 (سطح API 19) یا پایین‌تر هستند، اضافه کنم، چه اتفاقی می‌افتد؟

می‌توانید کتابخانه پشتیبانی EmojiCompat یا ویجت‌های آن را در برنامه‌های خود قرار دهید که از دستگاه‌های دارای Android 4.4 (سطح API 19) یا پایین‌تر پشتیبانی می‌کنند. با این حال، اگر دستگاهی بر روی نسخه اندرویدی قبل از سطح API 19 اجرا شود، EmojiCompat و ویجت‌های آن در حالت "بدون عملیات" هستند. این بدان معنی است که EmojiTextView دقیقاً مانند یک TextView معمولی رفتار می کند. نمونه EmojiCompat ؛ هنگامی که متد init() را فراخوانی می کنید، بلافاصله به حالت LOAD_STATE_SUCCEEDED می رسد.

منابع اضافی

برای اطلاعات بیشتر در مورد استفاده از کتابخانه EmojiCompat ، EmojiCompat را تماشا کنید.