این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

پشتیبانی از ایموجی های مدرن

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

اگر برنامه شما محتوای اینترنتی را نمایش می‌دهد یا ورودی متن ارائه می‌دهد، ما قویاً توصیه می‌کنیم از جدیدترین فونت‌های ایموجی پشتیبانی کنید. در غیر این صورت، شکلک‌های بعدی ممکن است به‌عنوان یک جعبه مربع کوچک به نام توفو (☐) یا سایر دنباله‌های شکلک‌هایی که به اشتباه رندر شده‌اند نمایش داده شود.

نسخه‌های اندروید 11 (سطح API 30) و پایین‌تر نمی‌توانند فونت ایموجی را به‌روزرسانی کنند، بنابراین برنامه‌هایی که آن‌ها را در آن نسخه‌ها نمایش می‌دهند باید به‌صورت دستی به‌روزرسانی شوند.

موارد زیر نمونه هایی از ایموجی های مدرن هستند.

نمونه ها	نسخه
🫠 🏼‍🫲🏿 🫰🏽	14.0 (سپتامبر 2021)
😶‍🌫️ 🧔🏻‍♀️ 🧑🏿‍❤️‍🧑🏾	13.1 (سپتامبر 2020)
🥲 🥷🏿 🐻‍❄️	13.0 (مارس 2020)
🧑🏻‍🦰 🧑🏿‍🦯 👩🏻‍🤝‍👩🏼	12.1 (اکتبر 2019)
🦩 🦻🏿 👩🏼‍🤝‍👩🏻	12.0 (فوریه 2019)

کتابخانه androidx.emoji2:emoji2 سازگاری ساده‌تری را با نسخه‌های پایین‌تر اندروید ارائه می‌کند. کتابخانه emoji2 یک وابستگی به کتابخانه AppCompat است و برای کار کردن به پیکربندی بیشتری نیاز ندارد.

پشتیبانی از ایموجی در Compose

BOM March 2023 ( Compose UI 1.4 ) از آخرین نسخه شکلک‌ها پشتیبانی می‌کند، از جمله سازگاری با نسخه‌های قدیمی‌تر Android تا API 21. این صفحه نحوه پیکربندی ایموجی‌های مدرن در سیستم View را پوشش می‌دهد. برای اطلاعات بیشتر به صفحه Emoji in Compose مراجعه کنید.

پیش نیازها

برای تأیید اینکه برنامه شما به‌درستی شکلک‌های جدیدتر را نمایش می‌دهد، آن را روی دستگاهی راه‌اندازی کنید که Android 10 (سطح API 29) یا پایین‌تر دارد. این صفحه شامل ایموجی های مدرنی است که می توانید برای آزمایش نمایش دهید.

از AppCompat برای پشتیبانی از آخرین ایموجی استفاده کنید

AppCompat 1.4 شامل پشتیبانی از ایموجی است.

برای استفاده از AppCompat برای پشتیبانی از ایموجی، موارد زیر را انجام دهید:

بررسی کنید که ماژول شما به کتابخانه AppCompat نسخه 1.4.0-alpha01 یا بالاتر بستگی دارد.
```
build.gradle

// Ensure version is 1.4.0-alpha01 or higher.
implementation "androidx.appcompat:appcompat.$appcompatVersion"
```
اطمینان حاصل کنید که تمام فعالیت هایی که متن را نمایش می دهند، کلاس AppCompatActivity را گسترش می دهند.
کاتلین
MyActivity.kt class MyActivity: AppCompatActivity { ... }
جاوا
MyActivity.java class MyActivity extends AppCompatActivity { ... }
ادغام خود را با راه‌اندازی برنامه خود در دستگاهی که Android 10 یا پایین‌تر دارد و نمایش رشته آزمایشی زیر آزمایش کنید. مطمئن شوید که همه کاراکترها به درستی ارائه می شوند.
- 14.0: 🫠، 🫱🏼‍🫲🏿، 🫰🏽
- 13.1: 😶‍🌫️، 🧔🏻‍♀️، 🧑🏿‍❤️‍🧑🏾
- 13.0: 🥲، 🥷🏿، 🐻‍❄️
- 12.1: 🧑🏻‍🦰، 🧑🏿‍🦯، 👩🏻‍🤝‍👩🏼
- 12.0: 🦩، 🦻🏿، 👩🏼‍🤝‍👩🏻

برنامه شما به‌طور خودکار شکلک‌های سازگار با عقب را در همه دستگاه‌هایی که ارائه‌دهنده فونت‌های قابل دانلود سازگار با emoji2 ارائه می‌کنند، مانند دستگاه‌هایی که توسط سرویس‌های Google Play ارائه می‌شوند، نمایش می‌دهد.

اگر برنامه شما از AppCompat استفاده می کند اما توفو را نمایش می دهد (☐)

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

شما برنامه را روی دستگاهی که اخیراً فلش شده یا شبیه ساز جدیدی اجرا می کنید

داده‌های سرویس‌های Google Play برنامه را برای پاک کردن حافظه پنهان فونت که ممکن است در حین راه‌اندازی رخ دهد، پاک کنید. این معمولاً بعد از چند ساعت مشکل را حل می کند.

برای پاک کردن داده های برنامه، موارد زیر را انجام دهید:

تنظیمات را در دستگاه مجهز به Android خود باز کنید.
روی Apps & Notifications ضربه بزنید.
روی مشاهده همه برنامه‌ها یا اطلاعات برنامه ضربه بزنید.
در میان برنامه‌ها حرکت کنید و روی خدمات Google Play ضربه بزنید.
روی Storage & cache ضربه بزنید.
روی Clear cache ضربه بزنید.

برنامه شما از کلاس مرتبط با متن AppCompat استفاده نمی کند

اگر AppCompatActivity گسترش ندهید یا اگر یک view را در کد مثال بزنید، مانند TextView ، ممکن است اتفاق بیفتد. موارد زیر را بررسی کنید:

این فعالیت AppCompatActivity را گسترش می دهد.
در صورت ایجاد نمای در کد، از زیرکلاس AppCompat صحیح استفاده کنید.

AppCompatActivity هنگام افزایش XML به طور خودکار AppCompatTextView به جای TextView افزایش می دهد، بنابراین نیازی به به روز رسانی XML خود ندارید.

تلفن آزمایشی از فونت های قابل دانلود پشتیبانی نمی کند

بررسی کنید که DefaultEmojiCompatConfig.create یک پیکربندی غیر تهی را برمی گرداند.

یک شبیه‌ساز در سطح API قبلی، خدمات Google Play را ارتقا نداده است

هنگام استفاده از شبیه‌ساز در سطح API قبلی، ممکن است لازم باشد خدمات Google Play همراه برای emoji2 را به‌روزرسانی کنید تا ارائه‌دهنده فونت را پیدا کنید. برای انجام این کار، از طریق شبیه ساز وارد فروشگاه Google Play شوید.

برای تأیید نصب نسخه سازگار، موارد زیر را انجام دهید:

دستور زیر را اجرا کنید:

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

بررسی کنید که versionCode بالاتر از 211200000 باشد.

پشتیبانی از ایموجی بدون AppCompat

اگر برنامه شما نمی‌تواند شامل AppCompat باشد، می‌تواند مستقیماً از emoji2 استفاده کند. این کار به کار بیشتری نیاز دارد، بنابراین فقط در صورتی از این روش استفاده کنید که برنامه شما نمی تواند از AppCompat استفاده کند.

برای پشتیبانی از ایموجی بدون کتابخانه AppCompat ، موارد زیر را انجام دهید:

در فایل 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 پیاده‌سازی می‌کند.
در XML و کد - هر جا که از TextView ، EditText یا Button استفاده می کنید، به جای آن از EmojiTextView ، EmojiEditText یا EmojiButton استفاده کنید.
```
activity_main.xml

<androidx.emoji2.widget.EmojiTextView ... />
<androidx.emoji2.widget.EmojiEditText ... />
<androidx.emoji2.widget.EmojiButton ... />
```
با گنجاندن ماژول emoji2 ، سیستم از ارائه‌دهنده فونت‌های قابل دانلود پیش‌فرض برای بارگذاری خودکار فونت ایموجی بلافاصله پس از راه‌اندازی برنامه استفاده می‌کند. نیازی به پیکربندی بیشتر نیست.
برای آزمایش ادغام خود، برنامه خود را بر روی دستگاهی با Android 11 یا پایین تر اجرا کنید و رشته های آزمایشی زیر را نمایش دهید. مطمئن شوید که همه کاراکترها به درستی ارائه می شوند.
- 14.0: 🫠، 🫱🏼‍🫲🏿، 🫰🏽
- 13.1: 😶‍🌫️، 🧔🏻‍♀️، 🧑🏿‍❤️‍🧑🏾
- 13.0: 🥲، 🥷🏿، 🐻‍❄️
- 12.1: 🧑🏻‍🦰، 🧑🏿‍🦯، 👩🏻‍🤝‍👩🏼
- 12.0: 🦩، 🦻🏿، 👩🏼‍🤝‍👩🏻

از EmojiCompat بدون ابزارک استفاده کنید

EmojiCompat از EmojiSpan برای ارائه تصاویر صحیح استفاده می کند. بنابراین، باید هر شی CharSequence داده شده را با اشیاء EmojiSpan به یک شی Spanned تبدیل کند. کلاس 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 به صفحه‌کلیدها اجازه می‌دهد شکلک‌هایی را که توسط برنامه‌ای که با آن در تعامل هستند پشتیبانی می‌کنند، ارائه دهند. ویرایشگرهای روش ورودی (IME) می‌توانند از متد getEmojiMatch() برای بررسی اینکه آیا نمونه‌ای از EmojiCompat قادر به ارائه ایموجی است یا خیر استفاده کنند. این روش یک CharSequence از یک ایموجی را می گیرد و اگر EmojiCompat بتواند ایموجی را شناسایی و رندر کند، true را برمی گرداند.

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

به جای تمدید ...	تمدید کنید
`TextView`	`AppCompatTextView`
`EditText`	`AppCompatEditText`
`ToggleButton`	`AppCompatToggleButton`
`Switch`	`SwitchCompat`
`Button`	`AppCompatButton`
`CheckedTextView`	`AppCompatCheckedTextView`
`RadioButton`	`AppCompatRadioButton`
`CheckBox`	`AppCompatCheckBox`
`AutoCompleteTextView`	`AppCompatAutoCompleteTextView`
`MultiAutoCompleteTextView`	`AppCompatMultiAutoCompleteTextView`

نماهای سفارشی برای برنامه ها بدون AppCompat اضافه کنید

اگر برنامه شما از AppCompat استفاده نمی‌کند، از کمک‌کننده‌های یکپارچه‌سازی view در ماژول emoji2-views-helper استفاده کنید که برای استفاده در نماهای سفارشی طراحی شده‌اند. اینها کمک هایی هستند که کتابخانه AppCompat برای اجرای پشتیبانی از ایموجی استفاده می کند.

برای پشتیبانی از نماهای سفارشی برای برنامه هایی که از AppCompat استفاده نمی کنند، مراحل زیر را تکمیل کنید.

کتابخانه emoji2-views-helper را اضافه کنید:

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

دستورالعمل‌ها را دنبال کنید تا EmojiTextViewHelper یا EmojiEditTextHelper در نماهای سفارشی برنامه‌تان قرار دهید.
ادغام خود را با راه‌اندازی برنامه خود در دستگاهی که Android 10 یا پایین‌تر دارد و نمایش رشته آزمایشی زیر آزمایش کنید. مطمئن شوید که همه کاراکترها به درستی ارائه می شوند.
- 14.0: 🫠، 🫱🏼‍🫲🏿، 🫰🏽
- 13.1: 😶‍🌫️، 🧔🏻‍♀️، 🧑🏿‍❤️‍🧑🏾
- 13.0: 🥲، 🥷🏿، 🐻‍❄️
- 12.1: 🧑🏻‍🦰، 🧑🏿‍🦯، 👩🏻‍🤝‍👩🏼
- 12.0: 🦩، 🦻🏿، 👩🏼‍🤝‍👩🏻

ویژگی های اختیاری برای مدیریت emoji2

بعد از اینکه کتابخانه emoji2 را در برنامه خود قرار دادید، می توانید ویژگی های اختیاری که در این بخش توضیح داده شده است را اضافه کنید.

emoji2 را برای استفاده از فونت متفاوت یا ارائه دهنده فونت قابل دانلود پیکربندی کنید

برای پیکربندی emoji2 برای استفاده از فونت دیگری یا ارائه دهنده فونت قابل دانلود، موارد زیر را انجام دهید:

با افزودن موارد زیر به مانیفست خود 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>

یکی از کارهای زیر را انجام دهید:
- با فراخوانی 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 از این رویه پیروی می کند و بارگذاری فونت emoji را تا پس از از سرگیری اولین صفحه به تعویق می اندازد.

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

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 .

پشتیبانی از فونت های همراه با emoji2

می‌توانید از مصنوع emoji2-bundled برای بسته‌بندی یک فونت emoji در برنامه خود استفاده کنید. با این حال، از آنجایی که فونت NotoColorEmoji بیش از 10 مگابایت است، ما قویاً توصیه می کنیم برنامه شما در صورت امکان از فونت های قابل دانلود استفاده کند. مصنوع emoji2-bundled برای برنامه‌هایی در دستگاه‌هایی که فونت‌های قابل دانلود را پشتیبانی نمی‌کنند در نظر گرفته شده است.

برای استفاده از مصنوع emoji2-bundled ، موارد زیر را انجام دهید:

شامل مصنوعات emoji2-bundled و emoji2 :
```
implementation "androidx.emoji2:emoji2:$emojiVersion"
implementation "androidx.emoji2:emoji2-bundled:$emojiVersion"
```
احتیاط: گنجاندن مصنوع emoji2-bundled EmojiCompatInitializer غیرفعال می‌کند، بنابراین برنامه شما باید EmojiCompat.init() فراخوانی کند.
emoji2 برای استفاده از پیکربندی همراه پیکربندی کنید:
کاتلین
EmojiCompat.init(BundledEmojiCompatConfig(context))
جاوا
EmojiCompat.init(new BundledEmojiCompatConfig(context));
ادغام را با دنبال کردن مراحل قبلی برای گنجاندن emojicompat با یا بدون AppCompat آزمایش کنید. مطمئن شوید که رشته تست به درستی نمایش داده می شود.
- 14.0: 🫠، 🫱🏼‍🫲🏿، 🫰🏽
- 13.1: 😶‍🌫️، 🧔🏻‍♀️، 🧑🏿‍❤️‍🧑🏾
- 13.0: 🥲، 🥷🏿، 🐻‍❄️
- 12.1: 🧑🏻‍🦰، 🧑🏿‍🦯، 👩🏻‍🤝‍👩🏼
- 12.0: 🦩، 🦻🏿، 👩🏼‍🤝‍👩🏻

تاثیر پیکربندی خودکار EmojiCompat

سیستم پیکربندی پیش‌فرض را با استفاده از کتابخانه راه‌اندازی، EmojiCompatInitializer و DefaultEmojiCompatConfig اعمال می‌کند.

پس از از سرگیری اولین فعالیت در برنامه شما، راه اندازی کننده بارگذاری فونت ایموجی را برنامه ریزی می کند. این تأخیر کوتاه به برنامه شما امکان می‌دهد محتوای اولیه خود را بدون هیچ تأخیر احتمالی به دلیل بارگیری فونت در یک رشته پس‌زمینه نمایش دهد.

DefaultEmojiCompatConfig به دنبال ارائه‌دهنده فونت قابل دانلود نصب‌شده در سیستم می‌گردد که رابط EmojiCompat ، مانند سرویس‌های Google Play را پیاده‌سازی می‌کند. در دستگاه‌هایی که توسط سرویس‌های Google Play ارائه می‌شوند، این فونت را با استفاده از خدمات Google Play بارگیری می‌کند.

آغازگر یک رشته پس‌زمینه برای بارگیری فونت emoji ایجاد می‌کند، و دانلود فونت می‌تواند تا 10 ثانیه طول بکشد تا زمان پایان برسد. پس از بارگیری فونت، تقریباً 150 میلی ثانیه در یک رشته پس‌زمینه طول می‌کشد تا EmojiCompat مقداردهی اولیه شود.

شروع اولیه EmojiCompat را به تعویق بیندازید، حتی اگر EmojiCompatInitializer غیرفعال کنید. اگر EmojiCompat به صورت دستی پیکربندی می‌کنید ، پس از نمایش اولین صفحه برنامه شما EmojiCompat.load() را فراخوانی کنید تا از مشاجره پس‌زمینه با بارگیری صفحه اول جلوگیری کنید.

پس از بارگذاری، EmojiCompat از حدود 300 کیلوبایت رم برای نگهداری فراداده های ایموجی استفاده می کند.