יצירת ספרייה ל-Android

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

עם זאת, במקום הידור ל-APK שפועל במכשיר, ספריית Android עוברת לקובץ ארכיון של Android (AAR) שאפשר משמשת כתלות במודול של אפליקציה ל-Android. בשונה מקובצי JAR, קובצי AAR מציעים את הפונקציונליות הבאה באפליקציות ל-Android:

  • קובצי AAR יכולים להכיל משאבי Android וקובץ מניפסט, שמאפשר מאגדים יחד משאבים משותפים, כמו פריסות ופריטים גרפיים, לכיתות ולשיטות של Kotlin או Java.
  • קובצי AAR יכולים להכיל את הטקסט C/C++ ספריות לשימוש בקוד C/C++ של מודול האפליקציה.

מודול ספרייה שימושי במצבים הבאים:

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

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

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

יצירת מודול ספרייה

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

  1. לוחצים על קובץ > חדש > מודול חדש.
  2. בתיבת הדו-שיח יצירת מודול חדש שמופיעה, לוחצים על ספריית Android ואז על הבא.

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

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

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

המרה של מודול אפליקציה למודול ספרייה

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

  1. פותחים את הקובץ build.gradle ברמת המודול, אם משתמשים בו מגניב, או הקובץ build.gradle.kts, אם משתמשים ב-Kotlin סקריפט.
  2. מוחקים את השורה של applicationId. רק מודול של אפליקציה ל-Android יכול להגדיר את זה.
  3. מוצאים את הבלוק 'Plugins' (יישומי פלאגין) בחלק העליון של הקובץ שנראה כך:

    מגניב

      plugins {
      id 'com.android.application'
  }

    Kotlin

      plugins {
      id("com.android.application")
  }

    משנים אותה לאפשרות הבאה:

    מגניב

      plugins {
      id 'com.android.library'
  }

    Kotlin

      plugins {
      id("com.android.library")
  }
  4. שומרים את הקובץ ולוחצים על File > (קובץ >) סנכרון הפרויקט עם קובצי Gradle

המבנה של המודול לא השתנה, אבל עכשיו הוא פועל כספריית Android. ה-build יוצר קובץ AAR במקום APK.

כדי ליצור את קובץ ה-AAR, צריך לבחור את מודול הספרייה החלון Project ולוחצים Build > Build APK.

הוספת יחסי תלות באמצעות תיבת הדו-שיח של מבנה הפרויקט

אפשר להשתמש בתיבת הדו-שיח Project Project כדי להוסיף יחסי תלות פרויקט. בקטעים הבאים מתואר איך להשתמש בתיבת הדו-שיח כדי להוסיף של יחסי התלות.

אפשר להשתמש בספרייה מתוך אותו פרויקט

כדי להשתמש בקוד של ספריית Android החדשה באפליקציה אחרת או במודול ספרייה אחר בתוך לפרויקט מסוים, מוסיפים תלות ברמת הפרויקט:

  1. עוברים אל File > Project (קובץ). מבנה > יחסי תלות.
  2. בוחרים את המודול שרוצים להוסיף לו את הספרייה.
  3. בכרטיסייה יחסי תלות מוצהרים, לוחצים על ובחירה תלות במודול מהתפריט.

  4. בתיבת הדו-שיח Add Module Dependency בוחרים את מודול הספרייה.

    הוספת תלות של מודול במבנה הפרויקט תיבת דו-שיח

  5. בוחרים את ההגדרה שדורשת את התלות הזאת או בוחרים הטמעה אם היא חלה על כל התצורות, לוחצים על אישור.

מערכת Android Studio עורכים את הקובץ build.gradle או build.gradle.kts של המודול כך: מוסיפים את התלות בפורמט הבא:

מגניב

  implementation project(path: ":example-library")

Kotlin

  implementation(project(":example-library"))

שימוש בספרייה בפרויקטים אחרים

הדרך המומלצת לשתף יחסי תלות (JAR ו-AAR) היא עם Maven שמתארחים בשירות מסוים, Maven Central, או באמצעות מבנה ספרייה בדיסק המקומי. לקבלת מידע נוסף על השימוש למידע על מאגרים של Maven, אפשר לעיין במאמר מרחוק מאגרים.

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

כדי להשתמש בקוד של ספריית Android במודול אפליקציה אחר בפרויקט אחר: כך עושים את זה:

  1. ניווט אל קובץ > מבנה הפרויקט > של יחסי התלות.
  2. בכרטיסייה יחסי תלות מוצהרים, לוחצים על ובחירה תלות בספרייה בתפריט.

  3. בתיבת הדו-שיח הוספת תלות בספרייה, משתמשים בתיבת החיפוש כדי למצוא לספרייה להוספה. בטופס הזה אפשר לחפש במאגרים שצוינו בבלוק dependencyResolutionManagement { repositories {...}} קובץ settings.gradle או settings.gradle.kts.

    הוספת תלות של ספרייה במבנה הפרויקט תיבת דו-שיח

  4. בוחרים את ההגדרה שדורשת את התלות הזאת או בוחרים הטמעה אם היא חלה על כל התצורות, לוחצים על אישור.

צריך לבדוק את הקובץ build.gradle או build.gradle.kts של האפליקציה כדי לוודא ש תופיע הצהרה שדומה לזו (בהתאם לתצורת ה-build). שבחרת):

מגניב

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

  implementation("com.example:examplelibrary:1.0.0")

הוספת ה-AAR או ה-JAR כתלות

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

  1. עוברים אל קובץ > מבנה הפרויקט > של יחסי התלות.
  2. בכרטיסייה יחסי תלות מוצהרים, לוחצים על ובוחרים ב-Jar תלות בתפריט.

  3. בתיבת הדו-שיח הוספת תלות של Jar/Aar, מזינים את הנתיב ל-AAR או קובץ JAR, בוחרים את התצורה שהתלות חל. אם הספרייה אמורה להיות זמינה לכל ההגדרות, בוחרים הגדרה של הטמעה.

    הוספת תלות של AAR במבנה הפרויקט תיבת דו-שיח

    צריך לבדוק את הקובץ build.gradle או build.gradle.kts של האפליקציה כדי לוודא ש תופיע הצהרה שדומה לזו (בהתאם לתצורת ה-build). שבחרת):

    מגניב

      implementation files('my_path/my_lib.aar')

    Kotlin

      implementation(files("my_path/my_lib.aar"))

כדי לייבא תלות ב-build של Gradle שפועל מחוץ ל-Android Studio, מוסיפה נתיב לתלות את קובץ build.gradle או build.gradle.kts של האפליקציה. לדוגמה:

מגניב

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}

Kotlin

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

למידע נוסף על הוספת יחסי תלות של Gradle, מוסיפים יחסי תלות של build

הצהרה על משאב ציבורי

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

כדי להצהיר על משאב ציבורי, צריך להוסיף הצהרת <public> לקובץ public.xml של הספרייה. אם לא הוספתם בסטטוס 'גלוי לכולם' קודם לכן, עליכם ליצור את הקובץ public.xml בספרייה res/values/ של הספרייה שלך.

הקוד לדוגמה הבא יוצר שני משאבי מחרוזת ציבוריים עם המאפיין שמות mylib_app_name ו-mylib_public_string:

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

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

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

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

כשיוצרים ספרייה, הפלאגין של Android Gradle מקבל את המשאב הציבורי ומחלץ אותן לקובץ public.txt, ואז נארזות בתוך קובץ ה-AAR.

שיקולי פיתוח למודולים של ספריות

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

  • הספריות ממוזגות לפי סדר עדיפות.

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

  • מניעת התנגשויות במיזוג משאבים

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

    אם מתרחשות התנגשויות בין ספריות AAR מרובות, המשאב הראשונה שמופיעה ברשימת יחסי התלות (הקרובה ביותר לחלק העליון של בלוק אחד (dependencies).

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

  • בגרסאות build של מודולים מרובים, יחסי התלות של JAR נחשבים יחסי תלות מעבריביים.

    כשמוסיפים תלות של JAR לפרויקט ספרייה שמפיק פלט של AAR, ה-JAR מעובד על ידי מודול הספרייה ונארז עם ה-AAR שלו.

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

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

  • מודול ספרייה יכול להיות תלוי בספריית JAR חיצונית.

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

    שימו לב שגם מודול הספרייה וגם האפליקציה התלויה חייבים להצהיר על הספרייה החיצונית בקובצי המניפסט שלהם ב רכיב <uses-library>.

  • ה-minSdkVersion של מודול האפליקציה חייב להיות שווה ל- או גדולה מהגרסה שהוגדרה על ידי הספרייה.

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

  • כל מודול ספרייה יוצר מחלקה R משלו.

    כשיוצרים את המודולים של האפליקציות התלויות, המודולים של הספרייה עוברים הידור קובץ AAR שנוסף למודול האפליקציה. לכן, לכל ספרייה יש מחלקה אחת (R), בעלת שם בהתאם לשם החבילה של הספרייה.

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

  • מודול ספרייה יכול לכלול הגדרת ProGuard משלו .

    אם יש לכם פרויקט ספרייה שאתם משתמשים בו כדי ליצור ולפרסם AAR, יכולים להוסיף קובץ תצורה של ProGuard לתצורת ה-build של הספרייה. אם כן, הפלאגין Android Gradle מחיל את כללי ProGuard שציינת. כלי ה-build מטמיעים את הקובץ הזה בקובץ ה-AAR שנוצר לספרייה של מודל טרנספורמר. כשמוסיפים את הספרייה למודול של אפליקציה, קובץ ProGuard של הספרייה מצורף לקובץ התצורה של ProGuard (proguard.txt) של את מודול האפליקציה.

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

    כדי להוסיף את כללי ProGuard לפרויקט הספרייה שלך, יש לציין את שם הקובץ עם המאפיין consumerProguardFiles שבתוך הרכיב גוש בניינים אחד (defaultConfig) מתוך build.gradle של הספרייה שלך או קובץ build.gradle.kts.

    לדוגמה, קטעי הקוד הבאים מגדירים lib-proguard-rules.txt כהגדרות ProGuard של הספרייה file:

    מגניב

    android {
    defaultConfig {
        consumerProguardFiles 'lib-proguard-rules.txt'
    }
    ...
}

    Kotlin

    android {
    defaultConfig {
        consumerProguardFiles("lib-proguard-rules.txt")
    }
    ...
}

    עם זאת, אם מודול הספרייה הוא חלק מגרסת build של מודולים מרובים, מהדרת ל-APK ולא יוצרת AAR, מריצה קוד כיווץ רק למודול האפליקציה שצורך את הספרייה. מידע נוסף על כללי ProGuard והשימוש בהם, ניתן לקרוא כיווץ, ערפול קוד (obfuscation) ואופטימיזציה של app.

  • בדיקת מודול של ספרייה כמעט זהה לזו של בדיקת אפליקציה.

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

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

המבנה של קובץ AAR

סיומת הקובץ של קובץ AAR היא .aar, וסוג ארטיפקט של Maven הוא aar גם כן. הקובץ עצמו הוא קובץ ZIP. ערך החובה היחיד הוא /AndroidManifest.xml

קובץ AAR יכול לכלול גם אחד או יותר מהמאפיינים האופציונליים הבאים ערכים: