منابع فایل‌های اضافی و محتوای ثابتی هستند که کد شما استفاده می‌کند، مانند نگاشت‌های بیتی، رشته‌های میانای کاربر، دستورالعمل‌های پویانمایی، و غیره.
همیشه منابع برنامه مانند تصاویر و رشته‌ها را از کد خود برون‌سپاری کنید تا بتوانید آن‌ها را به‌طور مستقل نگهداری کنید. همچنین، منابع جایگزین برای پیکربندی‌های خاص دستگاه را با گروه‌بندی آن‌ها در فهرست‌های راهنمای منبع با نام‌های خاص ارائه دهید. در زمان اجرا، Android از منبع مناسب براساس پیکربندی فعلی استفاده می‌کند. برای مثال، ممکن است بخواهید رشته‌های مختلفی را بسته به تنظیمات زبان ارائه دهید.
وقتی منابع برنامه‌تان را خارجی کردید، می‌توانید بااستفاده از شناسه‌های منبعی که در کلاس R پروژه‌تان تولید شده است به آن‌ها دسترسی پیدا کنید.
این سند به شما نشان می‌دهد که چگونه منابع را در پروژه Android خود گروه‌بندی کنید. همچنین به شما نشان می‌دهد که چگونه
منابع جایگزین را برای پیکربندی‌های خاص دستگاه ارائه دهید و سپس ازطریق
کد برنامه یا سایر فایل‌های XML به آن‌ها دسترسی پیدا کنید.
انواع منبع گروه
هر نوع منبع را در زیرفهرست راهنمای خاصی از فهرست راهنمای
res/ پروژه‌تان قرار دهید. برای مثال، در اینجا سلسله‌مراتب فایل برای یک پروژه ساده آورده شده است:
MyProject/
src/
MyActivity.kt
res/
drawable/
graphic.png
mipmap/
icon.png
values/
strings.xml
فهرست راهنمای res/ شامل همه منابع در
زیرفهرست‌های راهنمای آن است: یک منبع تصویر، یک فهرست راهنمای mipmap/ برای نمادهای
راه‌انداز، و یک فایل منبع رشته. نام‌های فهرست راهنمای منبع مهم هستند و در جدول ۱ شرح داده شده‌اند.
توجه: برای اطلاعات بیشتر درباره استفاده از پوشه‌های mipmap، به قرار دادن نمادهای برنامه در دایرکتوری‌های mipmap مراجعه کنید.
جدول ۱. فهرست‌های راهنمای منبع
در فهرست راهنمای پروژه res/ پشتیبانی می‌شود.
| فهرست راهنما | نوع منبع |
|---|---|
drawable/ |
فایل‌های Bitmap (PNG،
برای اطلاعات بیشتر، به منابع ترسیم‌شدنی مراجعه کنید. |
mipmap/ |
فایل‌های قابل‌رسم برای تراکم‌های مختلف نماد راه‌انداز. برای اطلاعات بیشتر درباره مدیریت
نمادهای راه‌انداز با پوشه‌های mipmap/، به
قرار دادن نمادهای برنامه در
دایرکتوری‌های mipmap مراجعه کنید. |
raw/ |
فایل‌های دلخواه برای ذخیره کردن در قالب خام. برای باز کردن این منابع با
بااین‌حال، اگر به نام‌های اصلی فایل و سلسله‌مراتب فایل نیاز دارید،
ذخیره منابع در فهرست راهنمای |
values/ |
فایل‌های XML که حاوی مقادیر ساده مانند رشته‌ها، اعداد صحیح، و رنگ‌ها هستند. درحالی‌که فایل‌های منبع XML در زیرفهرست‌های راهنمای چون هر منبع با عنصر XML خودش تعریف می‌شود، می‌توانید فایل را هرطور که می‌خواهید نام‌گذاری کنید و انواع مختلف منابع را در یک فایل قرار دهید. بااین‌حال، برای شفافیت، ممکن است بخواهید انواع منبع منحصربه‌فرد را در فایل‌های مختلف قرار دهید. برای مثال، در اینجا چند قرارداد نام فایل برای منابعی که می‌توانید در این دایرکتوری ایجاد کنید آورده شده است:
برای اطلاعات بیشتر، منابع رشته، منبع سبک، و انواع منابع بیشتر را ببینید. |
xml/ |
فایل‌های XML دلخواه که می‌توانند در زمان اجرا با فراخوانی Resources.getXML خوانده شوند. فایل‌های پیکربندی XML مختلف
باید در اینجا ذخیره شود.
|
font/ |
فایل‌های قلم با پسوندهایی مانند TTF، OTF،
یا TTC، یا فایل‌های XML که
شامل عنصر <font-family> هستند. برای اطلاعات بیشتر درباره
قلم‌ها به‌عنوان منابع، به
افزودن قلم به‌عنوان منبع XML مراجعه کنید.
|
احتیاط: هرگز فایل‌های منبع را مستقیماً در فهرست راهنمای
res/ ذخیره نکنید. این کار باعث خطای کامپایلر می‌شود.
منابعی که در زیرفهرست‌های راهنمای تعریف‌شده در جدول ۱ ذخیره می‌کنید، منابع پیش‌فرض شما هستند. یعنی این منابع طراحی و محتوای پیش‌فرض را برای برنامه‌تان تعریف می‌کنند. بااین‌حال، انواع مختلف دستگاه‌های مجهز به Android ممکن است به انواع مختلفی از منابع نیاز داشته باشند.
برای مثال، می‌توانید منابع رشته‌ای متفاوتی ارائه دهید که نوشتار را در میانای کاربر براساس تنظیمات زبان دستگاه ترجمه کند.
توجه: در Compose، رابط‌های کاربری، پویانمایی‌ها، و رنگ‌های مبتنی بر وضعیت در Kotlin اعلام می‌شوند، بنابراین
دایرکتوری‌های layout/، menu/، anim/، animator/،
و color/ برای برنامه‌های مدرن منسوخ شده‌اند. برای اطلاعات بیشتر، به پویانمایی‌ها در Compose و آناتومی طرح زمینه در Compose مراجعه کنید.
ارائه منابع جایگزین
بیشتر برنامه‌ها منابع جایگزینی برای پشتیبانی از پیکربندی‌های خاص دستگاه ارائه می‌دهند. برای مثال، منابع ترسیم‌شدنی جایگزین برای تراکم‌های مختلف صفحه‌نمایش و منابع رشته‌ای جایگزین برای زبان‌های مختلف اضافه کنید. در زمان اجرا، Android پیکربندی فعلی دستگاه را شناسایی می‌کند و منابع مناسب را برای برنامه‌تان بار می‌کند.
برای مشخص کردن جایگزین‌های ویژه پیکربندی برای مجموعه‌ای از منابع، کارهای زیر را انجام دهید:
- دایرکتوری جدیدی در
res/با نامی به شکل<resources_name>-<qualifier>ایجاد کنید.<resources_name>نام دایرکتوری منابع پیش‌فرض مربوطه است (در جدول ۱ تعریف شده است).<qualifier>نامی است که پیکربندی خاصی را مشخص می‌کند که این منابع برای آن استفاده می‌شوند (در جدول ۲ تعریف شده است).
می‌توانید بیش‌از یک
<qualifier>اضافه کنید. هرکدام را با خط تیره جدا کنید.احتیاط: هنگام افزودن چند توصیف‌کننده، باید آن‌ها را به همان ترتیبی که در جدول ۲ فهرست شده‌اند قرار دهید. اگر ترتیب توصیف‌کننده‌ها نادرست باشد، منابع نادیده گرفته می‌شوند.
- منابع جایگزین مناسب را در این دایرکتوری جدید ذخیره کنید. نام فایل‌های منبع باید دقیقاً با نام فایل‌های منبع پیش‌فرض یکسان باشد.
برای مثال، در اینجا چند منبع پیش‌فرض و جایگزین آورده شده است:
res/
drawable/
icon.png
background.png
drawable-hdpi/
icon.png
background.png
توصیف‌کننده hdpi نشان می‌دهد که منابع موجود در آن دایرکتوری برای دستگاه‌های دارای
صفحه تراکم بالا است. تصاویر موجود در این دایرکتوری‌های قابل‌رسم برای تراکم‌های صفحه‌نمایش خاصی اندازه شده‌اند، اما نام فایل‌ها دقیقاً یکسان است. به‌این‌ترتیب، شناسه منبعی که برای ارجاع به تصویر icon.png یا
background.png استفاده می‌کنید همیشه یکسان است. Android با مقایسه اطلاعات پیکربندی دستگاه با واجدشرایط‌ها در نام فهرست راهنمای منبع، نسخه‌ای از هر منبع را که با دستگاه فعلی بیشترین مطابقت را دارد انتخاب می‌کند.
احتیاط: هنگام تعریف منبع جایگزین، مطمئن شوید که
منبع را در پیکربندی پیش‌فرض نیز تعریف کنید. درغیراین‌صورت، ممکن است برنامه‌تان هنگام تغییر پیکربندی دستگاه با استثناهای زمان اجرا مواجه شود. برای مثال، اگر رشته‌ای را فقط به
values-en و نه values اضافه کنید، ممکن است وقتی کاربر زبان پیش‌فرض سیستم را تغییر می‌دهد، برنامه‌تان با استثنای
Resource Not Found مواجه شود.
جدول ۲ توصیف‌گرهای پیکربندی را به‌ترتیب اولویت فهرست می‌کند. می‌توانید با جدا کردن هر شناسه با خط تیره، چندین شناسه به یک نام دایرکتوری اضافه کنید. اگر از چند واجدشرایط برای فهرست راهنمای منبع استفاده می‌کنید، باید آن‌ها را به‌ترتیبی که در جدول فهرست شده‌اند به نام فهرست راهنما اضافه کنید.
جدول ۲. نام‌های توصیف‌گر پیکربندی.
| پیکربندی | مقادیر توصیف‌گر | شرح |
|---|---|---|
| کد کشور موبایل و کد شبکه تلفن همراه | مثال‌ها:mcc310mcc208-mnc00
|
کد کشور تلفن همراه (MCC)، به‌طور اختیاری به‌دنبال کد شبکه تلفن همراه (MNC)
از سیم‌کارت در دستگاه. برای مثال، اگر دستگاه از اتصال رادیویی استفاده می‌کند (یعنی تلفن GSM است)، مقادیر MCC و MNC از سیم‌کارت گرفته می‌شود. همچنین می‌توانید از MCC به‌تنهایی استفاده کنید، برای مثال، برای گنجاندن منابع قانونی مختص کشور در برنامه‌تان. اگر لازم است فقط براساس زبان مشخص کنید، به‌جای آن از شناسه زبان، نویسه (اختیاری)، و منطقه (اختیاری) استفاده کنید. اگر از MCC و توصیف‌کننده MNC استفاده می‌کنید، این کار را با دقت انجام دهید و آزمایش کنید که طبق انتظار کار کند. همچنین فیلدهای پیکربندی |
| زبان، نویسه (اختیاری)، و منطقه (اختیاری) | مثال‌ها:enfren-rUSfr-rFRfr-rCAb+enb+en+USb+es+419b+zh+Hantb+sr+Latn+RS |
زبان با کد زبان دو حرفی ISO 639-1 تعریف می‌شود و به‌طور اختیاری با کد منطقه دو حرفی ISO 3166-1-alpha-2 (با پیشوند کدها به حروف بزرگ و کوچک حساس نیستند. پیشوند Android 7.0 (سطح میانای برنامه‌سازی کاربردی ۲۴) پشتیبانی از برچسب‌های زبان BCP 47 را معرفی کرد که می‌توانید از آن برای واجدشرایط کردن منابع مختص زبان و منطقه استفاده کنید. برچسب زبان از توالی یک یا چند برچسب فرعی تشکیل شده است که هرکدام از آن‌ها محدوده زبان شناسایی‌شده توسط برچسب کلی را اصلاح یا محدود می‌کند. برای اطلاعات بیشتر درباره برچسب‌های زبان، به برچسب‌های شناسایی زبان مراجعه کنید. برای استفاده از برچسب زبان BCP 47، اگر کاربران زبانشان را در تنظیمات سیستم تغییر دهند، برچسب زبان می‌تواند درطول عمر برنامه‌تان تغییر کند. برای اطلاعات درباره اینکه این موضوع چگونه می‌تواند بر برنامه‌تان درطول زمان اجرا تأثیر بگذارد، به مدیریت تغییرات پیکربندی مراجعه کنید. برای راهنمای کامل بومی‌سازی برنامه‌تان برای زبان‌های دیگر، بومی‌سازی برنامه را ببینید. همچنین روش |
| جنسیت دستوری | masculinefeminineneuter |
جنسیت دستوری کاربر. برای زبان‌هایی که جنسیت دستوری دارند استفاده می‌شود. برای مثال، اگر لازم است منابع متفاوتی برای کاربران فرانسوی‌زبان ارائه دهید، می‌توانید از دایرکتوری‌هایی مانند موارد زیر استفاده کنید: به شخصی‌سازی کردن واسط کاربر برنامه با جنسیت دستوری مراجعه کنید. همچنین روش پیکربندی در سطح ای‌پی‌آی ۳۴ اضافه شده است. |
| طیف رنگی گسترده |
widecgnowidecg
|
در سطح ۲۶ میانای برنامه‌سازی کاربردی اضافه شده است. همچنین روش پیکربندی |
| دامنه پویای بالا (HDR) |
highdrlowdr
|
در سطح ۲۶ میانای برنامه‌سازی کاربردی اضافه شده است. همچنین روش پیکربندی |
| حالت واسط کاربر |
cardesktelevisionappliancewatchvrheadset
|
در سطح میانای برنامه‌سازی کاربردی ۸ اضافه شد؛ تلویزیون در میانای برنامه‌سازی کاربردی ۱۳ اضافه شد؛ لوازم خانگی در میانای برنامه‌سازی کاربردی ۱۶ اضافه شد؛ ساعت در میانای برنامه‌سازی کاربردی ۲۰ اضافه شد؛ هدست واقعیت مجازی در میانای برنامه‌سازی کاربردی ۲۶ اضافه شد. برای کسب اطلاعات درباره نحوه پاسخ‌دهی برنامه شما هنگام قرار دادن دستگاه در پایه یا برداشتن آن از پایه، تعیین و نظارت بر وضعیت و نوع پایه را بخوانید. این وضعیت ممکن است درطول عمر برنامه‌تان تغییر کند، مثلاً اگر کاربر دستگاه را در
پایه قرار دهد. می‌توانید برخی‌از این حالت‌ها را بااستفاده از
|
| حالت شب |
nightnotnight
|
در سطح میانای برنامه‌سازی کاربردی ۸ اضافه شده است. اگر حالت شب در حالت خودکار (پیش‌فرض) باقی بماند، این موضوع می‌تواند درطول عمر برنامه‌تان تغییر کند،
در این صورت حالت براساس زمان روز تغییر می‌کند. بااستفاده از |
| تراکم پیکسل صفحه‌نمایش (dpi) |
ldpimdpihdpixhdpixxhdpixxxhdpinodpitvdpianydpinnndpi
|
نسبت مقیاس‌بندی بین شش چگالی اصلی (با نادیده گرفتن چگالی tvdpi) برابر با ۳:۴:۶:۸:۱۲:۱۶ است. بنابراین، بیت‌مپ ۹×۹ در ldpi برابر با ۱۲×۱۲ در mdpi، ۱۸×۱۸ در hdpi، ۲۴×۲۴ در xhdpi، و غیره است. توجه: استفاده از توصیف‌گر تراکم به این معنی نیست که منابع فقط برای صفحه‌نمایش‌های دارای آن تراکم هستند. اگر منابع جایگزین را با اصلاح‌کننده‌هایی که با پیکربندی فعلی دستگاه مطابقت بهتری دارند ارائه نکنید، سیستم از هر منبعی که بهترین مطابقت را داشته باشد استفاده می‌کند. برای اطلاعات بیشتر درباره نحوه مدیریت تراکم‌های مختلف صفحه‌نمایش و نحوه مقیاس‌بندی نقشه‌های بیتی توسط Android برای تطابق با تراکم فعلی، به نمای کلی سازگاری صفحه‌نمایش مراجعه کنید. |
| نوع صفحه لمسی |
notouchfinger
|
همچنین فیلد پیکربندی |
| دردسترس بودن صفحه‌کلید |
keysexposedkeyshiddenkeyssoft
|
اگر منابع این مورد می‌تواند درطول عمر برنامه‌تان تغییر کند، مثلاً اگر کاربر صفحه‌کلید سخت‌افزاری را باز کند. برای کسب اطلاعات درباره اینکه این موضوع چگونه بر برنامه‌تان درطول زمان اجرا تأثیر می‌گذارد، به مدیریت تغییرات پیکربندی مراجعه کنید. همچنین فیلدهای پیکربندی |
| روش اصلی ورودی نوشتار |
nokeysqwerty12key
|
همچنین فیلد پیکربندی |
| دردسترس بودن کلید پیمایش |
navexposednavhidden
|
این مورد می‌تواند درطول عمر برنامه‌تان تغییر کند اگر کاربر کلیدهای پیمایش را آشکار کند. برای کسب اطلاعات درباره اینکه این موضوع چگونه بر برنامه‌تان درطول زمان اجرا تأثیر می‌گذارد، به مدیریت تغییرات پیکربندی مراجعه کنید. همچنین فیلد پیکربندی |
| روش پیمایش غیرلمسی اصلی |
nonavdpadtrackballwheel
|
همچنین فیلد پیکربندی |
| نسخه پلاتفرم (سطح API) | مثال‌ها:v3v4v7و غیره. |
سطح API پشتیبانی‌شده توسط دستگاه. برای مثال، |
توجه: همه نسخه‌های Android از همه واجدین شرایط پشتیبانی نمی‌کنند. استفاده از یک شناسه جدید به‌طور ضمنی شناسه نسخه پلاتفرم را اضافه می‌کند تا دستگاه‌های قدیمی‌تر بتوانند آن را نادیده بگیرند. برای جلوگیری از هرگونه مشکل، همیشه مجموعه‌ای از منابع پیش‌فرض (مجموعه‌ای از منابع بدون توصیف‌کننده) را اضافه کنید. برای اطلاعات بیشتر، به بخش مربوط به ارائه بهترین سازگاری دستگاه با منابع مراجعه کنید.
در برنامه‌های Compose، توصیف‌گرهای پیکربندی مربوط به چیدمان و ابعاد لازم نیستند. اگرچه این موارد هنوز وجود دارند، از جدول ۲ مستثنی شده‌اند. این واجدین شرایط عبارتند از: جهت چیدمان، کوچک‌ترین عرض، عرض دردسترس، ارتفاع دردسترس، اندازه صفحه‌نمایش، نسبت ابعاد صفحه‌نمایش، صفحه‌نمایش گرد، و جهت صفحه‌نمایش. برای مشاهده جدول کامل توصیف‌گرهای پیکربندی به‌ترتیب اولویت، به نمای کلی منابع برنامه (نماها) مراجعه کنید.
قوانین نام واجدشرایط
در اینجا چند قانون درباره استفاده از نام‌های توصیف‌گر پیکربندی آورده شده است:
- می‌توانید چند توصیف‌گر را برای یک مجموعه منابع مشخص کنید و آن‌ها را با خط تیره از هم جدا کنید. برای
مثال،
drawable-en-rUS-nightبرای دستگاه‌های انگلیسی (ایالات متحده) در حالت شب اعمال می‌شود. - توصیف‌کننده‌ها باید به ترتیبی که در جدول ۲ فهرست شده است باشند.
- اشتباه:
drawable-hdpi-night/ - درست:
drawable-night-hdpi/
- اشتباه:
- فهرست‌های راهنمای منبع جایگزین نمی‌توانند تودرتو باشند. برای مثال، نمی‌توانید
res/drawable/drawable-en/داشته باشید. - مقادیر به حروف بزرگ و کوچک حساس نیستند. کامپایلر منبع نام دایرکتوری‌ها را قبل‌از پردازش به حروف کوچک تبدیل می‌کند تا از بروز مشکل در سیستم‌های فایل غیرحساس به حروف بزرگ و کوچک جلوگیری شود. هرگونه حروف بزرگ در نام‌ها فقط برای بهبود خوانایی است.
- فقط یک مقدار برای هر نوع توصیف‌کننده پشتیبانی می‌شود. برای مثال، اگر می‌خواهید از
فایل‌های قابل‌ترسیم یکسانی برای اسپانیا و فرانسه استفاده کنید، نمی‌توانید دایرکتوری‌ای با نام
drawable-es-fr/داشته باشید. به‌جای آن، به دو فهرست راهنمای منبع نیاز دارید، مثلdrawable-es/وdrawable-fr/، که حاوی فایل‌های مناسب باشند.
پس‌از ذخیره کردن منابع جایگزین در دایرکتوری‌هایی که با این شناساننده‌ها نام‌گذاری شده‌اند، Android به‌طور خودکار منابع را براساس پیکربندی فعلی دستگاه در برنامه‌تان اعمال می‌کند. هر بار که منبعی درخواست می‌شود، Android فهرست‌های راهنمای منبع جایگزین را که حاوی فایل منبع درخواستی هستند بررسی می‌کند، سپس منبعی را که بهترین مطابقت را دارد پیدا می‌کند.
اگر هیچ منبع جایگزینی وجود نداشته باشد که با پیکربندی دستگاه خاصی مطابقت داشته باشد، Android از منابع پیش‌فرض مربوطه استفاده می‌کند—مجموعه منابع برای نوع منبع خاصی که شامل توصیف‌گر پیکربندی نیست.
ساختن منابع دگرنام
وقتی منبعی دارید که می‌خواهید برای بیش‌از یک پیکربندی دستگاه استفاده کنید اما نمی‌خواهید آن را به‌عنوان منبع پیش‌فرض ارائه دهید، لازم نیست همان منبع را در بیش‌از یک فهرست راهنمای منبع جایگزین قرار دهید. درعوض، می‌توانید منبع جایگزینی ایجاد کنید که به‌عنوان نام مستعار برای منبع ذخیره‌شده در فهرست راهنمای منبع پیش‌فرض شما عمل می‌کند.
ترسیم‌شدنی‌ها
برای مثال، فرض کنید نماد برنامه‌ای (icon.png) دارید و به نسخه منحصربه‌فردی از آن برای مناطق زبانی مختلف نیاز دارید. بااین‌حال، دو منطقه زبانی انگلیسی-کانادایی و فرانسوی-کانادایی باید
از یک نسخه استفاده کنند. لازم نیست تصویر یکسانی را
در فهرست راهنمای منبع برای هر دو زبان انگلیسی-کانادایی و فرانسوی-کانادایی کپی کنید.
درعوض، می‌توانید تصویری را که برای هر دو استفاده می‌شود با هر نامی غیراز
icon.png، مثلاً icon_ca.png، ذخیره کنید و آن را
در دایرکتوری پیش‌فرض res/drawable/ قرار دهید. سپس فایل icon.xml را در
res/drawable-en-rCA/ و res/drawable-fr-rCA/ ایجاد کنید که بااستفاده از عنصر <bitmap> به منبع icon_ca.png
ارجاع می‌دهد.
<?xml version="1.0" encoding="utf-8"?> <bitmap xmlns:android="http://schemas.android.com/apk/res/android" android:src="@drawable/icon_ca" />
این کار به شما امکان می‌دهد فقط یک نسخه از فایل PNG و دو فایل XML کوچک را که به آن اشاره می‌کنند ذخیره کنید.
سپس می‌توانید از painterResource(R.drawable.icon) استفاده کنید و سیستم پس‌از شناسایی منطقه زبانی،
فایل مناسب را انتخاب خواهد کرد.
رشته‌ها و مقادیر ساده دیگر
برای ایجاد نام مستعار برای رشته موجود، از شناسه منبع رشته موردنظر به‌عنوان مقدار رشته جدید استفاده کنید:
<?xml version="1.0" encoding="utf-8"?> <resources> <string name="hello">Hello</string> <string name="hi">@string/hello</string> </resources>
منبع R.string.hi اکنون نام مستعاری برای R.string.hello است.
مقادیر ساده دیگر، مانند رنگ‌ها، به همین روش کار می‌کنند:
<?xml version="1.0" encoding="utf-8"?> <resources> <color name="red">#f00</color> <color name="highlight">@color/red</color> </resources>
دسترسی به منابع برنامه
وقتی منبعی را در برنامه‌تان ارائه کردید، می‌توانید آن را با ارجاع به شناسه منبع آن اعمال کنید. همه شناسه‌های منبع در کلاس R پروژه شما تعریف شده‌اند که
ابزار aapt به‌طور خودکار تولید می‌کند.
وقتی برنامه‌تان کامپایل می‌شود، aapt کلاس R را تولید می‌کند که حاوی شناسه‌های منبع برای همه منابع موجود در فهرست راهنمای res/ شما است. برای هر نوع منبع،
یک زیرکلاس R وجود دارد، مانند
R.drawable برای همه منابع ترسیم‌شدنی. و برای هر منبع از آن نوع، یک عدد صحیح ثابت وجود دارد، برای مثال، R.drawable.icon. این عدد صحیح شناسه منبعی است که می‌توانید برای بازیابی منبعتان استفاده کنید.
اگرچه کلاس R جایی است که شناسه‌های منبع مشخص می‌شوند، اما برای پیدا کردن شناسه منبع نیازی به نگاه کردن به آنجا ندارید. شناسه منبع همیشه از موارد زیر تشکیل شده است:
- نوع منبع: هر منبع در یک «نوع» گروه‌بندی می‌شود، مانند
stringیاdrawable. - نام منبع که همان نام فایل بدون پسوند است.
دسترسی به منابع در Compose
Jetpack Compose توابع داخلی و آگاه از ترکیب‌پذیری را برای دسترسی ایمن به منابع ارائه می‌دهد.
- رشته‌ها:
stringResource(id = R.string.hello)
- Drawables:
painterResource(id = R.drawable.my_icon)
دسترسی به منابع در کد غیرمیانای کاربر
اگر لازم است به منابعی خارج از سلسله‌مراتب واسط کاربرتان دسترسی پیدا کنید (مثلاً در
ViewModel، Repository، یا Service سیستم)، می‌توانید
آن‌ها را بااستفاده از Context حل کنید.
// Retrieve a localized string resource val greeting = context.getString(R.string.hello_world)
همچنین می‌توانید منابع فردی را بااستفاده از روش‌های موجود در Resources بازیابی کنید، که می‌توانید نمونه‌ای از آن را با getResources دریافت کنید.
نحو
نحو ارجاع به منبع در کد در اینجا آمده است:
[<package_name>.]R.<resource_type>.<resource_name>
<package_name>نام بسته‌ای است که منبع در آن قرار دارد (هنگام ارجاع به منابع از بسته خودتان لازم نیست).<resource_type>زیرکلاسRبرای نوع منبع است.<resource_name>یا نام فایل منبع بدون پسوند است یا مقدار مشخصهandroid:nameدر عنصر XML، برای مقادیر ساده.
برای اطلاعات بیشتر درباره هر نوع منبع و نحوه ارجاع به آن‌ها، منابع در Compose را ببینید.
دسترسی به فایل‌های اصلی
اگرچه این اتفاق رایج نیست، اما ممکن است لازم باشد به فایل‌ها و دایرکتوری‌های اصلی خود دسترسی پیدا کنید. اگر این کار را انجام دهید،
ذخیره کردن فایل‌هایتان در res/ برای شما کار نخواهد کرد، زیرا تنها راه خواندن منبع از
res/ با شناسه منبع است. درعوض، می‌توانید منابعتان را در
دایرکتوری assets/ ذخیره کنید.
به فایل‌های ذخیره‌شده در فهرست راهنمای assets/ شناسه منبع داده نمی‌شود، بنابراین نمی‌توانید ازطریق کلاس R یا از منابع XML به آن‌ها ارجاع دهید. درعوض، می‌توانید
فایل‌ها را در فهرست راهنمای assets/ مانند یک سیستم فایل معمولی پُرسمان کنید و داده‌های خام را بااستفاده از
AssetManager بخوانید.
بااین‌حال، اگر تنها چیزی که نیاز دارید توانایی خواندن داده‌های خام (مانند فایل ویدیویی یا صوتی) است،
فایل را در دایرکتوری res/raw/ ذخیره کنید و بااستفاده از openRawResource،
جاری‌سازی بایت‌ها را بخوانید.
دسترسی به منابع پلاتفرم
Android حاوی تعدادی منابع استاندارد است، مانند سبک‌ها و زمینه‌های سیستم. برای دسترسی به
این موارد، مرجع منبع خود را با کلاس بسته android واجدشرایط کنید. برای مثال:
painterResource(android.R.drawable.ic_menu_info_details).
ارائه بهترین سازگاری دستگاه با منابع
برای اینکه برنامه‌تان از پیکربندی‌های چند دستگاه پشتیبانی کند، بسیار مهم است که همیشه منابع پیش‌فرض را برای هر نوع منبعی که برنامه‌تان استفاده می‌کند ارائه دهید.
برای مثال، اگر برنامه‌تان از چند زبان پشتیبانی می‌کند، همیشه یک دایرکتوری values/ (که رشته‌هایتان در آن ذخیره می‌شود) بدون توصیف‌کننده زبان و منطقه اضافه کنید. اگر درعوض همه فایل‌های رشته‌ای را در دایرکتوری‌هایی قرار دهید که دارای شناسه زبان و منطقه هستند، وقتی برنامه در دستگاهی اجرا شود که روی زبانی تنظیم شده است که رشته‌های شما از آن پشتیبانی نمی‌کنند، برنامه ازکار می‌افتد.
تا زمانی که منابع پیش‌فرض
values/ را ارائه دهید، برنامه‌تان به‌درستی اجرا می‌شود، حتی اگر کاربر
زبانی را که برنامه ارائه می‌دهد متوجه نشود. بهتر از خراب شدن است.
ارائه منابع پیش‌فرض مهم است، نه فقط به این دلیل که ممکن است برنامه‌تان در پیکربندی‌ای اجرا شود که پیش‌بینی نکرده‌اید، بلکه به این دلیل که نسخه‌های جدید Android گاهی توصیف‌گرهای پیکربندی‌ای اضافه می‌کنند که نسخه‌های پایین‌تر از آن‌ها پشتیبانی نمی‌کنند. اگر از توصیف‌گر منبع جدیدی استفاده می‌کنید، اما سازگاری کد را با نسخه‌های پایین‌تر Android حفظ می‌کنید، وقتی نسخه پایین‌تر Android برنامه شما را اجرا می‌کند، اگر منابع پیش‌فرض را ارائه نکنید، برنامه ازکار می‌افتد، زیرا نمی‌تواند از منابعی که با توصیف‌گر جدید نام‌گذاری شده‌اند استفاده کند.
برای مثال، اگر minSdkVersion شما روی ۴ تنظیم شده باشد و همه منابع ترسیم‌شدنی‌تان را بااستفاده از حالت شب (night یا notnight که در سطح ۸ میانای برنامه‌سازی کاربردی اضافه شده‌اند) واجدشرایط کنید، دستگاهی با سطح ۴ میانای برنامه‌سازی کاربردی نمی‌تواند به منابع ترسیم‌شدنی شما دسترسی پیدا کند و ازکار می‌افتد. در این
مورد، احتمالاً می‌خواهید notnight منابع پیش‌فرض شما باشد، بنابراین آن
توصیف‌کننده را کنار بگذارید و منابع ترسیم‌شدنی خود را در drawable/ یا drawable-night/ قرار دهید.
به‌طور خلاصه، برای ارائه بهترین سازگاری دستگاه، همیشه منابع پیش‌فرض را برای منابعی که برنامه‌تان برای عملکرد صحیح نیاز دارد ارائه دهید. سپس بااستفاده از توصیف‌گرهای پیکربندی، منابع جایگزین برای پیکربندی‌های خاص دستگاه ایجاد کنید.
یک استثنا برای این قانون وجود دارد: اگر minSdkVersion برنامه‌تان ۴ یا
بیشتر باشد، وقتی منابع ترسیم‌شدنی جایگزین را با توصیف‌گر تراکم صفحه ارائه می‌دهید، به منابع ترسیم‌شدنی پیش‌فرض نیاز ندارید. حتی بدون منابع ترسیم‌شدنی پیش‌فرض، Android می‌تواند بهترین تطابق را در میان تراکم‌های صفحه‌نمایش جایگزین پیدا کند و نقشه‌های بیتی را درصورت لزوم مقیاس‌بندی کند. بااین‌حال، برای داشتن بهترین تجربه در انواع دستگاه‌ها،
برای هر سه نوع تراکم، drawable جایگزین ارائه دهید.
نحوه پیدا کردن بهترین منبع منطبق توسط Android
وقتی منبعی را درخواست می‌کنید که برای آن جایگزین‌هایی ارائه می‌دهید، Android انتخاب می‌کند که کدام منبع جایگزین در زمان اجرا استفاده شود، بسته به پیکربندی فعلی دستگاه. برای نشان دادن نحوه انتخاب منبع جایگزین توسط Android، فرض کنید دایرکتوری‌های قابل‌ترسیم زیر هرکدام حاوی نسخه‌های متفاوتی از تصاویر یکسان هستند:
drawable/ drawable-en/ drawable-fr-rCA/ drawable-en-night/ drawable-en-notouch-12key/ drawable-night-ldpi/ drawable-night-notouch-12key/
و فرض کنید پیکربندی دستگاه به‌صورت زیر است:
منطقه زبانی = en-GB
حالت شب = night
تراکم پیکسل صفحه‌نمایش = hdpi
نوع نمایشگر لمسی = notouch
روش اصلی ورودی نوشتار = 12key
Android با مقایسه پیکربندی دستگاه با منابع جایگزین دردسترس،
ترسیم‌شدنی‌ها را از drawable-en-night انتخاب می‌کند.
سیستم با منطق زیر تصمیم می‌گیرد که از کدام منابع استفاده کند:
شکل ۲. روندنمای نحوه پیدا کردن بهترین منبع منطبق توسط Android.
- فایل‌های منبعی را که با پیکربندی دستگاه مغایرت دارند حذف کنید.
فهرست راهنمای
drawable-fr-rCA/حذف شده است، زیرا با منطقه زبانیen-GBمغایرت دارد.drawable/ drawable-en/
drawable-fr-rCA/drawable-en-night/ drawable-en-notouch-12key/ drawable-night-ldpi/ drawable-night-notouch-12key/استثنا: تراکم پیکسلی صفحه‌نمایش تنها واجدشرایطی است که به‌دلیل تناقض حذف نمی‌شود. اگرچه تراکم صفحه دستگاه hdpi است،
drawable-night-ldpi/حذف نمی‌شود زیرا در این مرحله، هر تراکم صفحه‌ای به‌عنوان مطابقت درنظر گرفته می‌شود. برای اطلاعات بیشتر، به نمای کلی سازگاری صفحه‌نمایش مراجعه کنید. - توصیف‌کننده بعدی با بالاترین اولویت را در فهرست پیدا کنید (جدول ۲). (با MCC شروع می‌شود.)
- آیا هیچ‌کدام از فهرست‌های راهنمای منبع شامل این شناسه هستند؟
- اگر نه، به مرحله دو برگردید و به واجدشرایط بعدی نگاه کنید. در این مثال، پاسخ «نه» است تا زمانی که به توصیف‌گر زبان برسیم.
- اگر بله، به مرحله چهار بروید.
- فهرست‌های راهنمای منبعی را که شامل این توصیف‌گر نیستند حذف کنید. در این مثال، سیستم
سپس همه دایرکتوری‌هایی را که توصیف‌گر زبان ندارند حذف می‌کند:
drawable/drawable-en/ drawable-en-night/ drawable-en-notouch-12key/drawable-night-ldpi/drawable-night-notouch-12key/استثنا: اگر واجدشرایط‌کننده موردنظر تراکم پیکسلی صفحه‌نمایش باشد، Android گزینه‌ای را انتخاب می‌کند که بیشترین مطابقت را با تراکم صفحه‌نمایش دستگاه دارد. به‌طور کلی، Android ترجیح می‌دهد تصویر اصلی بزرگ‌تر را کوچک کند تا اینکه تصویر اصلی کوچک‌تر را بزرگ کند. برای اطلاعات بیشتر، به نمای کلی سازگاری صفحه‌نمایش مراجعه کنید.
- مراحل دو، سه، و چهار را تکرار کنید تا فقط یک فهرست باقی بماند. در این مثال، حالت شب
توصیف‌کننده بعدی است که برای آن مطابقت وجود دارد.
بنابراین، منابعی که حالت شب را مشخص نمی‌کنند حذف می‌شوند:
drawable-en/drawable-en-night/drawable-en-notouch-12key/دایرکتوری باقی‌مانده
drawable-en-nightاست.
اگرچه این رویه برای هر منبع درخواستی اجرا می‌شود، سیستم برخی‌از جنبه‌های آن را بهینه‌سازی می‌کند. یکی از این بهینه‌سازی‌ها این است که وقتی پیکربندی دستگاه مشخص شد، ممکن است منابع جایگزینی را که هرگز مطابقت ندارند حذف کند. برای مثال، اگر زبان پیکربندی انگلیسی باشد، هر فهرست راهنمای منبعی که توصیف‌گر زبان آن روی چیزی غیراز انگلیسی تنظیم شده باشد هرگز در مجموعه منابع بررسی‌شده گنجانده نمی‌شود (هرچند فهرست راهنمای منبع بدون توصیف‌گر زبان همچنان گنجانده می‌شود).
هنگام انتخاب منابع براساس واجدین شرایط اندازه صفحه، سیستم از منابعی استفاده می‌کند که برای صفحه‌ای کوچک‌تر از صفحه فعلی طراحی شده‌اند، اگر منابعی وجود نداشته باشد که مطابقت بهتری داشته باشند. برای مثال، صفحه‌نمایش بزرگ درصورت لزوم از منابع صفحه‌نمایش اندازه معمولی استفاده می‌کند.
بااین‌حال، اگر تنها منابع دردسترس بزرگ‌تر از صفحه فعلی باشند، سیستم از آن‌ها استفاده نمی‌کند و اگر منابع دیگری با پیکربندی دستگاه مطابقت نداشته باشند، برنامه‌تان از کار می‌افتد. برای مثال، این اتفاق زمانی می‌افتد که همه منابع چیدمان با واجدشرایط‌ساز xlarge برچسب‌گذاری شده باشند،
اما دستگاه صفحه‌نمایشی با اندازه معمولی داشته باشد.
توجه: اولویت توصیف‌کننده (در جدول ۲) مهم‌تر از تعداد توصیف‌کننده‌هایی است که دقیقاً با دستگاه مطابقت دارند. در مثال بالا، در مرحله چهارم، آخرین گزینه در فهرست شامل سه توصیف‌کننده است که دقیقاً با دستگاه مطابقت دارد (حالت شب، نوع صفحه‌لمسی، و روش ورودی)، درحالی‌که drawable-en فقط یک پارامتر منطبق دارد (زبان). بااین‌حال، زبان نسبت‌به این توصیف‌کننده‌های دیگر اولویت بالاتری دارد، بنابراین
drawable-night-notouch-12key حذف می‌شود.
منابع بیشتر
برای کسب اطلاعات بیشتر درباره منابع برنامه، منابع اضافی زیر را ببینید: