پشتیبانی از راه اندازی کتابخانه

توجه: با انتشار اندروید ۹.۰ (سطح API 28)، نسخه جدیدی از کتابخانه پشتیبانی به نام AndroidX وجود دارد که بخشی از Jetpack است. کتابخانه AndroidX شامل کتابخانه پشتیبانی موجود و همچنین جدیدترین اجزای Jetpack است.

شما می‌توانید به استفاده از کتابخانه پشتیبانی ادامه دهید. مصنوعات تاریخی (آن‌هایی که نسخه ۲۷ و قبل از آن دارند و به صورت android.support.* بسته‌بندی شده‌اند) در Google Maven در دسترس خواهند بود. با این حال، تمام توسعه کتابخانه‌های جدید در کتابخانه AndroidX انجام خواهد شد.

توصیه می‌کنیم در تمام پروژه‌های جدید از کتابخانه‌های AndroidX استفاده کنید. همچنین باید انتقال پروژه‌های موجود به AndroidX را نیز در نظر بگیرید.

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

این سند شما را در دانلود بسته کتابخانه پشتیبانی و افزودن کتابخانه‌ها به محیط توسعه‌تان راهنمایی می‌کند.

کتابخانه‌های پشتیبانی اکنون از طریق مخزن Maven گوگل در دسترس هستند. ما دیگر از دانلود کتابخانه‌ها از طریق SDK Manager پشتیبانی نمی‌کنیم و این قابلیت به زودی حذف خواهد شد.

انتخاب کتابخانه‌های پشتیبانی

قبل از افزودن یک کتابخانه پشتیبانی به برنامه خود، تصمیم بگیرید که چه ویژگی‌هایی را می‌خواهید در آن بگنجانید و از پایین‌ترین نسخه‌های اندروید که می‌خواهید پشتیبانی کنید، کدامند. برای اطلاعات بیشتر در مورد ویژگی‌های ارائه شده توسط کتابخانه‌های مختلف، به «ویژگی‌های کتابخانه پشتیبانی» مراجعه کنید.

افزودن کتابخانه‌های پشتیبانی

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

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

1. مخزن Maven گوگل را در فایل settings.gradle پروژه خود قرار دهید.

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
   
           // If you're using a version of Gradle lower than 4.1, you must
           // instead use:
           //
           // maven {
           //     url 'https://maven.google.com'
           // }
       }
   }

2. برای هر ماژولی که می‌خواهید از یک کتابخانه پشتیبانی در آن استفاده کنید، کتابخانه را در بلوک dependencies فایل build.gradle ماژول اضافه کنید. برای مثال، برای اضافه کردن کتابخانه core-utils نسخه ۴، موارد زیر را اضافه کنید:

   dependencies {
       ...
       implementation "com.android.support:support-core-utils:28.0.0"
   }

احتیاط: استفاده از وابستگی‌های پویا (برای مثال، palette-v7:23.0.+ ) می‌تواند باعث به‌روزرسانی‌های غیرمنتظره نسخه و ناسازگاری‌های رگرسیون شود. توصیه می‌کنیم که نسخه کتابخانه را به طور صریح مشخص کنید (برای مثال، palette-v7:28.0.0 ).

استفاده از APIهای کتابخانه پشتیبانی

کلاس‌های کتابخانه پشتیبانی که از APIهای موجود در فریم‌ورک پشتیبانی می‌کنند، معمولاً نامی مشابه کلاس فریم‌ورک دارند، اما در بسته‌های کلاس android.support قرار دارند یا پسوند *Compat دارند.

احتیاط: هنگام استفاده از کلاس‌های کتابخانه پشتیبانی، مطمئن شوید که کلاس را از بسته مناسب وارد می‌کنید. برای مثال، هنگام اعمال کلاس ActionBar :

• android.support.v7.app.ActionBar هنگام استفاده از کتابخانه پشتیبانی.
• android.app.ActionBar هنگام توسعه فقط برای API سطح ۱۱ یا بالاتر.

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

راهنمایی‌های بیشتر برای استفاده از برخی از ویژگی‌های کتابخانه پشتیبانی در کلاس‌های آموزشی توسعه‌دهندگان اندروید، راهنماها و نمونه‌ها ارائه شده است. برای اطلاعات بیشتر در مورد کلاس‌ها و متدهای کتابخانه پشتیبانی، به بسته‌های android.support در مرجع API مراجعه کنید.

تغییرات اعلامیه مانیفست

اگر می‌خواهید سازگاری برنامه فعلی خود را با نسخه‌های قدیمی‌تر API اندروید با استفاده از کتابخانه پشتیبانی افزایش دهید، حتماً مانیفست برنامه خود را به‌روزرسانی کنید. به‌طور خاص، باید عنصر android:minSdkVersion از برچسب <uses-sdk> در مانیفست را به شماره نسخه جدید و پایین‌تر، مطابق شکل زیر، به‌روزرسانی کنید:

  <uses-sdk
      android:minSdkVersion="14"
      android:targetSdkVersion="23" />

تنظیمات مانیفست به گوگل پلی می‌گوید که برنامه شما می‌تواند روی دستگاه‌هایی با اندروید ۴.۰ (سطح API ۱۴) و بالاتر نصب شود.

اگر از فایل‌های ساخت Gradle استفاده می‌کنید، تنظیم minSdkVersion در فایل ساخت، تنظیمات manifest را لغو می‌کند.

plugins {
  id 'com.android.application'
}

android {
    ...

    defaultConfig {
        minSdkVersion 16
        ...
    }
    ...
}

در این حالت، تنظیمات فایل ساخت به گوگل پلی می‌گوید که نسخه پیش‌فرض ساخت برنامه شما می‌تواند روی دستگاه‌هایی با اندروید ۴.۱ (سطح API ۱۶) و بالاتر نصب شود. برای اطلاعات بیشتر در مورد نسخه‌های ساخت، به بررسی اجمالی سیستم ساخت مراجعه کنید.

توجه: اگر چندین کتابخانه پشتیبانی را در برنامه خود قرار می‌دهید، حداقل نسخه SDK باید بالاترین نسخه مورد نیاز هر یک از کتابخانه‌های مشخص شده باشد. به عنوان مثال، اگر برنامه شما شامل هر دو کتابخانه پشتیبانی Preference نسخه ۱۴ و کتابخانه Leanback نسخه ۱۷ باشد، حداقل نسخه SDK شما باید ۱۷ یا بالاتر باشد.