סקירה כללית של משאבי האפליקציה

משאבים הם הקבצים הנוספים והתוכן הסטטי שבהם הקוד משתמש, כמו מפות סיביות, מחרוזות של ממשק המשתמש, הוראות לאנימציה ועוד.

כדאי תמיד להוציא את משאבי האפליקציה כמו תמונות ומחרוזות מהקוד, כדי שתוכלו לנהל אותם בנפרד. בנוסף, אפשר לספק משאבים חלופיים להגדרות ספציפיות של מכשירים על ידי קיבוץ שלהם בספריות משאבים עם שמות מיוחדים. בזמן הריצה, מערכת Android משתמשת במשאב המתאים על סמך ההגדרה הנוכחית. לדוגמה, יכול להיות שתרצו לספק מחרוזות שונות בהתאם להגדרת השפה.

אחרי שמוציאים את משאבי האפליקציה החוצה, אפשר לגשת אליהם באמצעות מזהי משאבים שנוצרים במחלקה R של הפרויקט. במאמר הזה מוסבר איך לקבץ את המשאבים בפרויקט Android. בנוסף, מוסבר שם איך לספק משאבים חלופיים להגדרות ספציפיות של מכשירים, ואז לגשת אליהם מקוד האפליקציה או מקובצי XML אחרים.

סוגי משאבים של קבוצות

ממקמים כל סוג של משאב בספריית משנה ספציפית של הספרייה res/ של הפרויקט. לדוגמה, היררכיית הקבצים של פרויקט פשוט:

MyProject/
    src/
        MyActivity.kt
    res/
        drawable/
            graphic.png
        mipmap/
            icon.png
        values/
            strings.xml

הספרייה res/ מכילה את כל המשאבים בספריות המשנה שלה: משאב תמונה, ספרייה mipmap/ לסמלי אפליקציה וקובץ משאבי מחרוזות. שמות ספריות המשאבים חשובים ומתוארים בטבלה 1.

הערה: מידע נוסף על השימוש בתיקיות mipmap זמין במאמר הוספת סמלי אפליקציות לספריות mipmap.

טבלה 1. ספריות משאבים שנתמכות בתוך ספריית הפרויקט res/.

ספרייה Resource Type
drawable/

קבצי Bitmap ‏ (PNG,‏ .9.png,‏ JPG או GIF) או קובצי XML שעברו קומפילציה לסוגי משנה של משאבי drawable:

  • קובצי מפת סיביות
  • תמונות 9-patch (מפות סיביות שניתן לשנות את הגודל שלהן)
  • רשימות של מדינות
  • צורות
  • נכסי אנימציה מסוג drawable
  • רכיבים אחרים שאפשר לצייר

מידע נוסף זמין במאמר משאבים מסוג Drawable.

mipmap/ קבצים של רכיבי ציור לצפיפויות שונות של סמלי מרכז האפליקציות. מידע נוסף על ניהול סמלים של מרכז האפליקציות באמצעות תיקיות mipmap/ זמין במאמר העברת סמלי אפליקציות לתיקיות mipmap.
raw/

קבצים שרירותיים לשמירה בפורמט גולמי. כדי לפתוח את המשאבים האלה עם InputStreamraw, צריך להתקשר אל 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 ידרשו סוגים שונים של משאבים.

לדוגמה, אתם יכולים לספק משאבי מחרוזות שונים שמתרגמים את הטקסט בממשק המשתמש על סמך הגדרת השפה במכשיר.

הערה: ב-Compose, ממשקי המשתמש, האנימציות והצבעים מבוססי-המצב מוצהרים ב-Kotlin, ולכן הספריות layout/, menu/, anim/, animator/ ו-color/ כבר לא רלוונטיות לאפליקציות מודרניות. מידע נוסף זמין במאמרים אנימציות ב-Compose וממה מורכב עיצוב ב-Compose.

לספק משאבים חלופיים

רוב האפליקציות מספקות משאבים חלופיים לתמיכה בהגדרות ספציפיות של מכשירים. לדוגמה, כדאי לכלול משאבי drawable חלופיים לצפיפויות מסך שונות ומשאבי מחרוזות חלופיים לשפות שונות. בזמן הריצה, מערכת Android מזהה את תצורת המכשיר הנוכחית וטוענת את המשאבים המתאימים לאפליקציה.

כדי לציין חלופות ספציפיות להגדרות עבור קבוצת משאבים:

  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. שמות של מחרוזות להגדרת תצורה.

הגדרות אישיות ערכי מגדיר תיאור
קוד MCC וקוד MNC דוגמאות:
mcc310
mcc310-mnc004
mcc208-mnc00

קוד מדינה של רשת סלולרית (MCC), שאחריו יכול להופיע קוד הרשת הסלולרית (MNC) מכרטיס ה-SIM במכשיר. לדוגמה, mcc310 היא ארה"ב בכל ספק, mcc310-mnc004 היא ארה"ב ב-Verizon, ו-mcc208-mnc00 היא צרפת ב-Orange.

אם המכשיר משתמש בחיבור רדיו (כלומר, זה טלפון GSM), ערכי ה-MCC וה-MNC מגיעים מכרטיס ה-SIM.

אפשר גם להשתמש רק ב-MCC, למשל כדי לכלול באפליקציה משאבים משפטיים שספציפיים למדינה. אם אתם צריכים לציין לפי שפה בלבד, אתם יכולים להשתמש במקום זאת במאפיין המסווג שפה, סקריפט (אופציונלי) ואזור (אופציונלי). אם אתם משתמשים בחשבון ניהול (MCC) ובמספר הנייד של החברה (MNC) כמזהה, עליכם לעשות זאת בזהירות ולבדוק שהם פועלים כמצופה.

אפשר גם לראות את שדות ההגדרה mcc ו-mnc, שמציינים את קוד המדינה של רשת סלולרית ואת קוד הרשת הסלולרית (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).

הקודים לא תלויי אותיות רישיות (case-sensitive). הקידומת r משמשת להפרדה בין חלקי האזור. אי אפשר לציין רק אזור.

ב-Android 7.0 (רמת API ‏24) הוספנו תמיכה בתגי שפה של BCP 47, שאפשר להשתמש בהם כדי לציין משאבים שספציפיים לשפה ולאזור. תג שפה מורכב מרצף של תגי משנה אחד או יותר, וכל אחד מהם מצמצם או משפר את טווח השפה שמזוהה על ידי התג הכולל. מידע נוסף על תגי שפה זמין במאמר תגים לזיהוי שפות.

כדי להשתמש בתג שפה לפי BCP 47, צריך לשרשר את b+ ואת קוד השפה בן שתי האותיות ISO 639-1, ואפשר להוסיף אחריו תגי משנה נוספים שמופרדים באמצעות +.

תג השפה יכול להשתנות במהלך השימוש באפליקציה אם המשתמשים משנים את השפה שלהם בהגדרות המערכת. מידע על ההשפעה של השינוי הזה על האפליקציה במהלך זמן הריצה זמין במאמר טיפול בשינויים בהגדרות.

מדריך מלא להתאמת האפליקציה לשפות אחרות זמין במאמר התאמת האפליקציה לשוק המקומי.

אפשר גם לעיין ב-method‏ getLocales, שמספק את רשימת הלוקאלים המוגדרת. הרשימה הזו כוללת את הלוקאל הראשי.

לשון הפנייה masculine
feminine
neuter

המגדר הדקדוקי של המשתמש. משמש לשפות שיש בהן מגדר דקדוקי.

לדוגמה, אם אתם צריכים לספק משאבים שונים למשתמשים דוברי צרפתית, אתם יכולים להשתמש בספריות כמו אלה:

res/
  values-fr/
    strings.xml (מחרוזות ברירת מחדל ללא ציון מגדר)
  values-fr-masculine/
    strings.xml (מחרוזות עם מגדר זכר)
  values-fr-feminine/
    strings.xml (מחרוזות עם מגדר נקבה)
  values-fr-neuter/
    strings.xml (מחרוזות עם מגדר ניטרלי)

איך מתאימים אישית את ממשק המשתמש של האפליקציה באמצעות מגדר דקדוקי

אפשר גם לעיין בשיטת ההגדרה getGrammaticalGender, שבה מצוין המגדר הדקדוקי.

נוסף ברמת API‏ 34.

Wide Color Gamut widecg
nowidecg
  • widecg: מסכים עם מכלול רחב של צבעים, כמו Display P3 או AdobeRGB
  • nowidecg: מסכים עם סולם צבעים צר כמו sRGB

נוסף ברמת API‏ 26.

אפשר גם לעיין בשיטת ההגדרה isScreenWideColorGamut כדי לדעת אם המסך כולל מגוון רחב של צבעים.

טווח דינמי גבוה (HDR) highdr
lowdr
  • highdr: מסכים עם טווח דינמי גבוה
  • lowdr: תצוגה עם טווח דינמי נמוך או רגיל

נוסף ברמת API‏ 26.

אפשר גם לעיין בשיטת ההגדרה של isScreenHdr, שבה מצוין אם המסך תומך ב-HDR.

מצב ממשק המשתמש car
desk
television
appliance
watch
vrheadset
  • car: המכשיר מוצג במחבר לרכב
  • desk: המכשיר מוצג במעמד שולחני
  • television: המכשיר מוצג בטלוויזיה, ומספק חוויה של 'עשרה פיט' שבה ממשק המשתמש מוצג על מסך גדול שהמשתמש נמצא רחוק ממנו, והחוויה מבוססת בעיקר על אינטראקציה באמצעות כפתורי החיצים (D-pad) או אמצעי ניווט אחרים שאינם מצביעים
  • appliance: המכשיר משמש כמכשיר ביתי, ללא מסך
  • watch: למכשיר יש תצוגה והוא נלבש על פרק כף היד
  • vrheadset: המכשיר מוצג במשקפי מציאות מדומה

נוסף ברמת API‏ 8; טלוויזיה נוספה ב-API‏ 13; מכשיר ביתי נוסף ב-API‏ 16; שעון נוסף ב-API‏ 20; משקפי VR נוספו ב-API‏ 26.

מידע על האופן שבו האפליקציה יכולה להגיב כשמכניסים את המכשיר לאביזר עגינה או מוציאים אותו ממנו זמין במאמר קביעה ומעקב של מצב העגינה והסוג שלה.

הערך הזה יכול להשתנות במהלך השימוש באפליקציה אם המשתמש מניח את המכשיר במעמד. אפשר להפעיל או להשבית חלק מהמצבים האלה באמצעות UiModeManager. מידע על ההשפעה של השינוי הזה על האפליקציה במהלך זמן הריצה זמין במאמר בנושא טיפול בשינויים בהגדרות.

מצב לילה night
notnight
  • night: בלילה
  • notnight: שעות היום

נוסף ברמת API‏ 8.

ההגדרה הזו יכולה להשתנות במהלך השימוש באפליקציה אם מצב הלילה מוגדר למצב אוטומטי (ברירת מחדל). במקרה כזה, המצב משתנה בהתאם לשעה ביום. אפשר להפעיל או להשבית את המצב הזה באמצעות UiModeManager. מידע על ההשפעה של השינוי הזה על האפליקציה במהלך זמן הריצה זמין במאמר בנושא טיפול בשינויים בהגדרות.

צפיפות פיקסלים במסך (dpi) ldpi
mdpi
hdpi
xhdpi
xxhdpi
xxxhdpi
nodpi
tvdpi
anydpi
nnndpi
  • ldpi: מסכים עם צפיפות פיקסלים נמוכה; בערך ‎120 dpi.
  • mdpi: מסכים עם צפיפות בינונית (ב-HVGA מסורתי); בערך 160 dpi.
  • hdpi: מסכים עם צפיפות פיקסלים גבוהה; בערך 240 dpi.
  • xhdpi: מסכים עם צפיפות גבוהה במיוחד; בערך 320 dpi. נוסף ברמת API‏ 8.
  • xxhdpi: מסכים עם צפיפות גבוהה במיוחד; בערך 480 dpi. נוסף ברמת API‏ 16.
  • xxxhdpi: שימוש בצפיפות גבוהה במיוחד (רק בסמל של מרכז האפליקציות – ראו תמיכה בצפיפויות פיקסלים שונות); בערך 640 dpi. נוסף ברמת API‏ 18.
  • nodpi: משמש למשאבי מפת סיביות שלא רוצים לשנות את הגודל שלהם כדי להתאים לצפיפות הפיקסלים של המכשיר.
  • tvdpi: מסכים ברזולוציה שבין mdpi ל-hdpi; בערך ‎213 dpi. הקבוצה הזו לא נחשבת לקבוצת צפיפות 'ראשונית'. הוא מיועד בעיקר לטלוויזיות באיכות 720p, ורוב האפליקציות לא צריכות אותו. במסכי טלוויזיה של 1080p משתמשים ב-xhdpi, ובמסכי טלוויזיה של 4K משתמשים ב-xxxhdpi. נוסף ברמת API‏ 13.
  • anydpi: מתאים לכל ערכי הדחיסות של המסך וקודם למסננים אחרים. האפשרות הזו שימושית לפריטים גרפיים וקטוריים שניתנים לשרטוט. נוסף ברמת API‏ 21.
  • nnndpi: משמש לייצוג צפיפויות לא תקניות, כאשר nnn הוא מספר שלם חיובי של צפיפות המסך. ברוב המקרים לא משתמשים בזה. השימוש בדליים סטנדרטיים של צפיפות מפחית באופן משמעותי את התקורה של תמיכה בצפיפויות המסך השונות של המכשירים בשוק.

יש יחס קנה מידה של 3:4:6:8:12:16 בין שש הצפיפויות העיקריות (אם מתעלמים מהצפיפות tvdpi). לכן, מפת סיביות בגודל 9x9 ב-ldpi היא 12x12 ב-mdpi,‏ 18x18 ב-hdpi,‏ 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, שבו מצוינת שיטת הזנת הטקסט העיקרית שזמינה.

גרסת פלטפורמה (רמת API) דוגמאות:
v3
v4
v7
וכו'.

רמת ה-API שנתמכת על ידי המכשיר. לדוגמה, v1 לרמת API‏ 1 (מכשירים עם Android 1.0 ומעלה) ו-v4 לרמת API‏ 4 (מכשירים עם Android 1.6 ומעלה). מידע נוסף על הערכים האלה זמין במאמר רמות Android API.

הערה: לא כל הגרסאות של Android תומכות בכל התנאים. שימוש במגדיר חדש מוסיף באופן מרומז את מגדיר גרסת הפלטפורמה, כדי שמכשירים ישנים יותר יוכלו להתעלם ממנו. כדי להימנע מבעיות, תמיד כדאי לכלול קבוצה של משאבים שמוגדרים כברירת מחדל (קבוצת משאבים ללא מאפיינים). מידע נוסף זמין בקטע בנושא מתן תאימות מיטבית של מכשירים באמצעות משאבים.

באפליקציות Compose, לא צריך להשתמש במגדירי תצורה שקשורים לפריסה ולמידות. הם עדיין קיימים, אבל לא נכללים בטבלה 2. המסננים האלה כוללים: כיוון הפריסה, הרוחב הקטן ביותר, הרוחב הזמין, הגובה הזמין, גודל המסך, יחס הגובה-רוחב של המסך, מסך עגול וכיוון המסך. טבלה מלאה של מסנני הגדרה לפי סדר עדיפות מופיעה במאמר סקירה כללית של משאבי אפליקציות (תצוגות).

כללים לשמות של מגדירים

אלה כמה כללים לגבי השימוש בשמות של מסווגי תצורה:

  • אפשר לציין כמה מסננים לקבוצת משאבים אחת, ולהפריד ביניהם באמצעות מקפים. לדוגמה, drawable-en-rUS-night חל על מכשירים באנגלית (ארה"ב) במצב לילה.
  • המסננים צריכים להיות בסדר שמופיע בטבלה 2.
    • שגוי: drawable-hdpi-night/
    • נכון: drawable-night-hdpi/
  • אי אפשר להטמיע ספריות משאבים חלופיות בתוך ספריות אחרות. לדוגמה, אי אפשר להשתמש ב- res/drawable/drawable-en/.
  • הערכים לא תלויי-רישיות. מהדר המשאבים ממיר את שמות הספריות לאותיות קטנות לפני העיבוד, כדי למנוע בעיות במערכות קבצים שלא מבחינות בין אותיות רישיות לאותיות קטנות. השימוש באותיות רישיות בשמות הוא רק כדי לשפר את הקריאות.
  • המערכת תומכת רק בערך אחד לכל סוג של תנאי. לדוגמה, אם רוצים להשתמש באותם קבצים של drawable בספרד ובצרפת, אי אפשר ליצור ספרייה בשם drawable-es-fr/. במקום זאת, צריך שיהיו שתי ספריות משאבים, כמו drawable-es/ ו-drawable-fr/, שמכילות את הקבצים המתאימים.

אחרי ששומרים משאבים חלופיים בספריות ששמן כולל את המאפיינים האלה, מערכת Android מחילה באופן אוטומטי את המשאבים באפליקציה על סמך התצורה הנוכחית של המכשיר. בכל פעם שמבוקש משאב, מערכת Android מחפשת ספריות משאבים חלופיות שמכילות את קובץ המשאב המבוקש, ואז מוצאת את המשאב שהכי מתאים.

אם אין משאבים חלופיים שתואמים להגדרת מכשיר מסוימת, מערכת Android משתמשת במשאבים המתאימים שמוגדרים כברירת מחדל – קבוצת המשאבים של סוג משאב מסוים שלא כוללת מסווג הגדרה.

יצירת משאבים של כתובות אימייל חלופיות

אם יש לכם משאב שאתם רוצים להשתמש בו ביותר מהגדרת מכשיר אחת, אבל אתם לא רוצים לספק אותו כמשאב ברירת מחדל, אתם לא צריכים להוסיף את אותו משאב ליותר מספריית משאבים חלופית אחת. במקום זאת, אתם יכולים ליצור משאב חלופי שמשמש ככינוי למשאב שנשמר בספריית המשאבים שמוגדרת כברירת מחדל.

Drawables

לדוגמה, נניח שיש לכם סמל אפליקציה, icon.png, ואתם צריכים גרסה ייחודית שלו ללוקאלים שונים. עם זאת, שני לוקאלים, אנגלית קנדית וצרפתית קנדית, צריכים להשתמש באותה גרסה. אין צורך להעתיק את אותה תמונה לספריית המשאבים גם עבור אנגלית קנדית וגם עבור צרפתית קנדית. במקום זאת, אפשר לשמור את התמונה שמשמשת לשניהם בכל שם חוץ מ icon.png, כמו icon_ca.png, ולשים אותה בספרייה res/drawable/ שמוגדרת כברירת מחדל. לאחר מכן יוצרים קובץ icon.xml בתיקייה res/drawable-en-rCA/ ובתיקייה res/drawable-fr-rCA/ שמפנה למשאב icon_ca.png באמצעות הרכיב <bitmap>.

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

כך אפשר לאחסן רק גרסה אחת של קובץ ה-PNG ושני קובצי XML קטנים שמפנים אליו. אחר כך תוכלו להשתמש ב-painterResource(R.drawable.icon) והמערכת תבחר את הקובץ המתאים אחרי שהיא תזהה את הלוקאל.

מחרוזות וערכים פשוטים אחרים

כדי ליצור כינוי למחרוזת קיימת, משתמשים במזהה המשאב של המחרוזת הרצויה כערך של המחרוזת החדשה:

<?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.
  • שם המשאב, שהוא שם הקובץ ללא הסיומת.

גישה למשאבים ב-Compose

Jetpack Compose מספקת פונקציות מובנות שמתאימות ל-Composable כדי לגשת למשאבים בצורה מאובטחת.

  • מחרוזות:
    stringResource(id = R.string.hello)
  • Drawables:
    painterResource(id = R.drawable.my_icon)

גישה למשאבים בקוד שאינו ממשק משתמש

אם אתם צריכים לגשת למשאבים מחוץ להיררכיית ממשק המשתמש – למשל ב-ViewModel, ב-Repository או ב-Service של המערכת – אתם יכולים לפתור אותם באמצעות Context.

// Retrieve a localized string resource
val greeting = context.getString(R.string.hello_world)

אפשר גם לאחזר משאבים בודדים באמצעות שיטות ב-Resources, שאפשר לקבל מופע שלהן באמצעות getResources.

תחביר

זה התחביר להפניה למשאב בקוד:

[<package_name>.]R.<resource_type>.<resource_name>
  • <package_name> הוא שם החבילה שבה נמצא המשאב (לא נדרש כשמפנים למשאבים מהחבילה שלכם).
  • <resource_type> הוא מחלקת המשנה R של סוג המשאב.
  • <resource_name> הוא שם הקובץ של המשאב ללא הסיומת או ערך המאפיין android:name ברכיב ה-XML, עבור ערכים פשוטים.

מידע נוסף על כל סוג משאב ועל אופן ההפניה אליו זמין במאמר בנושא משאבים ב-Compose.

גישה לקבצים המקוריים

למרות שזה לא נפוץ, יכול להיות שתצטרכו לגשת לקבצים ולספריות המקוריים. אם כן, שמירת הקבצים ב-res/ לא תעבוד בשבילכם, כי הדרך היחידה לקרוא משאב מ-res/ היא באמצעות מזהה המשאב. במקום זאת, אפשר לשמור את המשאבים בספרייה assets/.

לקבצים שנשמרים בספרייה assets/ לא מוקצה מזהה משאב, ולכן אי אפשר להפנות אליהם דרך המחלקה R או ממשאבי XML. במקום זאת, אפשר לשלוח שאילתות לקבצים בספרייה assets/ כמו למערכת קבצים רגילה, ולקרוא נתונים גולמיים באמצעות AssetManager.

עם זאת, אם כל מה שאתם צריכים הוא היכולת לקרוא נתונים גולמיים (כמו קובץ וידאו או קובץ אודיו), אז שמרו את הקובץ בספרייה res/raw/ וקראו זרם של בייטים באמצעות openRawResource.

גישה למשאבי הפלטפורמה

‫Android מכילה מספר משאבים סטנדרטיים, כמו סגנונות וערכות נושא של המערכת. כדי לגשת אליהם, צריך להוסיף את מחלקת החבילה android להפניה למשאב. לדוגמה: painterResource(android.R.drawable.ic_menu_info_details).

התאמה טובה יותר של משאבים למכשירים

כדי שהאפליקציה שלכם תתמוך בתצורות שונות של מכשירים, חשוב מאוד שתמיד תספקו משאבי ברירת מחדל לכל סוג של משאב שהאפליקציה משתמשת בו.

לדוגמה, אם האפליקציה תומכת בכמה שפות, צריך תמיד לכלול ספרייה בשם values/ (שבה נשמרות המחרוזות) ללא מגדיר שפה ואזור. אם במקום זאת תשימו את כל קובצי המחרוזות בספריות עם מזהה שפה ואזור, האפליקציה תקרוס כשתופעל במכשיר שמוגדר בשפה שהמחרוזות לא תומכות בה.

כל עוד מספקים משאבי ברירת מחדל של values/, האפליקציה פועלת בצורה תקינה, גם אם המשתמש לא מבין את השפה שבה היא מוצגת. עדיף את זה מאשר קריסה.

חשוב לספק משאבי ברירת מחדל לא רק כי יכול להיות שהאפליקציה תפעל בהגדרה שלא צפיתם, אלא גם כי לפעמים גרסאות חדשות של Android מוסיפות מזהי תצורה שגרסאות ישנות יותר לא תומכות בהם. אם משתמשים במזהה חדש של משאב, אבל שומרים על תאימות הקוד לגרסאות מוקדמות יותר של Android, אז כשגרסה מוקדמת יותר של Android מריצה את האפליקציה, היא קורסת אם לא מספקים משאבי ברירת מחדל, כי היא לא יכולה להשתמש במשאבים שנקראים עם המזהה החדש.

לדוגמה, אם minSdkVersion מוגדר ל-4, ואתם מציינים את כל משאבי ה-drawable באמצעות מצב לילה (night או notnight, שנוספו ברמת API 8), מכשיר ברמת API 4 לא יכול לגשת למשאבי ה-drawable שלכם והאפליקציה קורסת. במקרה כזה, כדאי להגדיר את notnight כמשאבי ברירת המחדל, ולכן צריך להחריג את התנאי הזה ולהוסיף את משאבי ה-drawable ל-drawable/ או ל-drawable-night/.

בקיצור, כדי לספק את התאימות הכי טובה למכשירים, תמיד צריך לספק משאבי ברירת מחדל למשאבים שהאפליקציה צריכה כדי לפעול בצורה תקינה. לאחר מכן יוצרים משאבים חלופיים להגדרות ספציפיות של מכשירים באמצעות מסנני הגדרה.

יש יוצא מן הכלל אחד לכלל הזה: אם minSdkVersion של האפליקציה הוא 4 ומעלה, לא צריך משאבי drawable שמוגדרים כברירת מחדל כשמספקים משאבי drawable חלופיים עם מסווג צפיפות המסך. גם בלי משאבי drawable שמוגדרים כברירת מחדל, מערכת Android יכולה למצוא את ההתאמה הכי טובה בין צפיפויות המסך החלופיות ולשנות את קנה המידה של מפות הביטים לפי הצורך. עם זאת, כדי להשיג את חוויית השימוש הטובה ביותר בכל סוגי המכשירים, מומלץ לספק נכסי drawable חלופיים לכל שלושת סוגי הצפיפות.

איך מערכת Android מוצאת את המשאב המתאים ביותר

כשמבקשים משאב ומספקים חלופות, מערכת Android בוחרת בזמן הריצה את המשאב החלופי שבו יש להשתמש, בהתאם לתצורת המכשיר הנוכחית. כדי להדגים איך מערכת Android בוחרת משאב חלופי, נניח שכל אחת מהספריות הבאות של משאבי drawable מכילה גרסאות שונות של אותן תמונות:

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

נניח שההגדרה של המכשיר היא:

‫Locale = en-GB
Night mode = night
Screen pixel density = hdpi
Touchscreen type = notouch
Primary text input method = 12key

מערכת Android משווה את תצורת המכשיר למשאבים החלופיים הזמינים, ובוחרת משאבי drawable מתוך drawable-en-night.

המערכת מגיעה להחלטה אילו משאבים להקצות לפי הלוגיקה הבאה:

איור 2. תרשים זרימה שמראה איך מערכת Android מוצאת את המשאב שהכי מתאים.

  1. הסרת קובצי משאבים שסותרים את תצורת המכשיר.

    הספרייה drawable-fr-rCA/ נמחקת כי היא סותרת את הלוקאל en-GB.

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

    יוצא מן הכלל: דחיסות הפיקסלים במסך היא הקריטריון היחיד שלא נפסל בגלל סתירה. למרות שדחיסות הפיקסלים של המכשיר היא hdpi,‏ drawable-night-ldpi/ לא מוסר כי כל דחיסות הפיקסלים נחשבות להתאמה בשלב הזה. מידע נוסף זמין במאמר סקירה כללית על תאימות מסך.

  2. מחפשים ברשימה את התנאי הבא עם העדיפות הכי גבוהה (טבלה 2). (מתחילים עם קוד הקטגוריה של המוֹכר).
  3. האם אחד ממאגרי המשאבים כולל את התנאי הזה?
    • אם לא, חוזרים לשלב השני ובודקים את הקריטריון הבא. בדוגמה הזו, התשובה היא 'לא' עד שמגיעים לפרמטר להגדרת שפה.
    • אם כן, ממשיכים לשלב 4.
  4. מסירים ספריות של משאבים שלא כוללות את המסווג הזה. בדוגמה הזו, המערכת מסירה את כל הספריות שלא כוללות פרמטר להגדרת שפה:
    drawable/
    drawable-en/
    drawable-en-night/
    drawable-en-notouch-12key/
    drawable-night-ldpi/
    drawable-night-notouch-12key/
    

    יוצא מן הכלל: אם הקריטריון המדובר הוא צפיפות הפיקסלים במסך, מערכת Android בוחרת באפשרות שהכי קרובה לצפיפות המסך של המכשיר. באופן כללי, מערכת Android מעדיפה להקטין תמונה מקורית גדולה מאשר להגדיל תמונה מקורית קטנה. מידע נוסף מופיע במאמר בנושא סקירה כללית על תאימות המסך.

  5. חוזרים על שלבים שני, שלישי ורביעי עד שנשארת רק ספרייה אחת. בדוגמה הזו, מצב לילה הוא התנאי הבא שיש לו התאמות. לכן, משאבים שלא מצוין לגביהם מצב לילה נפסלים:
    drawable-en/
    drawable-en-night/
    drawable-en-notouch-12key/
    

    הספרייה שנותרה היא drawable-en-night.

התהליך הזה מתבצע לכל משאב שמבוקש, אבל המערכת מבצעת אופטימיזציה של חלק מההיבטים שלו. אחד מהאופטימיזציות האלה הוא שאחרי שמזהים את הגדרות המכשיר, יכול להיות שיוסרו משאבים חלופיים שלא יכולים להתאים. לדוגמה, אם שפת התצורה היא אנגלית, אז אף ספריית משאבים שמוגדר בה פרמטר להגדרת שפה שאינו אנגלית לא תיכלל במאגר המשאבים שנבדקים (אבל ספריית משאבים ללא פרמטר להגדרת השפה עדיין תיכלל).

כשבוחרים משאבים על סמך מסנני גודל המסך, המערכת משתמשת במשאבים שמיועדים למסך קטן יותר מהמסך הנוכחי, אם אין משאבים שתואמים יותר. לדוגמה, אם יש צורך, מסך בגודל גדול משתמש במשאבי מסך בגודל רגיל.

עם זאת, אם המשאבים הזמינים הם גדולים יותר מהמסך הנוכחי, המערכת לא משתמשת בהם והאפליקציה קורסת אם אין משאבים אחרים שתואמים לתצורת המכשיר. לדוגמה, זה קורה אם כל משאבי הפריסה מתויגים במגדיר xlarge, אבל המכשיר הוא מסך בגודל רגיל.

הערה: העדיפות של התנאי (בטבלה 2) חשובה יותר ממספר התנאים שתואמים בדיוק למכשיר. בדוגמה הקודמת, בשלב הרביעי, הבחירה האחרונה ברשימה כוללת שלושה מסננים שתואמים בדיוק למכשיר (מצב לילה, סוג מסך מגע ושיטת קלט), ואילו drawable-en כולל רק פרמטר אחד שתואם (שפה). עם זאת, לשפה יש עדיפות גבוהה יותר מאשר לשאר התנאים, ולכן המערכת תסיר את drawable-night-notouch-12key.

מקורות מידע נוספים

מידע נוסף על משאבי אפליקציות זמין במקורות המידע הבאים:

מאמרי עזרה

צפיות בתוכן