نظرة عامة على موارد التطبيق (المشاهدات)

المفاهيم والتنفيذ في Jetpack Compose

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

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

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

الدليل

نوع المورد

animator/

ملفات XML تحدّد الرسومات المتحركة للعناصر

anim/

ملفات XML التي تحدد الرسوم المتحركة بينية يمكن أيضًا حفظ حركات العناصر في هذا الدليل، ولكن يُفضّل استخدام الدليل animator/ لحركات العناصر من أجل التمييز بين النوعين.

color/

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

drawable/

ملفات Bitmap (ملفات PNG أو .9.png أو JPG أو GIF) أو ملفات XML التي يتم تجميعها في الأنواع الفرعية التالية من موارد الرسومات القابلة للرسم:

  • ملفات الصور النقطية
  • صور Nine-patch (صور نقطية قابلة لتغيير الحجم)
  • قوائم الولايات
  • الأشكال
  • الرسومات القابلة للرسم الخاصة بالصور المتحركة
  • عناصر قابلة للرسم أخرى

لمزيد من المعلومات، يُرجى الاطّلاع على الموارد القابلة للرسم.

mipmap/

ملفات قابلة للرسم لكثافات مختلفة لرموز مشغّل التطبيق لمزيد من المعلومات حول إدارة رموز مشغّل التطبيقات باستخدام مجلدات mipmap/، يُرجى الاطّلاع على وضع رموز التطبيقات في أدلة mipmap.

layout/

ملفات XML التي تحدّد تخطيط واجهة المستخدم لمزيد من المعلومات، اطّلِع على مورد التنسيق.

menu/

ملفات XML تحدّد قوائم التطبيقات، مثل قائمة الخيارات أو قائمة السياقات أو القائمة الفرعية. لمزيد من المعلومات، يُرجى الاطّلاع على مورد القائمة.

raw/

ملفات عشوائية لحفظها في شكلها الأولي لفتح هذه الموارد باستخدام InputStream غير معدَّل، استخدِم الدالة Resources.openRawResource مع رقم تعريف المرجع، وهو R.raw.filename.

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

values/

ملفات XML التي تحتوي على قيم بسيطة، مثل السلاسل والأعداد الصحيحة والألوان

في حين أنّ ملفات موارد XML في أدلة res/ الفرعية الأخرى تحدّد موردًا واحدًا استنادًا إلى اسم ملف XML، تصف الملفات في الدليل values/ موارد متعدّدة. بالنسبة إلى ملف في هذا الدليل، يحدّد كل عنصر فرعي من العنصر مصدرًا واحدًا. على سبيل المثال، ينشئ العنصر المورد R.string، وينشئ العنصر المورد R.color.

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

لمزيد من المعلومات، اطّلِع على موارد السلاسل ومورد الأنماط والمزيد من أنواع الموارد.

xml/

ملفات XML عشوائية يمكن قراءتها في وقت التشغيل من خلال استدعاء Resources.getXML(). يجب حفظ ملفات إعداد XML المختلفة هنا.

font/

ملفات الخطوط التي تحمل امتدادات مثل TTF أو OTF أو TTC أو ملفات XML التي تتضمّن عنصر لمزيد من المعلومات حول الخطوط كموارد، يُرجى الاطّلاع على إضافة خط كمورد XML.

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

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

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

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

الشكل 1. جهازان يستخدمان موارد تخطيط مختلفة استنادًا إلى حجم الشاشة

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

  1. أنشئ دليلاً جديدًا في res/ باسم <resources_name>-<qualifier>.

    • <resources_name> هو اسم دليل الموارد التلقائية المقابلة (المحدّدة في الجدول 1).
    • ‫<qualifier> هو اسم يحدّد إعدادًا فرديًا يجب استخدام هذه الموارد له (محدّد في الجدول 2).

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

  2. احفظ المراجع البديلة المناسبة في هذا الدليل الجديد. يجب أن تتطابق أسماء ملفات الموارد تمامًا مع أسماء ملفات الموارد التلقائية.

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

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

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

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

الجدول 2. أسماء مؤهلات الإعداد

الإعداد

قيم المؤهِّل

الوصف

رمز البلد ورمز الشبكة

أمثلة:

mcc310

mcc310-mnc004

mcc208-mnc00

رمز البلد المتنقل (MCC)، يليه اختياريًا رمز شبكة الجوّال (MNC) من شريحة SIM في الجهاز على سبيل المثال، mcc310 هي الولايات المتحدة على أي شركة اتصالات، وmcc310-mnc004 هي الولايات المتحدة على Verizon، وmcc208-mnc00 هي فرنسا على Orange.

إذا كان الجهاز يستخدم اتصالاً لاسلكيًا (أي أنّه هاتف GSM)، يتم الحصول على قيمتَي رمز البلد المتنقّل (MCC) ورمز الشبكة المتنقّلة (MNC) من شريحة SIM.

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

اطّلِع أيضًا على حقلَي الإعداد mcc وmnc اللذين يشيران إلى رمز البلد الحالي لشبكة الجوّال ورمز شبكة الجوّال الحالي على التوالي.

اللغة والبرنامج النصي (اختياري) والمنطقة (اختياري)

أمثلة:

en

fr

en-rUS

fr-rFR

fr-rCA

b+en

b+en+US

b+es+419

b+zh+Hant

b+sr+Latn+RS

يتم تحديد اللغة من خلال رمز لغة ISO 639-2{:.external} مكوّن من حرفين، يليه بشكل اختياري رمز منطقة ISO 3166-1-alpha-2{:.external} مكوّن من حرفين (يسبقه الحرف r بالأحرف الصغيرة).

الرموز غير حساسة لحالة الأحرف. تُستخدَم البادئة r للتمييز بين جزء المنطقة. لا يمكنك تحديد منطقة وحدها.

أتاح الإصدار 7.0 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 24) إمكانية استخدام علامات اللغة BCP 47{:.external}، والتي يمكنك استخدامها لتحديد الموارد الخاصة باللغة والمنطقة. تتألف علامة اللغة من سلسلة من علامات فرعية واحدة أو أكثر، ويؤدي كل منها إلى تحسين أو تضييق نطاق اللغة المحددة بواسطة العلامة الإجمالية. لمزيد من المعلومات عن علامات اللغة، يُرجى الاطّلاع على علامات تحديد اللغات{:.external}.

لاستخدام علامة لغة BCP 47، ادمج b+ مع رمز لغة ISO 639-2{:.external} مكوّن من حرفَين، ويمكنك اختياريًا إضافة علامات فرعية أخرى مفصولة بـ +.

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

للحصول على دليل كامل حول أقلمة تطبيقك للغات أخرى، يُرجى الاطّلاع على مقالة أقلمة تطبيقك.

اطّلِع أيضًا على طريقة getLocales التي توفّر قائمة محدّدة باللغات المحلية. تتضمّن هذه القائمة اللغة الأساسية.
صيغة المخاطبة المناسبة نحويًا masculine
feminine
neuter

جنس المستخدم النحوي تُستخدَم للغات التي تتضمّن صيغة مخاطبة مناسبة نحويًا.

على سبيل المثال، إذا كنت بحاجة إلى توفير مراجع مختلفة للمستخدمين الذين يتحدثون الفرنسية، يمكنك استخدام أدلة مثل ما يلي:

res/
  values-fr/
    strings.xml (السلاسل التلقائية التي لم يتم تحديد الجنس فيها)
  values-fr-masculine/
    strings.xml (السلاسل التي تم تحديد الجنس فيها على أنّه مذكر)
  values-fr-feminine/
    strings.xml (السلاسل التي تم تحديد الجنس فيها على أنّه مؤنث)
  values-fr-neuter/
    strings.xml (السلاسل التي تم تحديد الجنس فيها على أنّه محايد)

راجِع: التصريف اللغوي في Android.

يمكنك أيضًا الاطّلاع على طريقة الضبط getGrammaticalGender() التي تشير إلى الجنس النحوي.

تمت إضافته في مستوى واجهة برمجة التطبيقات 34.

اتجاه التنسيق

ldrtl

ldltr

تمثّل هذه السمة اتجاه التنسيق لتطبيقك، حيث يشير ldrtl إلى "layout-direction-right-to-left". تعني ldltr "layout-direction-left-to-right" وهي القيمة الضمنية التلقائية.

يمكن أن ينطبق ذلك على أي مورد، مثل التصاميم أو العناصر القابلة للرسم أو القيم.

على سبيل المثال، إذا أردت توفير تخطيط معيّن للغة العربية وتخطيط عام لأي لغة أخرى "من اليمين إلى اليسار"، مثل الفارسية أو العبرية، يمكنك استخدام أدلة مثل ما يلي:

res/
layout/
main.xml (التنسيق التلقائي)
layout-ar/
main.xml (تنسيق محدّد للغة العربية)
layout-ldrtl/
main.xml (أي لغة من اليمين إلى اليسار باستثناء العربية، لأنّ مؤهّل اللغة "ar" له الأولوية)

ملاحظة: لتفعيل ميزات التنسيق من اليمين إلى اليسار في تطبيقك، يجب ضبط SupportsRtl على "true" وضبط TargetSdkVersion على 17 أو أعلى.

تمت إضافته في مستوى واجهة برمجة التطبيقات 17.

أصغر عرض

swdp

أمثلة:

sw320dp

sw600dp

sw720dp

إلخ

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

على سبيل المثال، إذا كان التصميم يتطلّب أن يكون أصغر بُعد لمساحة الشاشة 600 وحدة بكسل مستقلة عن الكثافة على الأقل في جميع الأوقات، يمكنك استخدام هذا المؤهِّل لإنشاء موارد التصميم في دليل res/layout-sw600dp/. لا يستخدم النظام هذه الموارد إلا عندما يكون أصغر بُعد للشاشة المتاحة 600 بكسل مستقل الكثافة على الأقل، بغض النظر عمّا إذا كان الجانب الذي يبلغ 600 بكسل مستقل الكثافة هو الارتفاع أو العرض الذي يراه المستخدم. يمكن أن يتغير أصغر عرض إذا تم تغيير حجم النافذة، ما يؤدي إلى تغيير العرض/الارتفاع المتاحَين، أو إذا تم تغيير موضعها، ما قد يؤدي إلى تغيير الحواف الداخلية للنظام.

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

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

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

في ما يلي بعض القيم التي يمكنك استخدامها هنا لأحجام الشاشات الشائعة:

  • ‫320، للأجهزة التي تتضمّن إعدادات شاشة مثل:
    • ‫240x320 نقطة لكل بوصة (هاتف QVGA)
    • ‫320×480 mdpi (هاتف محمول)
    • ‫480×800 hdpi (هاتف بكثافة عالية)
  • ‫480، للشاشات مثل 480x800 mdpi (جهاز لوحي/هاتف)
  • ‫600، للشاشات مثل 600x1024 mdpi (جهاز لوحي بحجم 7 بوصات)
  • ‫720، للشاشات مثل 720x1280 mdpi (كمبيوتر لوحي بحجم 10 بوصة)

عندما يوفّر تطبيقك أدلة موارد متعددة بقيم مختلفة للمحدّد smallestWidth، يستخدم النظام الدليل الأقرب إلى smallestWidth للجهاز (بدون تجاوزها).

تمت إضافته في مستوى واجهة برمجة التطبيقات 13.

اطّلِع أيضًا على السمة android:requiresSmallestWidthDp التي تحدّد الحد الأدنى من smallestWidth الذي يتوافق معه تطبيقك، وحقل الإعداد smallestScreenWidthDp الذي يتضمّن قيمة smallestWidth للجهاز.

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

العرض والارتفاع المتاحان

wdp

hdp

أمثلة:

w720dp

w1024dp

h720dp

h1024dp

إلخ

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

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

عندما يوفّر تطبيقك أدلة موارد متعددة بقيم مختلفة لعمليات الضبط هذه، يستخدم النظام الدليل الأقرب إلى عرض الشاشة الحالي للجهاز (بدون تجاوزه). يتم تحديد الأقرب إلى من خلال جمع الفروق بين عرض الشاشة الفعلي والعرض المحدّد إلى الفرق بين ارتفاع الشاشة الفعلي والارتفاع المحدّد، مع العلم أنّ الارتفاعات والعروض غير المحدّدة لها قيمة 0.

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

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

ملاحظة: يختار النظام المرجع الذي يتطابق مع العرض والارتفاع. لذلك، يُفضّل بشدة استخدام مصدر يحدّد كلا النوعين على استخدام مصدر يحدّد أحدهما فقط. على سبيل المثال، إذا كان عرض الشاشة الفعلي 720 وحدة بكسل مستقلة الكثافة وارتفاعها 1280 وحدة بكسل مستقلة الكثافة، وتم تحديد أحد الموارد باستخدام w720dp وتحديد مورد آخر باستخدام w700dp-h1200dp، سيتم اختيار المورد الأخير على الرغم من أنّ المورد الأول يطابق تمامًا ما يحدده.

تمت إضافته في مستوى واجهة برمجة التطبيقات 13.

اطّلِع أيضًا على حقلَي الإعداد screenWidthDp وscreenHeightDp اللذين يتضمّنان عرض الشاشة وارتفاعها الحاليَين.

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

حجم الشاشة

small

normal

large

xlarge
  • small: شاشات ذات حجم مشابه لشاشة QVGA منخفضة الكثافة يبلغ الحد الأدنى لحجم التصميم لشاشة صغيرة حوالي 320 × 426 وحدة بكسل مستقلة الكثافة. وتشمل الأمثلة QVGA منخفضة الكثافة وVGA عالية الكثافة.
  • ‫normal: الشاشات التي يكون حجمها مشابهًا لحجم شاشة HVGA متوسطة الكثافة الحد الأدنى لحجم التصميم للشاشة العادية هو 320×470 وحدة بكسل مستقلة الكثافة تقريبًا. وتتضمّن أمثلة هذه الشاشات شاشة WQVGA منخفضة الكثافة وشاشة HVGA متوسطة الكثافة وشاشة WVGA عالية الكثافة.
  • large: الشاشات التي لها حجم مشابه لشاشة VGA متوسطة الكثافة يبلغ الحد الأدنى لحجم التصميم على الشاشة الكبيرة 480x640 وحدة بكسل مستقلة الكثافة تقريبًا. وتشمل الأمثلة شاشات VGA وWVGA ذات الكثافة المتوسطة.
  • xlarge: شاشات أكبر بكثير من شاشة HVGA التقليدية ذات الكثافة المتوسطة الحد الأدنى لحجم التصميم لشاشة كبيرة جدًا هو 720×960 وحدة بكسل مستقلة الكثافة تقريبًا. في معظم الحالات، تكون الأجهزة ذات الشاشات الكبيرة جدًا كبيرة جدًا بحيث لا يمكن حملها في الجيب، ومن المرجّح أن تكون أجهزة على شكل جهاز لوحي. تمت إضافته في مستوى واجهة برمجة التطبيقات 9.

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

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

تمت إضافته في مستوى واجهة برمجة التطبيقات 4.

راجِع أيضًا حقل الإعداد screenLayout الذي يشير إلى ما إذا كانت الشاشة صغيرة أو عادية أو كبيرة.

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

نسبة عرض إلى ارتفاع الشاشة

long

notlong
  • long: الشاشات الطويلة، مثل WQVGA وWVGA وFWVGA
  • notlong: الشاشات غير الطويلة، مثل QVGA وHVGA وVGA

تمت إضافته في مستوى واجهة برمجة التطبيقات 4.

ويستند ذلك إلى نسبة العرض إلى الارتفاع في الشاشة (الشاشة ذات نسبة العرض إلى الارتفاع long تكون أعرض). لا يرتبط ذلك باتجاه الشاشة.

راجِع أيضًا حقل إعدادات screenLayout الذي يشير إلى ما إذا كانت الشاشة طويلة.

شاشة دائرية

round

notround
  • round: الشاشات الدائرية، مثل الأجهزة القابلة للارتداء الدائرية
  • ‫notround: الشاشات المستطيلة، مثل الهواتف أو الأجهزة اللوحية

تمت إضافته في المستوى 23 من واجهة برمجة التطبيقات

راجِع أيضًا طريقة ضبط isScreenRound التي تشير إلى ما إذا كانت الشاشة دائرية.

Wide Color Gamut

widecg

nowidecg
  • widecg: شاشات عرض ذات نطاق ألوان واسع، مثل Display P3 أو AdobeRGB
  • ‫nowidecg: الشاشات ذات نطاق الألوان الضيق، مثل sRGB

تمت إضافته في مستوى واجهة برمجة التطبيقات 26.

يمكنك أيضًا الاطّلاع على طريقة ضبط isScreenWideColorGamut التي تشير إلى ما إذا كانت الشاشة تتضمّن مجموعة ألوان واسعة.

نطاق عالي الديناميكية (HDR)

highdr

lowdr
  • ‫highdr: شاشات بنطاق عالي الديناميكية
  • lowdr: شاشات بنطاق ديناميكي منخفض/عادي

تمت إضافته في مستوى واجهة برمجة التطبيقات 26.

راجِع أيضًا طريقة الإعداد isScreenHdr التي تشير إلى ما إذا كانت الشاشة تتوافق مع تقنية HDR.

اتجاه الشاشة

port

land
  • ‫port: الجهاز في الوضع العمودي
  • ‫land: الجهاز في الوضع الأفقي

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

اطّلِع أيضًا على حقل الإعداد orientation الذي يشير إلى اتجاه الجهاز الحالي.

وضع واجهة المستخدم

car

desk

television

appliance

watch

vrheadset
  • ‫car: يتم عرض الجهاز في قاعدة تثبيت السيارة
  • desk: يتم عرض الجهاز في قاعدة شحن على المكتب
  • ‫television: يعرض الجهاز المحتوى على تلفزيون، ما يوفّر تجربة "من مسافة بعيدة" حيث تظهر واجهة المستخدم على شاشة كبيرة بعيدة عن المستخدم، وتكون التجربة موجّهة بشكل أساسي نحو لوحة الاتجاهات أو التفاعل غير المستند إلى المؤشر
  • ‫appliance: الجهاز يعمل كأداة منزلية بدون شاشة
  • ‫watch: الجهاز مزوّد بشاشة ويتم ارتداؤه على المعصم
  • ‫vrheadset: يتم عرض الجهاز في سماعة رأس مزوّدة بتقنية الواقع الافتراضي

تمت إضافة هذه الفئات في المستوى 8 من واجهة برمجة التطبيقات، وتمت إضافة التلفزيون في المستوى 13، والأجهزة المنزلية في المستوى 16، والساعات في المستوى 20، وسماعات الواقع الافتراضي في المستوى 26.

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

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

الوضع الليلي

night

notnight
  • ‫night: وقت الليل
  • ‫notnight: وقت النهار

تمت إضافته في مستوى واجهة برمجة التطبيقات 8.

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

كثافة البكسل على الشاشة (نقطة لكل بوصة)

ldpi

mdpi

hdpi

xhdpi

xxhdpi

xxxhdpi

nodpi

tvdpi

anydpi

nnndpi
  • ldpi: شاشات منخفضة الكثافة؛ حوالي 120 نقطة لكل بوصة
  • ‫mdpi: شاشات متوسطة الكثافة (على شاشات HVGA التقليدية)؛ تبلغ حوالي 160 نقطة لكل بوصة.
  • ‫hdpi: شاشات عالية الكثافة؛ حوالي 240 نقطة لكل بوصة
  • ‫xhdpi: شاشات عالية الكثافة جدًا؛ حوالي 320 نقطة لكل بوصة تمت إضافته في مستوى واجهة برمجة التطبيقات 8.
  • ‫xxhdpi: شاشات عالية الكثافة للغاية، تبلغ دقتها حوالي 480 نقطة لكل بوصة. تمت إضافته في مستوى واجهة برمجة التطبيقات 16.
  • xxxhdpi: تستخدم الكثافة العالية جدًا جدًا جدًا (رمز مشغّل التطبيقات فقط، راجِع توافُق التطبيق مع كثافات البكسل المختلفة)؛ تبلغ حوالي 640 نقطة لكل بوصة. تمت إضافته في مستوى واجهة برمجة التطبيقات 18.
  • ‫nodpi: تُستخدَم لموارد الصور النقطية التي لا تريد تغيير حجمها لتتطابق مع كثافة الجهاز.
  • ‫tvdpi: شاشات تقع في مكان ما بين mdpi وhdpi، أي حوالي 213 نقطة في البوصة. لا تُعدّ هذه المجموعة مجموعة كثافة "أساسية". وهي مخصّصة في الغالب لأجهزة التلفزيون بدقة 720p، ولا تحتاج إليها معظم التطبيقات. بالنسبة إلى لوحات التلفزيون بدقة 1080p، استخدِم xhdpi، وبالنسبة إلى لوحات التلفزيون بدقة 4K، استخدِم xxxhdpi. تمت إضافته في مستوى واجهة برمجة التطبيقات 13.
  • ‫anydpi: تطابق جميع قيم كثافة الشاشة ولها الأولوية على المؤهِّلات الأخرى. ويكون ذلك مفيدًا لرسومات المتجهات القابلة للرسم. تمت إضافته في مستوى واجهة برمجة التطبيقات 21.
  • ‫nnndpi: تُستخدَم لتمثيل الكثافات غير العادية، حيث يمثّل nnn كثافة الشاشة كعدد صحيح موجب. لا يتم استخدام هذا في معظم الحالات. يؤدي استخدام حِزم الكثافة العادية إلى تقليل النفقات العامة اللازمة لتوفير التوافق مع كثافات شاشات الأجهزة المختلفة المتوفرة في السوق بشكل كبير.

هناك نسبة تحجيم 3:4:6:8:12:16 بين الكثافات الأساسية الست (مع تجاهل الكثافة tvdpi). وبالتالي، فإنّ صورة نقطية بمقاس 9×9 في ldpi تكون بمقاس 12×12 في mdpi، و18×18 في hdpi، و24×24 في xhdpi، وهكذا.

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

لمزيد من المعلومات حول كيفية التعامل مع كثافات الشاشة المختلفة وكيفية تغيير Android لحجم الصور النقطية لتناسب الكثافة الحالية، يُرجى الاطّلاع على نظرة عامة حول توافق الشاشة.

نوع شاشة اللمس

notouch

finger
  • ‫notouch: الجهاز لا يتضمّن شاشة تعمل باللمس.
  • ‫finger: الجهاز مزوّد بشاشة تعمل باللمس ومخصّصة للاستخدام من خلال التفاعل المباشر بإصبع المستخدم.

اطّلِع أيضًا على حقل الإعداد touchscreen الذي يشير إلى نوع الشاشة التي تعمل باللمس على الجهاز.

مدى توفّر لوحة المفاتيح

keysexposed

keyshidden

keyssoft
  • ‫keysexposed: يتوفّر للجهاز لوحة مفاتيح. إذا كانت لوحة المفاتيح الافتراضية مفعّلة على الجهاز (وهو أمر محتمل)، سيتم استخدامها حتى عندما لا تظهر لوحة المفاتيح الخارجية للمستخدم أو عندما لا يتضمّن الجهاز لوحة مفاتيح خارجية. إذا لم يتم توفير لوحة مفاتيح افتراضية أو تم إيقافها، فلن يتم استخدام هذا الخيار إلا عند توفير لوحة مفاتيح أجهزة.
  • ‫keyshidden: يتوفّر للجهاز لوحة مفاتيح خارجية ولكنّها مخفية و الجهاز لا يتضمّن لوحة مفاتيح افتراضية مفعَّلة.
  • ‫keyssoft: تم تفعيل لوحة مفاتيح افتراضية على الجهاز، سواء كانت ظاهرة أم لا.

إذا قدّمت موارد keysexposed، ولكن ليس موارد keyssoft، سيستخدم النظام موارد keysexposed بغض النظر عمّا إذا كانت لوحة المفاتيح مرئية، طالما أنّ لوحة مفاتيح افتراضية مفعّلة في النظام.

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

اطّلِع أيضًا على حقلَي الإعداد hardKeyboardHidden وkeyboardHidden، اللذين يشيران إلى إمكانية ظهور لوحة مفاتيح خارجية وإمكانية ظهور أي نوع من لوحات المفاتيح (بما في ذلك لوحة المفاتيح البرمجية)، على التوالي.

طريقة إدخال النص الأساسية

nokeys

qwerty

12key
  • ‫nokeys: الجهاز لا يتضمّن مفاتيح أجهزة لإدخال النص.
  • ‫qwerty: يشير إلى أنّ الجهاز يتضمّن لوحة مفاتيح QWERTY مدمجة، سواء كانت مرئية للمستخدم أم لا.
  • ‫12key: يشير إلى أنّ الجهاز يتضمّن لوحة مفاتيح مكوّنة من 12 مفتاحًا، سواء كانت مرئية للمستخدم أم لا.

يمكنك أيضًا الاطّلاع على حقل الإعداد keyboard الذي يشير إلى طريقة إدخال النص الأساسية المتاحة.

مدى توفّر مفتاح التنقّل

navexposed

navhidden
  • ‫navexposed: مفاتيح التنقل متاحة للمستخدم.
  • ‫navhidden: مفاتيح التنقّل غير متاحة (مثلما يحدث عند إغلاق الغطاء).

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

راجِع أيضًا حقل الإعداد navigationHidden الذي يشير إلى ما إذا كانت مفاتيح التنقّل مخفية.

طريقة التنقّل الأساسية غير المستندة إلى اللمس

nonav

dpad

trackball

wheel
  • ‫nonav: لا يتضمّن الجهاز أي وسيلة تنقّل أخرى غير استخدام الشاشة التي تعمل باللمس.
  • ‫dpad: يتضمّن الجهاز لوحة تحكّم (D-pad) للتنقّل.
  • ‫trackball: الجهاز مزوّد بكرة تتبُّع للتنقّل.
  • ‫wheel: الجهاز مزوّد بعجلات توجيه للتنقّل (غير شائع).

راجِع أيضًا حقل الإعداد navigation الذي يشير إلى نوع طريقة التنقّل المتاحة.

إصدار النظام الأساسي (مستوى واجهة برمجة التطبيقات)

أمثلة:

v3

v4

v7

إلخ

مستوى واجهة برمجة التطبيقات المتوافق مع الجهاز على سبيل المثال، v1 للمستوى 1 من واجهة برمجة التطبيقات (الأجهزة التي تعمل بالإصدار 1.0 من نظام التشغيل Android أو الإصدارات الأحدث) وv4 للمستوى 4 من واجهة برمجة التطبيقات (الأجهزة التي تعمل بالإصدار 1.6 من نظام التشغيل Android أو الإصدارات الأحدث). لمزيد من المعلومات حول هذه القيم، يُرجى الاطّلاع على مستند مستويات واجهة برمجة التطبيقات في Android.

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

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

  • يمكنك تحديد مؤهلات متعددة لمجموعة واحدة من الموارد، مع الفصل بينها بشرطات. على سبيل المثال، ينطبق 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 الموارد التلقائية المناسبة، وهي مجموعة الموارد الخاصة بنوع معيّن من الموارد لا يتضمّن محدّدات إعدادات.

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

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

على سبيل المثال، لنفترض أنّ لديك رمز تطبيق، 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

لإنشاء اسم مستعار لعنصر قابل للرسم حالي، استخدِم العنصر <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.

الوصول إلى موارد تطبيقك

بعد توفير مرجع في تطبيقك، يمكنك تطبيقه من خلال الإشارة إلى رقم تعريف المرجع. يتم تحديد جميع معرّفات الموارد في الفئة 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:

Kotlin

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

Java

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.

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

Kotlin

// 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)

Java

// 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);

الوصول إلى الموارد من 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 الخاصة بالنمط كقيمة android:textColor في هذه الأداة. بما أنّ أداة موارد النظام تعرف أنّه من المتوقّع توفّر مورد سمة في هذا السياق، لن تحتاج إلى تحديد النوع بشكل صريح، وهو ?android:attr/textColorSecondary. يمكنك استبعاد النوع attr.

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

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

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

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

الوصول إلى مراجع المنصة

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

Kotlin

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

Java

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 العثور على أفضل تطابق بين كثافات الشاشة البديلة وتغيير حجم الصور النقطية حسب الحاجة. ومع ذلك، للحصول على أفضل تجربة على جميع أنواع الأجهزة، يجب توفير رسومات قابلة للرسم بديلة لجميع أنواع الكثافة الثلاثة.