یک کتابخانه اندروید از نظر ساختاری مشابه یک ماژول برنامه اندروید است. این کتابخانه شامل همه چیزهایی است که برای ساخت یک برنامه لازم است، از جمله کد منبع، فایل‌های منبع و یک مانیفست اندروید.
با این حال، به جای کامپایل شدن به یک APK که روی یک دستگاه اجرا می‌شود، یک کتابخانه اندروید به یک فایل بایگانی اندروید (AAR) کامپایل می‌شود که می‌توانید از آن به عنوان یک وابستگی برای یک ماژول برنامه اندروید استفاده کنید. برخلاف فایل‌های JAR، فایل‌های AAR قابلیت‌های زیر را برای برنامه‌های اندروید ارائه می‌دهند:
- فایل‌های AAR می‌توانند شامل منابع اندروید و یک فایل مانیفست باشند که به شما امکان می‌دهد علاوه بر کلاس‌ها و متدهای کاتلین یا جاوا، منابع مشترکی مانند طرح‌بندی‌ها و فایل‌های ترسیمی را نیز در آنها قرار دهید.
- فایل‌های AAR می‌توانند حاوی کتابخانه‌های C/C++ برای استفاده توسط کد C/C++ ماژول برنامه باشند.
یک ماژول کتابخانه در شرایط زیر مفید است:
- هنگام ساخت چندین برنامه که از برخی از اجزای یکسان مانند فعالیت‌ها، سرویس‌ها یا طرح‌بندی‌های رابط کاربری استفاده می‌کنند
- هنگام ساخت برنامه‌ای که در چندین نسخه APK وجود دارد، مانند نسخه رایگان و پولی، که اجزای اصلی مشترکی دارند
در هر صورت، فایل‌هایی را که می‌خواهید دوباره استفاده کنید به یک ماژول کتابخانه منتقل کنید و سپس کتابخانه را به عنوان یک وابستگی برای هر ماژول برنامه اضافه کنید.
این صفحه نحوه ایجاد و استفاده از یک ماژول کتابخانه اندروید را توضیح می‌دهد. برای راهنمایی در مورد نحوه انتشار یک کتابخانه، به بخش «انتشار کتابخانه خود» مراجعه کنید.
ایجاد ماژول کتابخانه
برای ایجاد یک ماژول کتابخانه جدید در پروژه خود، مراحل زیر را دنبال کنید:
- روی فایل > جدید > ماژول جدید کلیک کنید.
- در پنجره‌ی «ایجاد ماژول جدید» که ظاهر می‌شود، روی «کتابخانه‌ی اندروید» کلیک کنید، سپس روی «بعدی» کلیک کنید.
همچنین گزینه‌ای برای ایجاد یک کتابخانه Kotlin یا Java وجود دارد که یک فایل JAR سنتی می‌سازد. در حالی که یک فایل JAR برای بسیاری از پروژه‌ها مفید است - به خصوص وقتی می‌خواهید کد را با سایر پلتفرم‌ها به اشتراک بگذارید - به شما اجازه نمی‌دهد منابع اندروید یا فایل‌های مانیفست را وارد کنید، که برای استفاده مجدد از کد در پروژه‌های اندروید بسیار مفید است. این راهنما بر ایجاد کتابخانه‌های اندروید تمرکز دارد.
- برای کتابخانه خود یک نام انتخاب کنید و حداقل نسخه SDK را برای کد موجود در کتابخانه انتخاب کنید، سپس روی Finish کلیک کنید.
پس از اتمام همگام‌سازی پروژه Gradle، ماژول کتابخانه در پنل پروژه ظاهر می‌شود. اگر پوشه ماژول جدید را نمی‌بینید، مطمئن شوید که پنل، نمای اندروید را نمایش می‌دهد.
تبدیل ماژول برنامه به ماژول کتابخانه
اگر یک ماژول برنامه موجود با کدی دارید که می‌خواهید دوباره از آن استفاده کنید، می‌توانید آن را به صورت زیر به یک ماژول کتابخانه تبدیل کنید:
- اگر از Groovy استفاده می‌کنید، فایل
build.gradleدر سطح ماژول و اگر از اسکریپت Kotlin استفاده می‌کنید، فایلbuild.gradle.ktsرا باز کنید. - خط مربوط به
applicationIdرا حذف کنید. فقط یک ماژول برنامه اندروید می‌تواند این را تعریف کند. - بلوک «افزونه‌ها» را در بالای فایل که به شکل زیر است، پیدا کنید:
گرووی
plugins { id 'com.android.application' }
کاتلین
plugins { id("com.android.application") }
آن را به صورت زیر تغییر دهید:
گرووی
plugins { id 'com.android.library' }
کاتلین
plugins { id("com.android.library") }
- فایل را ذخیره کنید و روی File > Sync Project with Gradle Files کلیک کنید.
ساختار ماژول ثابت مانده است، اما اکنون به عنوان یک کتابخانه اندروید عمل می‌کند. این نسخه به جای APK، یک فایل AAR ایجاد می‌کند.
وقتی می‌خواهید فایل AAR را بسازید، ماژول کتابخانه را در پنجره پروژه انتخاب کنید و روی Build > Build APK کلیک کنید.
اضافه کردن وابستگی‌ها با استفاده از پنجره ساختار پروژه
شما می‌توانید از پنجره‌ی ساختار پروژه برای افزودن وابستگی‌ها به پروژه‌ی خود استفاده کنید. بخش‌های زیر نحوه‌ی استفاده از این پنجره برای افزودن وابستگی‌ها را شرح می‌دهند.
از کتابخانه خود در همان پروژه استفاده کنید
برای استفاده از کد کتابخانه اندروید جدید خود در یک برنامه یا ماژول کتابخانه دیگر در همان پروژه، یک وابستگی در سطح پروژه اضافه کنید:
- به مسیر فایل > ساختار پروژه > وابستگی‌ها بروید.
- ماژولی را که می‌خواهید کتابخانه آن را اضافه کنید، انتخاب کنید.
- در برگه وابستگی‌های اعلام‌شده ، کلیک کنید
و از منو، گزینه وابستگی ماژول (Module Dependency) را انتخاب کنید. 
در پنجره‌ی «افزودن وابستگی ماژول» ، ماژول کتابخانه‌ی خود را انتخاب کنید.
پیکربندی‌ای را که به این وابستگی نیاز دارد انتخاب کنید یا اگر پیاده‌سازی برای همه پیکربندی‌ها اعمال می‌شود، آن را انتخاب کنید، سپس روی تأیید کلیک کنید.
اندروید استودیو فایل build.gradle یا build.gradle.kts ماژول شما را ویرایش می‌کند تا وابستگی را به شکل زیر اضافه کند:
گرووی
implementation project(path: ":example-library")
کاتلین
implementation(project(":example-library"))
استفاده از کتابخانه شما در پروژه‌های دیگر
روش توصیه‌شده برای اشتراک‌گذاری وابستگی‌ها (JARها و AARها) استفاده از یک مخزن Maven است که یا روی یک سرویس مانند Maven Central میزبانی می‌شود، یا با یک ساختار دایرکتوری روی دیسک محلی شما. برای اطلاعات بیشتر در مورد استفاده از مخازن Maven، به مخازن Remote مراجعه کنید.
وقتی یک کتابخانه اندروید در مخزن Maven منتشر می‌شود، متادیتا (metadata) نیز اضافه می‌شود تا وابستگی‌های کتابخانه در نسخه مصرفی گنجانده شوند. این امر به کتابخانه اجازه می‌دهد در صورت استفاده در چندین مکان، به‌طور خودکار داده‌های تکراری را حذف کند.
برای استفاده از کد کتابخانه اندروید خود در ماژول برنامه دیگری در یک پروژه متفاوت، به شرح زیر عمل کنید:
- به مسیر فایل > ساختار پروژه > وابستگی‌ها بروید.
- در برگه وابستگی‌های اعلام‌شده ، کلیک کنید و در منو، گزینه‌ی Library Dependency (وابستگی به کتابخانه) را انتخاب کنید.
در پنجره‌ی Add Library Dependency ، از کادر جستجو برای یافتن کتابخانه‌ی مورد نظر جهت افزودن استفاده کنید. این فرم، مخازن مشخص شده در بلوک
dependencyResolutionManagement { repositories {...}}در فایلsettings.gradleیاsettings.gradle.ktsرا جستجو می‌کند.
پیکربندی‌ای را که به این وابستگی نیاز دارد انتخاب کنید یا اگر پیاده‌سازی برای همه پیکربندی‌ها اعمال می‌شود، آن را انتخاب کنید، سپس روی تأیید کلیک کنید.
فایل build.gradle یا build.gradle.kts برنامه خود را بررسی کنید تا مطمئن شوید که اعلانی مشابه زیر ظاهر می‌شود (بسته به پیکربندی ساختی که انتخاب کرده‌اید):
گرووی
implementation 'com.example:examplelibrary:1.0.0'
کاتلین
implementation("com.example:examplelibrary:1.0.0")
AAR یا JAR خود را به عنوان وابستگی اضافه کنید
برای استفاده از کد کتابخانه اندروید خود در ماژول برنامه دیگر، مراحل زیر را دنبال کنید:
- به مسیر فایل > ساختار پروژه > وابستگی‌ها بروید.
- در برگه وابستگی‌های اعلام‌شده ، کلیک کنید و در منو، گزینه‌ی Jar Dependency را انتخاب کنید.
در پنجره‌ی Add Jar/Aar Dependency ، مسیر فایل AAR یا JAR خود را وارد کنید، سپس پیکربندی‌ای را که وابستگی به آن اعمال می‌شود انتخاب کنید. اگر کتابخانه باید برای همه پیکربندی‌ها در دسترس باشد، پیکربندی پیاده‌سازی را انتخاب کنید.
فایل
build.gradleیاbuild.gradle.ktsبرنامه خود را بررسی کنید تا مطمئن شوید که اعلانی مشابه زیر ظاهر می‌شود (بسته به پیکربندی ساختی که انتخاب کرده‌اید):گرووی
implementation files('my_path/my_lib.aar')
کاتلین
implementation(files("my_path/my_lib.aar"))
برای وارد کردن یک وابستگی به نسخه Gradle که خارج از اندروید استودیو اجرا می‌شود، مسیر وابستگی را در فایل 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، به Add build dependencies مراجعه کنید.
اعلام منبع عمومی
منابع شامل تمام فایل‌های موجود در دایرکتوری 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) فهرست شده است، استفاده می‌شود.برای جلوگیری از تداخل منابع، استفاده از یک پیشوند یا طرح نامگذاری سازگار دیگر را که مختص ماژول باشد (یا در تمام ماژول‌های پروژه منحصر به فرد باشد) در نظر بگیرید.
در ساخت‌های چند ماژولی، وابستگی‌های 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 و کاربرد آنها، بخش کوچک‌سازی، مبهم‌سازی و بهینه‌سازی برنامه خود را مطالعه کنید.
آزمایش یک ماژول کتابخانه تقریباً مشابه آزمایش یک برنامه است.
تفاوت اصلی این است که کتابخانه و وابستگی‌های آن به طور خودکار به عنوان وابستگی‌های APK آزمایشی گنجانده می‌شوند. این بدان معناست که APK آزمایشی نه تنها کد خود، بلکه AAR کتابخانه و تمام وابستگی‌های آن را نیز شامل می‌شود. از آنجا که هیچ برنامه جداگانه‌ای تحت آزمایش نیست، وظیفه
androidTestفقط APK آزمایشی را نصب (و حذف) می‌کند.هنگام ادغام چندین فایل مانیفست ، Gradle از ترتیب اولویت پیش‌فرض پیروی می‌کند و مانیفست کتابخانه را در مانیفست اصلی APK آزمایشی ادغام می‌کند.
آناتومی یک فایل AAR
پسوند فایل AAR، .aar است و نوع مصنوع Maven نیز aar است. خود فایل یک فایل ZIP است. تنها ورودی اجباری /AndroidManifest.xml است.
یک فایل AAR همچنین می‌تواند شامل یک یا چند مورد از ورودی‌های اختیاری زیر باشد:
-
/classes.jar -
/res/ -
/R.txt -
/public.txt -
/assets/ -
/libs/ name .jar -
/jni/ abi_name / name .so(که در آن abi_name یکی از ABI های پشتیبانی شده توسط اندروید است) -
/proguard.txt -
/lint.jar -
/api.jar -
/prefab/برای اکسپورت کتابخانه‌های بومی