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

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

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

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

• في الرمز: باستخدام عدد صحيح ثابت من فئة فرعية من فئة 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.