یک کتابخانه اندروید ایجاد کنید

کتابخانه اندروید از نظر ساختاری مشابه ماژول برنامه اندروید است. این شامل همه چیزهایی است که برای ساخت یک برنامه لازم است، از جمله کد منبع، فایل های منبع و مانیفست اندروید.

با این حال، به جای کامپایل در یک APK که روی یک دستگاه اجرا می‌شود، یک کتابخانه Android در یک فایل بایگانی Android (AAR) کامپایل می‌شود که می‌توانید از آن به عنوان وابستگی برای یک ماژول برنامه Android استفاده کنید. برخلاف فایل‌های JAR، فایل‌های AAR عملکرد زیر را برای برنامه‌های اندروید ارائه می‌دهند:

  • فایل‌های AAR می‌توانند حاوی منابع Android و یک فایل مانیفست باشند، که به شما امکان می‌دهد منابع به اشتراک‌گذاشته‌شده مانند طرح‌بندی‌ها و نقشه‌ها را علاوه بر کلاس‌ها و روش‌های Kotlin یا Java در بسته‌بندی کنید.
  • فایل‌های AAR می‌توانند شامل کتابخانه‌های C/C++ برای استفاده توسط کد C/C++ ماژول برنامه باشند.

یک ماژول کتابخانه در شرایط زیر مفید است:

  • هنگام ساخت چندین برنامه که از برخی از اجزای یکسان استفاده می کنند، مانند فعالیت ها، سرویس ها، یا طرح های رابط کاربری
  • هنگام ساخت برنامه ای که در چندین نسخه APK وجود دارد، مانند نسخه رایگان و پولی، که اجزای اصلی را به اشتراک می گذارد

در هر صورت، فایل‌هایی را که می‌خواهید دوباره استفاده کنید به یک ماژول کتابخانه منتقل کنید و سپس کتابخانه را به عنوان یک وابستگی برای هر ماژول برنامه اضافه کنید.

این صفحه نحوه ایجاد و استفاده از ماژول کتابخانه اندروید را توضیح می دهد. برای راهنمایی در مورد نحوه انتشار کتابخانه، به انتشار کتابخانه خود مراجعه کنید

یک ماژول کتابخانه ایجاد کنید

برای ایجاد یک ماژول کتابخانه جدید در پروژه خود، به صورت زیر عمل کنید:

  1. روی File > New > New Module کلیک کنید.
  2. در گفتگوی Create New Module که ظاهر می‌شود، روی Android Library کلیک کنید، سپس روی Next کلیک کنید.

    همچنین گزینه ای برای ایجاد یک کتابخانه Kotlin یا Java وجود دارد که یک فایل JAR سنتی می سازد. در حالی که یک فایل JAR برای بسیاری از پروژه ها مفید است - به خصوص زمانی که می خواهید کد را با سایر سیستم عامل ها به اشتراک بگذارید - به شما اجازه نمی دهد منابع Android یا فایل های مانیفست را اضافه کنید، که برای استفاده مجدد از کد در پروژه های Android بسیار مفید است. این راهنما بر روی ایجاد کتابخانه های اندروید تمرکز دارد.

  3. کتابخانه خود را نامی بگذارید و حداقل نسخه SDK را برای کد موجود در کتابخانه انتخاب کنید، سپس روی Finish کلیک کنید.

هنگامی که همگام سازی پروژه Gradle کامل شد، ماژول کتابخانه در پنجره Project ظاهر می شود. اگر پوشه ماژول جدید را نمی‌بینید، مطمئن شوید که صفحه نمای Android را نشان می‌دهد.

ماژول برنامه را به ماژول کتابخانه تبدیل کنید

اگر یک ماژول برنامه موجود با کدی دارید که می خواهید دوباره استفاده کنید، می توانید آن را به صورت زیر به یک ماژول کتابخانه تبدیل کنید:

  1. اگر از Groovy استفاده می‌کنید، فایل build.gradle سطح ماژول یا اگر از اسکریپت Kotlin استفاده می‌کنید، فایل build.gradle.kts باز کنید.
  2. خط مربوط به applicationId را حذف کنید. فقط یک ماژول برنامه اندروید می تواند این را تعریف کند.
  3. بلوک «plugins» را در بالای فایل پیدا کنید که به شکل زیر است:

    شیار 

      plugins {
      id 'com.android.application'
  }

    کاتلین

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

    آن را به شکل زیر تغییر دهید:

    شیار 

      plugins {
      id 'com.android.library'
  }

    کاتلین

      plugins {
      id("com.android.library")
  }
  4. فایل را ذخیره کنید و روی File > Sync Project with Gradle Files کلیک کنید.

ساختار ماژول یکسان است، اما اکنون به عنوان یک کتابخانه اندرویدی عمل می کند. بیلد به جای APK یک فایل AAR ایجاد می کند.

هنگامی که می خواهید فایل AAR را بسازید، ماژول کتابخانه را در پنجره پروژه انتخاب کنید و روی Build > Build APK کلیک کنید.

با گفتگوی Project Structure وابستگی ها را اضافه کنید

می توانید از کادر گفتگوی ساختار پروژه برای افزودن وابستگی به پروژه خود استفاده کنید. بخش‌های زیر نحوه استفاده از گفتگو برای افزودن وابستگی‌ها را توضیح می‌دهند.

از کتابخانه خود در همان پروژه استفاده کنید

برای استفاده از کد کتابخانه Android جدید خود در برنامه یا ماژول کتابخانه دیگری در همان پروژه، یک وابستگی در سطح پروژه اضافه کنید:

  1. به File > Project Structure > Dependencies بروید.
  2. ماژولی را که می خواهید کتابخانه را اضافه کنید انتخاب کنید.
  3. در تب Declared Dependencies ، کلیک کنید و از منو Module Dependency را انتخاب کنید.

  4. در گفتگوی Add Module Dependency ، ماژول کتابخانه خود را انتخاب کنید.

    وابستگی ماژول را در ساختار پروژه اضافه کنید گفتگو

  5. پیکربندی را که به این وابستگی نیاز دارد انتخاب کنید یا اگر برای همه پیکربندی ها اعمال می شود، اجرا را انتخاب کنید، سپس روی OK کلیک کنید.

Android Studio فایل build.gradle یا build.gradle.kts ماژول شما را ویرایش می کند تا وابستگی را به شکل زیر اضافه کند:

شیار 

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

کاتلین 

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

از کتابخانه خود در پروژه های دیگر استفاده کنید

روش توصیه شده برای به اشتراک گذاری وابستگی ها (JAR ها و AAR ها) با یک مخزن Maven است که روی یک سرویس میزبانی می شود، مانند Maven Central ، یا با ساختار دایرکتوری روی دیسک محلی شما. برای اطلاعات بیشتر در مورد استفاده از مخازن Maven، به مخازن راه دور مراجعه کنید.

هنگامی که یک کتابخانه اندروید در یک مخزن Maven منتشر می شود، ابرداده ها گنجانده می شود تا وابستگی های کتابخانه در ساخت مصرف کننده گنجانده شود. این به کتابخانه اجازه می‌دهد تا در صورت استفاده در مکان‌های مختلف، به‌طور خودکار حذف شود.

برای استفاده از کد کتابخانه اندروید خود در یک ماژول برنامه دیگر در یک پروژه دیگر، به صورت زیر عمل کنید:

  1. به File > Project Structure > Dependencies بروید.
  2. در تب Declared Dependencies ، کلیک کنید و کتابخانه Dependency را در منو انتخاب کنید.

  3. در گفتگوی Add Library Dependency ، از کادر جستجو برای پیدا کردن کتابخانه برای افزودن استفاده کنید. این فرم مخازن مشخص شده در بلوک dependencyResolutionManagement { repositories {...}} را در فایل settings.gradle یا settings.gradle.kts جستجو می کند.

    وابستگی کتابخانه را در ساختار پروژه اضافه کنید گفتگو

  4. پیکربندی را که به این وابستگی نیاز دارد انتخاب کنید یا اگر برای همه پیکربندی ها اعمال می شود، اجرا را انتخاب کنید، سپس روی OK کلیک کنید.

فایل build.gradle یا build.gradle.kts برنامه خود را بررسی کنید تا تأیید کنید که اعلانی مشابه موارد زیر ظاهر می شود (بسته به پیکربندی ساختی که انتخاب کرده اید):

شیار 

  implementation 'com.example:examplelibrary:1.0.0'

کاتلین 

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

AAR یا JAR خود را به عنوان یک وابستگی اضافه کنید

برای استفاده از کد کتابخانه اندروید خود در یک ماژول برنامه دیگر، به صورت زیر عمل کنید:

  1. به File > Project Structure > Dependencies بروید.
  2. در تب Declared Dependencies ، کلیک کنید و Jar Dependency را در منو انتخاب کنید.

  3. در گفتگوی Add Jar/Aar Dependency ، مسیر فایل AAR یا JAR خود را وارد کنید، سپس پیکربندی که وابستگی به آن اعمال می شود را انتخاب کنید. اگر کتابخانه باید برای همه پیکربندی ها در دسترس باشد، پیکربندی پیاده سازی را انتخاب کنید.

    وابستگی AAR را در ساختار پروژه اضافه کنید گفتگو

    فایل build.gradle یا build.gradle.kts برنامه خود را بررسی کنید تا تأیید کنید که اعلانی مشابه موارد زیر ظاهر می شود (بسته به پیکربندی ساختی که انتخاب کرده اید):

    شیار 

      implementation files('my_path/my_lib.aar')

    کاتلین

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

برای وارد کردن وابستگی به بیلد Gradle که خارج از Android Studio اجرا می شود، یک مسیر به وابستگی در فایل build.gradle یا build.gradle.kts برنامه خود اضافه کنید. به عنوان مثال:

شیار 

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

کاتلین

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

برای اطلاعات بیشتر درباره افزودن وابستگی‌های Gradle، به افزودن وابستگی‌های ساخت رجوع کنید.

یک منبع عمومی را اعلام کنید

منابع شامل تمام فایل‌های موجود در دایرکتوری 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 /> خصوصی کنید. این هیچ چیز را عمومی نمی کند و همه منابع را خصوصی می کند.

هر منبعی که می‌خواهید برای توسعه‌دهندگانی که از کتابخانه شما استفاده می‌کنند قابل مشاهده باقی بماند، باید عمومی شود.

خصوصی کردن ضمنی ویژگی‌ها، کاربران کتابخانه شما را از دریافت پیشنهادات تکمیل کد از منابع داخلی کتابخانه جلوگیری می‌کند و به کاربران اجازه می‌دهد منابع خصوصی را بدون شکستن مشتریان کتابخانه شما تغییر نام داده یا حذف کنند. منابع خصوصی از تکمیل کد فیلتر می‌شوند و ابزار lint به شما هشدار می‌دهد وقتی می‌خواهید به یک منبع خصوصی ارجاع دهید.

هنگام ساخت یک کتابخانه، افزونه Android Gradle تعاریف منابع عمومی را دریافت می کند و آنها را در فایل public.txt استخراج می کند، که سپس در داخل فایل AAR بسته بندی می شود.

ملاحظات توسعه برای ماژول های کتابخانه

همانطور که ماژول های کتابخانه و برنامه های وابسته خود را توسعه می دهید، از رفتارها و محدودیت های زیر آگاه باشید.

  • کتابخانه ها به ترتیب اولویت ادغام می شوند.

    پس از افزودن ارجاع به ماژول های کتابخانه به ماژول برنامه اندروید خود، می توانید اولویت نسبی آنها را تعیین کنید. در زمان ساخت، کتابخانه‌ها یکی یکی با برنامه ادغام می‌شوند، از کمترین اولویت تا بالاترین.

  • از تضادهای ادغام منابع اجتناب کنید.

    ابزارهای ساخت، منابع یک ماژول کتابخانه را با منابع یک ماژول برنامه وابسته ادغام می کنند. اگر شناسه منبع معینی در هر دو ماژول تعریف شده باشد، از منبع برنامه استفاده می شود.

    اگر تداخل بین چندین کتابخانه AAR رخ دهد، از منبع کتابخانه ای که ابتدا در لیست وابستگی ها (نزدیک ترین به بالای بلوک dependencies ) فهرست شده استفاده می شود.

    برای جلوگیری از تضاد منابع، از کلاس های R غیر گذرا استفاده کنید. اگر این امکان پذیر نیست، پس استفاده از یک پیشوند یا طرح نامگذاری ثابت دیگری را در نظر بگیرید که منحصر به ماژول است (یا در همه ماژول های پروژه منحصر به فرد است).

  • در ساخت های چند ماژول، وابستگی های JAR به عنوان وابستگی های گذرا در نظر گرفته می شوند.

    هنگامی که یک وابستگی JAR را به پروژه کتابخانه ای اضافه می کنید که یک AAR خروجی می دهد، JAR توسط ماژول کتابخانه پردازش شده و با AAR آن بسته بندی می شود.

    با این حال، اگر پروژه شما شامل یک ماژول کتابخانه است که توسط یک ماژول برنامه مصرف می شود، ماژول برنامه با وابستگی محلی JAR کتابخانه به عنوان یک وابستگی گذرا برخورد می کند. در این مورد، JAR محلی توسط ماژول برنامه ای که آن را مصرف می کند پردازش می شود و نه توسط ماژول کتابخانه. این باعث افزایش سرعت ساخت‌های افزایشی می‌شود که به دلیل تغییرات در کد یک کتابخانه ایجاد می‌شوند.

    هرگونه تضاد منابع جاوا ناشی از وابستگی های محلی JAR باید در ماژول برنامه ای که کتابخانه را مصرف می کند حل شود.

  • یک ماژول کتابخانه می تواند به یک کتابخانه JAR خارجی وابسته باشد.

    شما می توانید یک ماژول کتابخانه ای توسعه دهید که به یک کتابخانه خارجی بستگی دارد. در این مورد، ماژول وابسته باید در برابر هدفی که شامل کتابخانه خارجی است ساخته شود.

    توجه داشته باشید که هم ماژول کتابخانه و هم برنامه وابسته باید کتابخانه خارجی را در فایل های مانیفست خود در عنصر <uses-library> اعلام کنند.

  • minSdkVersion ماژول برنامه باید مساوی یا بزرگتر از نسخه تعریف شده توسط کتابخانه باشد.

    یک کتابخانه به عنوان بخشی از ماژول برنامه وابسته کامپایل می شود، بنابراین APIهای مورد استفاده در ماژول کتابخانه باید با نسخه پلتفرمی که ماژول برنامه پشتیبانی می کند سازگار باشد.

  • هر ماژول کتابخانه ای کلاس R خود را ایجاد می کند.

    هنگامی که ماژول های برنامه وابسته را می سازید، ماژول های کتابخانه در یک فایل AAR کامپایل می شوند و سپس به ماژول برنامه اضافه می شوند. بنابراین، هر کتابخانه کلاس R خاص خود را دارد که با توجه به نام بسته کتابخانه نامگذاری می شود.

    کلاس R تولید شده از ماژول اصلی و ماژول کتابخانه در تمام بسته های مورد نیاز، از جمله بسته ماژول اصلی و بسته های کتابخانه ها ایجاد می شود.

  • یک ماژول کتابخانه ممکن است شامل فایل پیکربندی ProGuard خودش باشد.

    اگر پروژه کتابخانه ای دارید که از آن برای ساخت و انتشار یک AAR استفاده می کنید، می توانید یک فایل پیکربندی ProGuard را به پیکربندی ساخت کتابخانه خود اضافه کنید. اگر این کار را انجام می دهید، افزونه Android Gradle قوانین ProGuard را که شما مشخص کرده اید اعمال می کند. ابزارهای ساخت این فایل را در فایل AAR تولید شده برای ماژول کتابخانه جاسازی می کنند. هنگامی که کتابخانه را به یک ماژول برنامه اضافه می کنید، فایل ProGuard کتابخانه به فایل پیکربندی ProGuard ( proguard.txt ) ماژول برنامه اضافه می شود.

    با جاسازی یک فایل ProGuard در ماژول کتابخانه خود، به شما کمک می کنید تا اطمینان حاصل کنید که ماژول های برنامه که به کتابخانه شما وابسته هستند نیازی به به روز رسانی دستی فایل های ProGuard خود برای استفاده از کتابخانه شما ندارند. هنگامی که سیستم ساخت اندروید استودیو برنامه شما را می سازد، از دستورالعمل های ماژول برنامه و کتابخانه استفاده می کند. بنابراین نیازی به اجرای یک کد کوچک کننده در کتابخانه در یک مرحله جداگانه وجود ندارد.

    برای افزودن قوانین ProGuard به پروژه کتابخانه خود، نام فایل را با ویژگی consumerProguardFiles در بلوک defaultConfig فایل build.gradle یا build.gradle.kts کتابخانه خود مشخص کنید.

    به عنوان مثال، قطعه زیر lib-proguard-rules.txt به عنوان فایل پیکربندی ProGuard کتابخانه تنظیم می کند:

    شیار 

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

    کاتلین

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

    با این حال، اگر ماژول کتابخانه شما بخشی از یک ساخت چند ماژول است که در یک APK کامپایل می‌شود و AAR ایجاد نمی‌کند، کوچک کردن کد را فقط روی ماژول برنامه‌ای که کتابخانه را مصرف می‌کند، اجرا کنید. برای کسب اطلاعات بیشتر در مورد قوانین ProGuard و استفاده از آنها، Shrink، obfuscate و بهینه سازی برنامه خود را بخوانید.

  • آزمایش یک ماژول کتابخانه تقریباً مشابه آزمایش یک برنامه است.

    تفاوت اصلی این است که کتابخانه و وابستگی های آن به طور خودکار به عنوان وابستگی های APK آزمایشی گنجانده می شوند. این بدان معناست که APK آزمایشی نه تنها شامل کد خود، بلکه AAR کتابخانه و تمام وابستگی‌های آن است. از آنجایی که هیچ برنامه جداگانه ای تحت آزمایش وجود ندارد، وظیفه androidTest فقط APK آزمایشی را نصب می کند (و حذف نصب می کند).

    هنگام ادغام چندین فایل مانیفست ، Gradle از ترتیب اولویت پیش‌فرض پیروی می‌کند و مانیفست کتابخانه را در مانیفست اصلی APK آزمایشی ادغام می‌کند.

آناتومی یک فایل AAR

پسوند فایل برای یک فایل AAR .aar است و نوع آرتیفکت Maven نیز aar است. خود فایل یک فایل ZIP است. تنها ورودی اجباری /AndroidManifest.xml است.

یک فایل AAR همچنین می تواند شامل یک یا چند مورد از ورودی های اختیاری زیر باشد: