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

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

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

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

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

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

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

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/ موارد متعددة. بالنسبة إلى أحد الملفات في هذا الدليل، يحدد كل عنصر ثانوي للعنصر <resources> موردًا واحدًا. على سبيل المثال، ينشئ العنصر <string> مورد R.string وينشئ العنصر <color> مورد R.color.

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

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

xml/ ملفات XML عشوائية يمكن قراءتها في وقت التشغيل من خلال طلب البيانات من Resources.getXML() يجب حفظ ملفات ضبط XML المتنوعة هنا، مثل إعدادات البحث.
font/ ملفات الخطوط التي تتضمّن إضافات، مثل ملفات TTF أو OTF أو TTC أو XML التي تتضمّن عنصر <font-family> لمزيد من المعلومات حول الخطوط كموارد، يُرجى الاطّلاع على إضافة خط كمورد XML.

تنبيه: يجب عدم حفظ ملفات الموارد مطلقًا داخل الدليل 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. أسماء مؤهلات التهيئة.

الإعدادات قيم المؤهِّل الوصف
مركز عملائي وحساب MNC أمثلة:
mcc310
mcc310-mnc004
mcc208-mnc00

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

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

يمكنك أيضًا استخدام "مركز عملائي" وحده، على سبيل المثال، لتضمين الموارد القانونية الخاصة ببلد معيّن في تطبيقك. وإذا كنت بحاجة إلى التحديد استنادًا إلى اللغة فقط، استخدِم مؤهل اللغة والنص البرمجي (اختياري) والمنطقة (اختياري) بدلاً من ذلك. وإذا كنت تستخدم مؤهِّل "مركز عملائي" و"مؤهِّل الطب العام" (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-1 ويليه رمز المنطقة ISO 3166-1-alpha-2 المكوَّن من حرفَين (يُسبق له رمز r بأحرف صغيرة).

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

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

لاستخدام علامة لغة BCP 47، اربط رمز اللغة b+ ورمز اللغة ISO 639-1 المكوّن من حرفَين، ويمكنك اختياريًا إضافة علامات فرعية إضافية مفصولة بفواصل +.

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

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

اطّلِع أيضًا على الطريقة getLocales() التي توفّر قائمة محدّدة باللغات. تشمل هذه القائمة اللغة الرئيسية.

اتجاه التصميم ldrtl
ldltr

اتجاه تنسيق تطبيقك. ويعني ldrtl "تنسيق الاتجاه من اليمين إلى اليسار". تعني السمة ldltr "تنسيق الاتجاه من اليسار إلى اليمين" وهو القيمة الضمنية التلقائية.

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

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

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

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

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

أصغر عرض sw<N>dp

أمثلة:
sw320dp
sw600dp
sw720dp
وما إلى ذلك.

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

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

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

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

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

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

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

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

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

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

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

العرض والارتفاع المتاحان w<N>dp
h<N>dp

أمثلة:
w720dp
w1024dp
h720dp
h1024dp
وما إلى ذلك.

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

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

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

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

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

ملاحظة: يختار النظام المورد الذي يتطابق مع كلٍّ من العرض والارتفاع. لذلك، يُفضَّل استخدام المورد الذي يحدد كلا النوعين على حدة على مورد يحدد أحدهما فقط. على سبيل المثال، إذا كان عرض الشاشة الفعلية 720 بكسل مستقل الكثافة × 1280 بكسل مستقل الكثافة، وكان أحد الموارد مؤهَّلاً باستخدام w720dp وكان مورد آخر مؤهّلاً على هذا النحو، يتم اختيار المورد الثاني حتى لو كان الخيار الأول مطابقًا تمامًا لما يشير إليه.

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

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

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

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

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

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

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

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

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

جانب الشاشة long
notlong
  • long: الشاشات الطويلة، مثل WQVGA وWVGA وFWVGA
  • notlong: ليست شاشات طويلة، مثل QVGA وHVGA وVGA

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

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

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

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

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

يمكنك أيضًا الاطّلاع على طريقة الإعداد isScreenRound() التي تشير إلى ما إذا كانت الشاشة دائرية.

مجموعة ألوان واسعة 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، وتمّت إضافة الساعة في واجهة برمجة التطبيقات 20.

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

ويمكن أن يتغيّر هذا الإعداد خلال فترة استخدام التطبيق إذا وضع المستخدم الجهاز في قاعدة إرساء. ويمكنك تفعيل بعض هذه الأوضاع أو إيقافها باستخدام 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 نقطة لكل بوصة. ولا تعتبر هذه مجموعة كثافة "أساسية". وهو مُعد للاستخدام في الغالب للتلفزيونات بدقة 720 بكسل، ومعظم التطبيقات لا تحتاج إليه. بالنسبة إلى لوحات التلفزيون بدقة 1080p، استخدِم xhdpi، واستخدِم لوحات التلفزيون بدقة 4K xxxhdpi. تمّت الإضافة في المستوى 13 من واجهة برمجة التطبيقات.
  • anydpi: يتطابق مع جميع كثافات الشاشة ويكون له الأولوية على المؤهِّلات الأخرى. وهذا مفيد بالنسبة إلى المتجهات القابلة للرسم. تمّت الإضافة في المستوى 21 من واجهة برمجة التطبيقات.
  • nnndpi: تُستخدَم هذه السمة لتمثيل كثافة غير عادية، حيث تمثّل nnn كثافة شاشة عددًا صحيحًا موجبًا. ولا يتم استخدام هذه الطريقة في معظم الحالات. ويقلل استخدام مجموعات بيانات الكثافة العادية بشكل كبير من عبء استخدام كثافات شاشات الأجهزة المختلفة في السوق.

هناك نسبة تحجيم 3:4:6:8:12:16 بين الكثافة الأساسية الست (مع تجاهل كثافة tvdpi). إذًا، تكون الصورة النقطية بحجم 9×9 في ldpi هي 12x12 بmdpi، و18x18 بالدقة في البوصة، و24x24 في 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 الذي يشير إلى توفّر أسلوب إدخال النص الأساسي.

إصدار النظام الأساسي (مستوى واجهة برمجة التطبيقات) أمثلة:
v3
v4
v7
وما إلى ذلك.

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

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

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

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

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

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

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

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

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

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

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

قابلة للرسم

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

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

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

التنسيق

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

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

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello</string>
    <string name="hi">@string/hello</string>
</resources>

أصبح مورد R.string.hi الآن اسمًا مستعارًا لـ R.string.hello.

تعمل القيم البسيطة الأخرى بنفس الطريقة، مثل الألوان:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="red">#f00</color>
    <color name="highlight">@color/red</color>
</resources>

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

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

عند تجميع تطبيقك، ينشئ aapt الفئة R التي تحتوي على معرّفات الموارد لجميع الموارد في دليل res/. لكل نوع من الموارد، هناك فئة فرعية R، مثل R.drawable لجميع الموارد القابلة للرسم. ولكل مورد من هذا النوع، هناك عدد صحيح ثابت، على سبيل المثال، R.drawable.icon. هذا العدد الصحيح هو معرف المورد الذي يمكنك استخدامه لاسترداد موردك.

على الرغم من أنّ الفئة R هي المكان الذي يتم فيه تحديد معرّفات الموارد، لن تحتاج إلى البحث فيها لاكتشاف معرّف المورد. يتكون معرف المورد دائمًا مما يلي:

  • نوع المورد: يتم تجميع كل مورد في "نوع"، مثل string وdrawable وlayout. لمزيد من المعلومات عن الأنواع المختلفة، يُرجى الاطِّلاع على نظرة عامة على أنواع الموارد.
  • اسم المورد، وهو إما اسم الملف باستثناء الامتداد أو القيمة في سمة android:name بتنسيق XML، إذا كان المورد قيمة بسيطة، مثل سلسلة

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

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

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

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

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

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

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

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

تحذير: لا تعدِّل ملف 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:

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

على سبيل المثال، إذا تم ضبط 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.