نظرة عامة على مراجع التطبيقات

والموارد هي الملفات الإضافية والمحتوى الثابت الذي تستخدمه التعليمات البرمجية، مثل الصور النقطية وتعريفات التنسيق وسلاسل واجهة المستخدم وإرشادات الرسوم المتحركة والمزيد.

احرص دائمًا على استخدام موارد التطبيق الخارجية مثل الصور والسلاسل من التعليمات البرمجية، بحيث يمكنك الاحتفاظ بها بشكل مستقل. أيضًا، وفّر موارد بديلة لعمليات إعداد أجهزة معينة عن طريق تجميعها في أدلة موارد ذات أسماء خاصة. أثناء وقت التشغيل، يستخدم Android المورد المناسب بناءً على الإعدادات الحالية. على سبيل المثال، قد تحتاج إلى تقديم تنسيق مختلف لواجهة المستخدم بناءً على حجم الشاشة أو سلاسل مختلفة بناءً على إعدادات اللغة.

بعد استخدام موارد تطبيقك الخارجية، يمكنك الوصول إليها باستخدام معرّفات الموارد التي يتم إنشاؤها في فئة R الخاصة بمشروعك. يوضح لك هذا المستند كيفية تجميع الموارد في مشروع Android الخاص بك. ويوضّح لك أيضًا كيفية توفير موارد بديلة لإعدادات أجهزة محدّدة، ثم الوصول إليها من رمز تطبيقك أو ملفات XML الأخرى.

أنواع موارد المجموعة

ويمكنك وضع كل نوع من الموارد في دليل فرعي محدّد ضمن دليل res/ لمشروعك. على سبيل المثال، إليك التسلسل الهرمي للملفات لمشروع بسيط:

MyProject/
    src/
        MyActivity.java
    res/
        drawable/
            graphic.png
        layout/
            main.xml
            info.xml
        mipmap/
            icon.png
        values/
            strings.xml

يحتوي دليل res/ على جميع الموارد في أدلته الفرعية، وهي: مورد صورة وموردان للتنسيق ودليل mipmap/ لرموز مشغّل التطبيقات وملف مورد سلاسل. أسماء دليل الموارد مهمة وموضّحة في الجدول 1.

ملاحظة: لمزيد من المعلومات حول استخدام مجلدات mipmap، يُرجى الاطّلاع على وضع رموز التطبيقات في أدلة mipmap.

الجدول 1. أدلة الموارد المتوافقة داخل دليل المشروع res/.

تنبيه: يجب عدم حفظ ملفات الموارد مطلقًا داخل الدليل res/ مباشرةً. يتسبب في حدوث خطأ في المحول البرمجي.

لمزيد من المعلومات حول أنواع الموارد الفردية، يُرجى الاطِّلاع على نظرة عامة على أنواع الموارد.

الموارد التي تحفظها في الأدلة الفرعية المحددة في الجدول 1 هي الموارد الافتراضية لديك. وهذا يعني أنّ هذه الموارد تحدِّد التصميم والمحتوى التلقائيَين لتطبيقك. ومع ذلك، قد تستدعي الأنواع المختلفة من الأجهزة التي تعمل بنظام التشغيل Android أنواعًا مختلفة من الموارد.

على سبيل المثال، يمكنك توفير موارد تصميم مختلفة للأجهزة التي تضمّ شاشات أكبر من العادية للاستفادة من مساحة الشاشة الإضافية. يمكنك أيضًا توفير موارد سلسلة مختلفة تترجم النص في واجهة المستخدم بناءً على إعداد لغة الجهاز. لتوفير هذه الموارد المختلفة لإعدادات الأجهزة المختلفة، تحتاج إلى توفير موارد بديلة بالإضافة إلى الموارد الافتراضية.

توفير موارد بديلة

توفِّر معظم التطبيقات موارد بديلة لدعم عمليات ضبط أجهزة محدَّدة. على سبيل المثال، يمكنك تضمين موارد بديلة قابلة للرسم لكثافات شاشة مختلفة وموارد سلسلة بديلة للغات مختلفة. أثناء وقت التشغيل، يرصد نظام التشغيل Android الإعدادات الحالية للجهاز ويحمّل الموارد المناسبة لتطبيقك.

الشكل 1. جهازان يستخدمان موارد تنسيق مختلفة بناءً على حجم الشاشة.

لتحديد بدائل محددة لمجموعة من الموارد، اتّبِع الخطوات التالية:

1. أنشئ دليلاً جديدًا في res/ يحمل اسم النموذج <resources_name>-<qualifier>.
   • <resources_name> هو اسم الدليل للموارد التلقائية المقابلة (كما هو موضح في الجدول 1).
   • <qualifier> هو اسم يحدِّد الإعداد الفردي الذي سيتم استخدام هذه الموارد له (كما هو موضح في الجدول 2).

   يمكنك إلحاق أكثر من رمز <qualifier> واحد. افصل بين كل واحد بشرطة.

   تنبيه: عند إلحاق مؤهلات متعددة، يجب وضعها بالترتيب نفسه الذي تم إدراجها به في الجدول 2. في حالة ترتيب المؤهِّلات بشكل غير صحيح، يتم تجاهل الموارد.

2. احفظ الموارد البديلة المناسبة في هذا الدليل الجديد. يجب تسمية ملفات الموارد تمامًا مثل ملفات الموارد الافتراضية.

على سبيل المثال، إليك بعض الموارد التلقائية والبديلة:

res/
    drawable/
        icon.png
        background.png
    drawable-hdpi/
        icon.png
        background.png

يشير المؤهِّل hdpi إلى أنّ الموارد في هذا الدليل مخصَّصة للأجهزة ذات الشاشة العالية الكثافة. يتم تحديد حجم الصور الموجودة في هذه الأدلة القابلة للرسم حسب كثافات شاشة محددة، لكن أسماء الملفات متطابقة تمامًا. بهذه الطريقة، يظل رقم تعريف المورد الذي تستخدمه للإشارة إلى الصورة icon.png أو background.png هو نفسه دائمًا. ويختار نظام التشغيل Android إصدار كل مورد يتطابق مع الجهاز الحالي على أفضل نحو من خلال مقارنة معلومات ضبط الجهاز بالمؤهلات الواردة في اسم دليل الموارد.

تحذير: عند تحديد مورد بديل، تأكَّد من تحديد المورد أيضًا في الإعدادات التلقائية. وبخلاف ذلك، قد يواجه تطبيقك استثناءات وقت التشغيل عندما يغيّر الجهاز الإعدادات. على سبيل المثال، إذا أضفت سلسلة إلى values-en فقط وليس values، قد يواجه تطبيقك استثناءً Resource Not Found عندما يغيّر المستخدم لغة النظام التلقائية.

يسرد الجدول 2 مؤهلات التكوين الصالحة بترتيب الأسبقية. يمكنك إضافة مؤهِّلات متعددة إلى اسم دليل واحد من خلال فصل كل مؤهِّل بشَرطة. إذا كنت تستخدم مؤهِّلات متعددة لدليل موارد، عليك إضافتها إلى اسم الدليل بترتيب إدراجها في الجدول.

الجدول 2. أسماء مؤهلات التهيئة.

ملاحظة:لا تتوافق بعض إصدارات Android مع بعض المؤهِّلات. يؤدي استخدام مؤهِّل جديد إلى إضافة مؤهِّل إصدار النظام الأساسي ضمنيًا حتى تتمكّن الأجهزة القديمة من تجاهله. على سبيل المثال، يؤدي استخدام مؤهِّل w600dp إلى تضمين المؤهِّل v13 تلقائيًا، لأنّ مؤهِّل العرض المتاح كان جديدًا في المستوى 13 من واجهة برمجة التطبيقات. لتجنب أي مشاكل، احرص دائمًا على تضمين مجموعة من الموارد التلقائية (مجموعة من الموارد بدون أي مؤهِّلات). لمزيد من المعلومات، يُرجى الاطّلاع على القسم حول توفير أفضل توافق للأجهزة مع الموارد.

قواعد اسم المؤهِّل

في ما يلي بعض القواعد المتعلّقة باستخدام أسماء مؤهِّلات الإعداد:

• يمكنك تحديد مؤهلات متعددة لمجموعة واحدة من الموارد، مفصولة بشرطة. على سبيل المثال، تنطبق drawable-en-rUS-land على الأجهزة التي تستخدم اللغة الإنجليزية الأمريكية في الاتجاه الأفقي.
• يجب أن تكون المؤهِّلات بالترتيب المذكور في الجدول 2.
  • الخطأ: drawable-hdpi-port/
  • صحيح: drawable-port-hdpi/
• ولا يمكن دمج أدلة الموارد البديلة. على سبيل المثال، لا يمكنك الحصول على res/drawable/drawable-en/.
• والقيم غير حساسة لحالة الأحرف. يحوِّل برنامج تجميع الموارد أسماء الأدلة إلى أحرف صغيرة قبل المعالجة لتجنّب المشاكل في أنظمة الملفات غير الحساسة لحالة الأحرف. والهدف من استخدام أي أحرف لاتينية كبيرة في الأسماء هو تحسين إمكانية القراءة فقط.
• يُسمح باستخدام قيمة واحدة فقط لكل نوع مؤهِّل. على سبيل المثال، إذا كنت تريد استخدام الملفات القابلة للرسم نفسها في إسبانيا وفرنسا، لا يمكن أن يكون لديك دليل باسم drawable-es-fr/. بدلاً من ذلك، ستحتاج إلى دليلَي موارد، مثل drawable-es/ وdrawable-fr/، يتضمّنان الملفات المناسبة. ومع ذلك، لا يلزمك تكرار الملفات في كلا الموقعين. بدلاً من ذلك، يمكنك إنشاء اسم مستعار لمورد، كما هو موضح في قسم إنشاء موارد بديلة.

بعد حفظ الموارد البديلة في أدلة تحمل أسماء هذه المؤهِّلات، يطبِّق Android تلقائيًا الموارد المتوفّرة في تطبيقك استنادًا إلى إعدادات الجهاز الحالية. في كل مرة يتم فيها طلب مورد، يبحث نظام Android عن أدلة الموارد البديلة التي تحتوي على ملف المورد المطلوب، ثم يعثر على أفضل المورد المطابق.

إذا لم تكن هناك موارد بديلة تطابق إعداد جهاز محدّد، سيستخدم Android الموارد التلقائية المقابلة، وهي مجموعة الموارد لنوع معيّن من الموارد لا تتضمن أي مؤهِّل للضبط.

إنشاء موارد أسماء مستعارة

عندما يكون لديك مورد تريد استخدامه لأكثر من إعداد واحد للجهاز ولكنك لا تريد تقديمه كمورد افتراضي، لن تحتاج إلى وضع المورد نفسه في أكثر من دليل موارد بديل. بدلاً من ذلك، يمكنك إنشاء مورد بديل يعمل كاسم مستعار لمورد محفوظ في دليل الموارد الافتراضي.

ملاحظة: لا تقدم جميع الموارد آلية يمكنك من خلالها إنشاء اسم مستعار لمورد آخر. على وجه التحديد، لا توفّر الصور المتحركة والقائمة والموارد الأولية وغيرها من الموارد غير المحدّدة في دليل xml/ هذه الميزة.

على سبيل المثال، تخيل أن لديك رمز التطبيق icon.png، وتحتاج إلى إصدار فريد منه لللغات المختلفة. ومع ذلك، هناك لغتين، الإنجليزية الكندا، والفرنسية-الكندية، بحاجة إلى استخدام نفس الإصدار. لست بحاجة إلى نسخ الصورة نفسها في دليل الموارد لكل من الإنجليزية-الكندية والفرنسية-الكندية. بدلاً من ذلك، يمكنك حفظ الصورة المستخدَمة لكليهما باستخدام أي اسم بخلاف icon.png، مثل icon_ca.png، وإدراجها في دليل res/drawable/ التلقائي. بعد ذلك، عليك إنشاء ملف icon.xml في res/drawable-en-rCA/ وres/drawable-fr-rCA/ يشير إلى المورد icon_ca.png باستخدام العنصر <bitmap>. يتيح لك هذا تخزين نسخة واحدة فقط من ملف PNG وملفي XML صغيرين يشيران إليهما. راجِع الأمثلة الواردة في الأقسام التالية لمعرفة التفاصيل

قابلة للرسم

لإنشاء اسم مستعار لأحد العناصر القابلة للرسم الحالية، استخدِم العنصر <drawable> على النحو التالي:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <drawable name="icon">@drawable/icon_ca</drawable>
</resources>

إذا حفظت هذا الملف باسم icon.xml في دليل موارد بديل، مثل res/values-en-rCA/، سيتم تجميع الملف في مورد يمكنك الإشارة إليه باعتباره R.drawable.icon، ولكنه في الواقع اسم مستعار لمورد R.drawable.icon_ca الذي يتم حفظه في res/drawable/.

التنسيق

لإنشاء اسم مستعار لتنسيق حالي، يمكنك استخدام العنصر <include> المحاط بعنصر <merge>:

<?xml version="1.0" encoding="utf-8"?>
<merge>
    <include layout="@layout/main_ltr"/>
</merge>

إذا حفظت هذا الملف باسم main.xml، سيتم تجميعه في مورد يمكنك الإشارة إليه باسم R.layout.main، ولكنه في الواقع اسم مستعار لمورد R.layout.main_ltr.

السلاسل والقيم البسيطة الأخرى

لإنشاء اسم مستعار لسلسلة حالية، استخدم رقم تعريف المورد للسلسلة المطلوبة كقيمة للسلسلة الجديدة:

<?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 وlayout. لمزيد من المعلومات عن الأنواع المختلفة، يُرجى الاطِّلاع على نظرة عامة على أنواع الموارد.
• اسم المورد، وهو إما اسم الملف باستثناء الامتداد أو القيمة في سمة android:name بتنسيق XML، إذا كان المورد قيمة بسيطة، مثل سلسلة

هناك طريقتان يمكنك من خلالهما الوصول إلى مورد:

• في الرمز: باستخدام عدد صحيح ثابت من فئة فرعية من فئة R، مثل:

  R.string.hello

  string هو نوع المورد وhello هو اسم المورد. هناك العديد من واجهات برمجة تطبيقات Android التي يمكنها الوصول إلى مواردك عند تقديم معرّف مورد بهذا التنسيق. لمزيد من المعلومات، يُرجى الاطّلاع على قسم الوصول إلى الموارد في الرمز.

• في XML: باستخدام بنية XML خاصة تتوافق مع رقم تعريف المورد المحدّد في فئة R، مثلاً:

  @string/hello

  string هو نوع المورد وhello هو اسم المورد. يمكنك استخدام هذه بناء الجملة في مورد XML في أي مكان من المتوقع أن تقدم فيه قيمة في مورد. لمزيد من المعلومات، يُرجى الاطّلاع على قسم الوصول إلى الموارد من XML.

الوصول إلى الموارد في الرموز البرمجية

يمكنك استخدام مورد في الرمز من خلال تمرير رقم تعريف المورد كمَعلمة طريقة. على سبيل المثال، يمكنك ضبط ImageView لاستخدام المورد res/drawable/myimage.png باستخدام setImageResource():

val imageView = findViewById(R.id.myimageview) as ImageView
imageView.setImageResource(R.drawable.myimage)

ImageView imageView = (ImageView) findViewById(R.id.myimageview);
imageView.setImageResource(R.drawable.myimage);

يمكنك أيضًا استرداد موارد فردية باستخدام طرق في Resources، والتي يمكنك الحصول على مثيل لها باستخدام getResources().

بناء الجملة

فيما يلي بناء الجملة للإشارة إلى مورد في التعليمة البرمجية:

[<package_name>.]R.<resource_type>.<resource_name>

• <package_name> هو اسم الحزمة التي يوجد فيها المورد (غير مطلوب عند الإشارة إلى موارد من حزمتك الخاصة).
• <resource_type> هي الفئة الفرعية R لنوع المورد.
• القيمة <resource_name> هي اسم ملف المورد بدون امتداد الملف أو قيمة السمة android:name في عنصر XML للقيم البسيطة.

للحصول على مزيد من المعلومات حول كل نوع من أنواع الموارد وكيفية الإشارة إليها، يُرجى الاطّلاع على نظرة عامة على أنواع الموارد.

حالات الاستخدام

هناك العديد من الطرق التي تقبل معلَمة رقم تعريف المورد، ويمكنك استرداد الموارد باستخدام الطرق المتوفّرة في Resources. يمكنك الحصول على مثيل Resources باستخدام Context.getResources().

فيما يلي بعض الأمثلة على الوصول إلى الموارد في الرمز:

// Load a background for the current screen from a drawable resource.
window.setBackgroundDrawableResource(R.drawable.my_background_image)

// Set the Activity title by getting a string from the Resources object, because
//  this method requires a CharSequence rather than a resource ID.
window.setTitle(resources.getText(R.string.main_title))

// Load a custom layout for the current screen.
setContentView(R.layout.main_screen)

// Set a slide in animation by getting an Animation from the Resources object.
flipper.setInAnimation(AnimationUtils.loadAnimation(this,
        R.anim.hyperspace_in))

// Set the text on a TextView object using a resource ID.
val msgTextView = findViewById(R.id.msg) as TextView
msgTextView.setText(R.string.hello_message)

// Load a background for the current screen from a drawable resource.
getWindow().setBackgroundDrawableResource(R.drawable.my_background_image) ;

// Set the Activity title by getting a string from the Resources object, because
//  this method requires a CharSequence rather than a resource ID.
getWindow().setTitle(getResources().getText(R.string.main_title));

// Load a custom layout for the current screen.
setContentView(R.layout.main_screen);

// Set a slide in animation by getting an Animation from the Resources object.
flipper.setInAnimation(AnimationUtils.loadAnimation(this,
        R.anim.hyperspace_in));

// Set the text on a TextView object using a resource ID.
TextView msgTextView = (TextView) findViewById(R.id.msg);
msgTextView.setText(R.string.hello_message);

تحذير: لا تعدِّل ملف R.java يدويًا. ويتم إنشاؤها بواسطة أداة aapt عند تجميع مشروعك. ويتم إلغاء أي تغييرات في المرة التالية التي يتم فيها التجميع.

الوصول إلى الموارد من ملف XML

يمكنك تحديد قيم لبعض سمات وعناصر XML باستخدام مرجع إلى مورد موجود. غالبًا ما تفعل ذلك عند إنشاء ملفات التخطيط، لتوفير السلاسل والصور للتطبيقات المصغّرة.

على سبيل المثال، إذا أضفت Button إلى التنسيق، استخدِم مورد سلسلة لنص الزر:

<Button
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:text="@string/submit" />

بناء الجملة

فيما يلي بناء الجملة للإشارة إلى مورد في مورد XML:

@[<package_name>:]<resource_type>/<resource_name>

• <package_name> هو اسم الحزمة التي يوجد فيها المورد (غير مطلوب عند الإشارة إلى موارد من الحزمة نفسها).
• <resource_type> هي الفئة R الفرعية لنوع المورد.
• القيمة <resource_name> هي اسم ملف المورد بدون الامتداد أو قيمة السمة android:name في عنصر XML للقيم البسيطة.

للحصول على مزيد من المعلومات حول كل نوع من أنواع الموارد وكيفية الإشارة إليها، يُرجى الاطّلاع على نظرة عامة على أنواع الموارد.

حالات الاستخدام

في بعض الحالات، يجب عليك استخدام مورد لقيمة في XML، مثل تطبيق صورة قابلة للرسم على أداة، ويمكنك أيضًا استخدام مورد في XML في أي مكان يقبل قيمة بسيطة. على سبيل المثال، إذا كان لديك ملف المورد التالي الذي يتضمّن مورد لون ومورد سلسلة:

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <color name="opaque_red">#f00</color>
   <string name="hello">Hello!</string>
</resources>

يمكنك استخدام هذه الموارد في ملف التنسيق التالي لتعيين لون النص وسلسلة النص:

<?xml version="1.0" encoding="utf-8"?>
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:textColor="@color/opaque_red"
    android:text="@string/hello" />

في هذه الحالة، لا تحتاج إلى تحديد اسم الحزمة في مرجع الموارد، لأن الموارد من الحزمة الخاصة بك. للإشارة إلى مورد نظام، عليك تضمين اسم الحزمة، كما هو موضح في المثال التالي:

<?xml version="1.0" encoding="utf-8"?>
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:textColor="@android:color/secondary_text_dark"
    android:text="@string/hello" />

ملاحظة: استخدم دائمًا موارد السلسلة، حتى يمكن ترجمة تطبيقك إلى لغات أخرى. للحصول على معلومات حول إنشاء موارد بديلة (مثل السلاسل المترجَمة)، يُرجى الاطّلاع على تقديم موارد بديلة. للحصول على دليل كامل لأقلمة تطبيقك للغات الأخرى، راجع ترجمة تطبيقك.

يمكنك أيضًا استخدام الموارد في XML لإنشاء أسماء مستعارة. على سبيل المثال، يمكنك إنشاء مورد قابل للرسم وهو اسم مستعار لمورد آخر قابل للرسم:

<?xml version="1.0" encoding="utf-8"?>
<bitmap xmlns:android="http://schemas.android.com/apk/res/android"
    android:src="@drawable/other_drawable" />

يبدو هذا تكرارًا، ولكنه قد يكون مفيدًا جدًا عند استخدام مورد بديل. لمزيد من المعلومات، راجِع القسم الذي يتناول إنشاء موارد بديلة.

سمات أنماط المرجع

يتيح لك مورد سمة النمط الإشارة إلى قيمة سمة ما في المظهر المطبق حاليًا. تتيح لك الإشارة إلى سمة نمط تخصيص مظهر عناصر واجهة المستخدم من خلال تنسيقها لمطابقة الأشكال القياسية التي يوفرها المظهر الحالي، بدلاً من تقديم قيمة ذات ترميز ثابت. وتشير الإشارة إلى سمة النمط بشكل أساسي إلى، "استخدم النمط الذي تحدده هذه السمة في المظهر الحالي".

للإشارة إلى سمة نمط، تكون بنية الاسم مطابقة تقريبًا لتنسيق المورد العادي، ولكن بدلاً من الرمز "at" (@)، استخدِم علامة الاستفهام (?). ويكون جزء نوع المورد اختياريًا. إذًا تكون صيغة المرجع على النحو التالي:

?[<package_name>:][<resource_type>/]<resource_name>

على سبيل المثال، إليك كيفية الإشارة إلى سمة لضبط لون النص لمطابقة لون النص الثانوي لمظهر النظام:

<EditText id="text"
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:textColor="?android:textColorSecondary"
    android:text="@string/hello_world" />

تحدّد السمة android:textColor هنا اسم سمة النمط في المظهر الحالي. يستخدم Android الآن القيمة المطبّقة على سمة النمط android:textColorSecondary كقيمة للسمة android:textColor ضمن هذه الأداة. ولأنّ أداة مورد النظام تعلم أنّ مورد السمة متوقعًا في هذا السياق، لن تحتاج إلى تحديد النوع صراحةً، وهو ?android:attr/textColorSecondary. ويمكنك استبعاد النوع attr.

الوصول إلى الملفات الأصلية

قد تحتاج إلى الوصول إلى ملفاتك وأدلتك الأصلية، على الرغم من كونها غير شائعة. وإذا فعلت ذلك، لن ينجح حفظ ملفاتك في res/، لأنّ الطريقة الوحيدة لقراءة مورد من res/ هي باستخدام رقم تعريف المورد. يمكنك بدلاً من ذلك حفظ مواردك في دليل assets/.

لا يتم منح الملفات المحفوظة في دليل assets/ معرّف مورد، لذا لا يمكنك الرجوع إليها من خلال الفئة R أو من موارد XML. بدلاً من ذلك، يمكنك البحث عن الملفات في دليل assets/ كنظام ملفات عادي وقراءة البيانات الأولية باستخدام AssetManager.

مع ذلك، إذا كان كل ما تحتاج إليه هو إمكانية قراءة البيانات الأولية (مثل ملف فيديو أو ملف صوتي)، يمكنك حفظ الملف في دليل res/raw/ وقراءة بث وحدات البايت باستخدام openRawResource().

الوصول إلى موارد النظام الأساسي

يحتوي Android على عدد من الموارد العادية، مثل الأنماط والمظاهر والتنسيقات. للوصول إلى هذه الموارد، عليك تحديد مرجع المورد باستخدام اسم الحزمة android. على سبيل المثال، يوفّر Android مورد تنسيق يمكنك استخدامه لإدراج العناصر في ListAdapter:

listAdapter = ArrayAdapter(this, android.R.layout.simple_list_item_1, myarray)

setListAdapter(new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, myarray));

في هذا المثال، simple_list_item_1 هو مورد تنسيق تحدّده النظام الأساسي للعناصر في ListView. يمكنك استخدام هذا بدلاً من إنشاء التخطيط الخاص بك لعناصر القائمة.

توفير أفضل توافق للأجهزة مع الموارد

لكي يكون تطبيقك متوافقًا مع عمليات ضبط أجهزة متعدّدة، من المهم جدًا أن يتم دائمًا توفير موارد تلقائية لكل نوع من الموارد التي يستخدمها تطبيقك.

على سبيل المثال، إذا كان تطبيقك يتيح استخدام عدة لغات، يجب دائمًا تضمين دليل values/ (يتم حفظ السلاسل فيه) بدون مؤهِّل لغة ومنطقة. إذا وضعت بدلاً من ذلك جميع ملفات السلسلة في أدلة لها مؤهل لغة ومنطقة، سيتعطّل تطبيقك عند تشغيله على جهاز تم ضبطه على لغة لا تتيحها السلاسل.

إذا قدّمت موارد values/ التلقائية، سيتم تشغيل تطبيقك بشكل صحيح، حتى إذا لم يفهم المستخدم اللغة التي يقدّمها. إنها أفضل من التعطل.

وبالمثل، إذا كنت توفر موارد تنسيق مختلفة استنادًا إلى اتجاه الشاشة، اختَر اتجاهًا واحدًا كاتجاه تلقائي. على سبيل المثال، بدلاً من توفير موارد التنسيق في layout-land/ للوضع الأفقي وlayout-port/ للوضع العمودي، يمكنك ترك إعداد تلقائي، مثل layout/ للوضع الأفقي وlayout-port/ للصورة العمودية.

يُعدّ تقديم الموارد التلقائية مهمًا، ليس فقط لأنّ تطبيقك قد يعمل على عملية إعداد لم تتوقعها، ولكن أيضًا لأنّ إصدارات Android الجديدة تضيف أحيانًا مؤهِّلات للإعدادات لا تتوافق معها الإصدارات القديمة. إذا استخدمت مؤهِّل موارد جديدًا مع الحفاظ على توافق الرموز مع الإصدارات القديمة من Android، سيتعطّل التطبيق إذا لم توفّر موارد تلقائية لأنّه لا يمكنه استخدام الموارد التي تحمل اسم المؤهِّل الجديد.

على سبيل المثال، إذا تم ضبط minSdkVersion على 4، وكنت مؤهلاً لجميع مواردك القابلة للرسم باستخدام الوضع الليلي (night أو notnight، التي تمت إضافتها في المستوى 8 من واجهة برمجة التطبيقات)، لن يتمكّن الجهاز من المستوى 4 من واجهة برمجة التطبيقات من الوصول إلى الموارد القابلة للرسم والأعطال الخاصة بك. في هذه الحالة، ربما تريد أن يكون notnight هو الموارد التلقائية لديك، لذا عليك استبعاد هذا المؤهل ووضع الموارد القابلة للرسم إما drawable/ أو drawable-night/.

باختصار، لتوفير أفضل توافق مع الأجهزة، عليك دائمًا توفير الموارد التلقائية للموارد التي يحتاج تطبيقك لتنفيذها بشكل صحيح. ثم يمكنك إنشاء موارد بديلة لعمليات إعداد أجهزة محددة باستخدام مؤهلات التهيئة.

هناك استثناء واحد لهذه القاعدة: إذا كان مقياس minSdkVersion في تطبيقك 4 أو أعلى، لا تحتاج إلى موارد تلقائية قابلة للرسم عند توفير موارد بديلة قابلة للرسم باستخدام مؤهل كثافة الشاشة. يمكن لنظام Android العثور على أفضل تطابق بين كثافات الشاشة البديلة وتغيير حجم الصور النقطية حسب الضرورة، حتى في حال عدم توفُّر موارد تلقائية قابلة للرسم. ومع ذلك، للحصول على أفضل تجربة على جميع أنواع الأجهزة، قدِّم عناصر قابلة للرسم بديلة لأنواع الكثافة الثلاثة.

كيفية عثور نظام التشغيل Android على المورد الأكثر تطابقًا

عندما تطلب موردًا توفّر بدائل له، يختار نظام التشغيل Android موردًا بديلاً لاستخدامه في وقت التشغيل، بناءً على الإعدادات الحالية للجهاز. لتوضيح كيفية اختيار Android لمورد بديل، افترض أن الأدلة التالية القابلة للرسم تحتوي على نُسخ مختلفة من الصور نفسها:

drawable/
drawable-en/
drawable-fr-rCA/
drawable-en-port/
drawable-en-notouch-12key/
drawable-port-ldpi/
drawable-port-notouch-12key/

ولنفترض أنّ ما يلي هو إعدادات الجهاز:

اللغة = en-GB
اتجاه الشاشة = port
كثافة وحدات البكسل في الشاشة = hdpi
نوع الشاشة التي تعمل باللمس = notouch
أسلوب إدخال النص الأساسي = 12key

من خلال مقارنة إعدادات الجهاز بالموارد البديلة المتاحة، يختار نظام Android العناصر القابلة للرسم من drawable-en-port.

يصل النظام إلى قراره بشأن الموارد التي يجب استخدامها على المنطق التالي:

الشكل 2. مخطط انسيابي لكيفية عثور Android على المورد الأفضل مطابقة

1. أزِل ملفات الموارد التي تتعارض مع إعدادات الجهاز.

   تم حذف الدليل drawable-fr-rCA/ لأنه يتناقض مع اللغة en-GB.

   drawable/
   drawable-en/
   drawable-fr-rCA/
   drawable-en-port/
   drawable-en-notouch-12key/
   drawable-port-ldpi/
   drawable-port-notouch-12key/
   

   استثناء: كثافة وحدات بكسل الشاشة هي المؤهِّل الوحيد الذي لا يتم استبعاده بسبب وجود تناقض. مع أنّ كثافة الشاشة في الجهاز تبلغ hdpi، لا يتم استبعاد drawable-port-ldpi/ لأنّ جميع كثافة الشاشة تُعتبر متطابقة في هذه المرحلة. وللحصول على المعلومات، يُرجى الاطِّلاع على نظرة عامة على توافق الشاشة.

2. ابحث عن المُؤهِّل الأعلى درجة التالي في القائمة (الجدول 2). (ابدأ باستخدام "مركز عملائي").
3. هل يحتوي أي من أدلة الموارد على هذا المؤهِّل؟
   • إذا كانت الإجابة "لا"، فارجع إلى الخطوة الثانية وانظر إلى المؤهل التالي. في هذا المثال، تكون الإجابة "لا" إلى أن يتم الوصول إلى معرِّف اللغة.
   • إذا كانت الإجابة بنعم، انتقِل إلى الخطوة الرابعة.
4. أزِل أدلة الموارد التي لا تتضمّن هذا المؤهِّل. في هذا المثال، سيزيل النظام التالي جميع الأدلة التي لا تتضمّن معرِّف لغة:

   drawable/
   drawable-en/
   drawable-en-port/
   drawable-en-notouch-12key/
   drawable-port-ldpi/
   drawable-port-notouch-12key/
   

   استثناء: إذا كان المؤهِّل المعنيّ هو كثافة وحدات بكسل الشاشة، سيحدِّد Android الخيار الذي يتطابق إلى حدّ كبير مع كثافة شاشة الجهاز. بشكل عام، يفضّل نظام Android تصغير حجم الصورة الأصلية الأكبر لتكبير الصورة الأصلية الأصغر حجمًا. لمزيد من المعلومات، راجع نظرة عامة على توافق الشاشة.

5. كرر الخطوات الثانية والثالثة والرابعة حتى يتبقى دليل واحد فقط. في هذا المثال، اتجاه الشاشة هو المؤهِّل التالي الذي توجد له أي مطابقات. ولذلك، يتم استبعاد الموارد التي لا تحدّد اتجاه الشاشة:

   drawable-en/
   drawable-en-port/
   drawable-en-notouch-12key/
   

   الدليل المتبقي هو drawable-en-port.

على الرغم من أنه يتم تنفيذ هذا الإجراء لكل مورد مطلوب، يحسّن النظام بعض جوانبه. ومن بين هذه التحسينات أنّه بعد معرفة إعدادات الجهاز، قد يتم التخلص من الموارد البديلة التي لا يمكن مطابقتها أبدًا. على سبيل المثال، إذا كانت لغة الإعداد هي الإنجليزية، لن يتم مطلقًا تضمين أي دليل موارد تم ضبط مؤهِّل لغة آخر له على شيء آخر غير الإنجليزية في مجموعة الموارد التي تم وضع علامة عليها (على الرغم من أنّ دليل الموارد بدون مؤهِّل اللغة يظل مضمَّنًا).

عند تحديد الموارد بناءً على مؤهلات حجم الشاشة، يستخدم النظام الموارد المصممة لشاشة أصغر من الشاشة الحالية إذا لم تكن هناك موارد تتطابق بشكل أفضل. على سبيل المثال، تستخدم الشاشة الكبيرة الحجم موارد الشاشة ذات الحجم العادي إذا لزم الأمر.

ومع ذلك، إذا كانت الموارد الوحيدة المتاحة أكبر من الشاشة الحالية، لا يستخدمها النظام، وسيتعطّل تطبيقك إذا لم تتطابق أي موارد أخرى مع إعدادات الجهاز. يحدث ذلك مثلاً إذا تم وضع علامة المُؤهِّل xlarge على جميع موارد التنسيق، ولكن الجهاز يعمل بشاشة ذات حجم عادي.

ملاحظة: إنّ أولوية المؤهِّل (في الجدول 2) أكثر أهمية من عدد المؤهِّلات التي تتطابق تمامًا مع الجهاز. في المثال السابق، يتضمّن الخيار الأخير في القائمة في الخطوة الرابعة ثلاثة مؤهلات تطابق الجهاز تمامًا (الاتجاه ونوع الشاشة التي تعمل باللمس وأسلوب الإدخال)، في حين أنّ السمة drawable-en تتضمّن معلَمة واحدة فقط تتطابق مع (اللغة). في المقابل، تحظى اللغة بأولوية أعلى من تلك المؤهِّلات الأخرى، وبالتالي لا يمكن استخدام السمة drawable-port-notouch-12key.