سازگاری Emoji

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

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

نمونه نمای متن

کاتلین

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

سوالات متداول

• چگونه دانلود فونت را شروع کنم؟

فونت‌های ایموجی در صورت عدم وجود در دستگاه، با اولین درخواست دانلود می‌شوند. زمان‌بندی دانلود برای برنامه شفاف است.

• چقدر زمان برای مقداردهی اولیه لازم است؟

پس از دانلود فونت، تقریباً ۱۵۰ میلی‌ثانیه طول می‌کشد تا EmojiCompat راه‌اندازی شود.

• کتابخانه پشتیبانی EmojiCompat چقدر حافظه استفاده می‌کند؟

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

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

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

• اگر در دستگاه‌هایی که اندروید ۴.۴ (سطح API ۱۹) یا پایین‌تر دارند، ویجت‌هایی را در فایل‌های XML طرح‌بندی اضافه کنم، چه اتفاقی می‌افتد؟

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

منابع اضافی

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