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

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

احرص دائمًا على فصل موارد التطبيق، مثل الصور والسلاسل، عن الرمز البرمجي، حتى تتمكّن من صيانتها بشكل مستقل. قدِّم أيضًا موارد بديلة لإعدادات أجهزة معيّنة من خلال تجميعها في أدلة موارد تحمل أسماء خاصة. أثناء وقت التشغيل، يستخدم 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 تلقائيًا، لأنّ المحدِّد available-width كان جديدًا في مستوى واجهة برمجة التطبيقات 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" />

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

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

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

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

?[<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 style كقيمة 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، سيتعطّل تطبيقك عند تشغيله على إصدار قديم من 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/

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

Locale = en-GB
Screen orientation = port
Screen pixel density = hdpi
Touchscreen type = notouch
Primary text input method = 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.