توجه: با انتشار اندروید 9.0 (سطح API 28) نسخه جدیدی از کتابخانه پشتیبانی به نام AndroidX وجود دارد که بخشی از Jetpack است. کتابخانه AndroidX شامل کتابخانه پشتیبانی موجود و همچنین شامل آخرین اجزای Jetpack است.
می توانید به استفاده از کتابخانه پشتیبانی ادامه دهید. مصنوعات تاریخی (آنهایی که نسخه 27 و قبل از آن منتشر شده اند و به عنوان android.support.* ) در Google Maven در دسترس خواهند بود. با این حال، تمام توسعه کتابخانه جدید در کتابخانه AndroidX رخ خواهد داد.
توصیه می کنیم از کتابخانه های AndroidX در تمام پروژه های جدید استفاده کنید. همچنین باید پروژه های موجود را به AndroidX منتقل کنید .
هنگام توسعه برنامه‌هایی که از چندین نسخه API پشتیبانی می‌کنند، ممکن است بخواهید یک راه استاندارد برای ارائه ویژگی‌های جدیدتر در نسخه‌های قبلی اندروید داشته باشید یا به طرز دلپذیری به عملکردهای مشابه برگردید. به جای ساخت کد برای مدیریت نسخه های قبلی پلتفرم، می توانید از این کتابخانه ها برای ارائه لایه سازگاری استفاده کنید. علاوه بر این، کتابخانه‌های پشتیبانی، کلاس‌ها و ویژگی‌های راحتی اضافی را ارائه می‌کنند که در API استاندارد Framework برای توسعه و پشتیبانی آسان‌تر در دستگاه‌های بیشتر موجود نیستند.
کتابخانه پشتیبانی اندروید که در اصل یک کتابخانه باینری واحد برای برنامه ها بود، به مجموعه ای از کتابخانه ها برای توسعه برنامه تبدیل شده است. بسیاری از این کتابخانه‌ها در حال حاضر به شدت توصیه می‌شوند، اگر نه ضروری، بخشی از توسعه برنامه.
این سند یک نمای کلی از کتابخانه پشتیبانی ارائه می دهد تا به شما در درک اجزای آن و نحوه استفاده موثر از آن در برنامه خود کمک کند.
احتیاط: با شروع نسخه 26.0.0 کتابخانه پشتیبانی (ژوئیه 2017)، حداقل سطح API پشتیبانی شده در اکثر کتابخانه های پشتیبانی به Android 4.0 (سطح API 14) برای اکثر بسته های کتابخانه افزایش یافته است. برای اطلاعات بیشتر، پشتیبانی نسخه و نام‌های بسته را در این صفحه ببینید.
موارد استفاده برای کتابخانه های پشتیبانی
چند کاربرد متمایز برای کتابخانه های پشتیبانی وجود دارد. کلاس‌های سازگاری با نسخه‌های قبلی پلتفرم تنها یکی از آنهاست. در اینجا لیست کامل تری از روش هایی وجود دارد که می توانید از کتابخانه های پشتیبانی در برنامه خود استفاده کنید:
- سازگاری به عقب برای API های جدیدتر - تعداد زیادی از کتابخانه های پشتیبانی سازگاری عقب مانده را برای کلاس ها و روش های چارچوب جدیدتر فراهم می کنند. به عنوان مثال، کلاس پشتیبانی
Fragment از قطعات در دستگاه‌هایی که نسخه‌های قدیمی‌تر از Android 3.0 (سطح API 11) دارند، پشتیبانی می‌کند. - کلاس‌های کمکی و راحتی - کتابخانه‌های پشتیبانی تعدادی کلاس کمکی، به‌ویژه برای توسعه رابط کاربری فراهم می‌کنند. به عنوان مثال، کلاس
RecyclerView یک ویجت رابط کاربری برای نمایش و مدیریت لیست های بسیار طولانی، قابل استفاده در نسخه های Android از سطح API 7 و بالاتر ارائه می دهد. - اشکال زدایی و ابزارهای کمکی - تعدادی ویژگی وجود دارد که فراتر از کدهایی که در برنامه خود گنجانده اید، ابزار مفیدی را ارائه می دهند، از جمله کتابخانه
support-annotations برای بررسی بهتر کدها در ورودی های روش و پشتیبانی Multidex برای پیکربندی و توزیع برنامه ها با بیش از 65536 روش.
استفاده از پشتیبانی در مقابل APIهای چارچوب
کتابخانه‌های پشتیبانی کلاس‌ها و روش‌هایی را ارائه می‌کنند که شباهت زیادی به APIها در چارچوب Android دارند. پس از کشف این موضوع، ممکن است تعجب کنید که آیا باید از نسخه چارچوب API یا معادل کتابخانه پشتیبانی استفاده کنید. در اینجا دستورالعمل هایی برای استفاده از کلاس های کتابخانه پشتیبانی به جای Framework API وجود دارد:
- سازگاری برای یک ویژگی خاص - اگر می‌خواهید از ویژگی پلتفرم اخیر در دستگاه‌هایی که نسخه‌های قبلی پلتفرم را اجرا می‌کنند، پشتیبانی کنید، از کلاس‌ها و روش‌های معادل کتابخانه پشتیبانی استفاده کنید.
- سازگاری با ویژگی‌های کتابخانه مرتبط - کلاس‌های کتابخانه پشتیبانی پیچیده‌تر ممکن است به یک یا چند کلاس کتابخانه پشتیبانی اضافی بستگی داشته باشند، بنابراین باید از کلاس‌های کتابخانه پشتیبانی برای آن وابستگی‌ها استفاده کنید. برای مثال، کلاس پشتیبانی
ViewPager باید با کلاس های پشتیبانی FragmentPagerAdapter یا FragmentStatePagerAdapter استفاده شود. - سازگاری عمومی دستگاه - اگر ویژگی پلتفرمی خاصی ندارید که قصد دارید با برنامه خود به روشی سازگار با عقب استفاده کنید، همچنان ایده خوبی است که از کلاس های کتابخانه پشتیبانی در برنامه خود استفاده کنید. به عنوان مثال، ممکن است بخواهید به جای کلاس
Activity Framework از ActivityCompat استفاده کنید، بنابراین می توانید بعداً از ویژگی های جدیدتر استفاده کنید، مانند ترکیب مدل مجوزهای جدید معرفی شده در Android 6.0 (سطح API 23).
کلاس‌های کتابخانه پشتیبانی که یک پیاده‌سازی سازگار از کلاس‌های API پلتفرم را ارائه می‌دهند، ممکن است نتوانند مجموعه کاملی از عملکردهای موجود در آخرین نسخه را ارائه دهند، به دلیل محدودیت‌های نسخه پلتفرم دستگاه میزبان. در این موارد، کلاس‌های کتابخانه پشتیبان به گونه‌ای طراحی شده‌اند که به‌خوبی کاهش پیدا کنند، و ممکن است تمام عملکردها یا داده‌های API پلتفرم فعلی را ارائه ندهند. به همین دلیل، باید مستندات مرجع را برای کلاس‌ها و روش‌های کتابخانه‌ای که استفاده می‌کنید بررسی کنید و روی دستگاه‌هایی که اولین نسخه پلتفرم پشتیبانی شده توسط برنامه شما را اجرا می‌کنند، به‌طور کامل آزمایش کنید.
توجه: کتابخانه‌های پشتیبانی کلاس‌ها و روش‌های معادل را برای هر چارچوب API ارائه نمی‌کنند. در برخی موارد، ممکن است لازم باشد یک فراخوانی روش چارچوب را با یک بررسی صریح نسخه SDK بپیچید و کد جایگزین برای مدیریت روش‌هایی که در دستگاه موجود نیست ارائه کنید. برای اطلاعات بیشتر در مورد استفاده از بررسی نسخه در کد خود، به پشتیبانی از نسخه‌های مختلف پلتفرم مراجعه کنید.
پشتیبانی نسخه و نام بسته
برخی از بسته‌های کتابخانه پشتیبانی دارای نام بسته هستند تا حداقل سطح API را که در ابتدا پشتیبانی می‌کردند، با استفاده از نماد av#، مانند بسته support-v4، نشان دهند. با شروع نسخه 26.0.0 کتابخانه پشتیبانی (منتشر شده در ژوئیه 2017)، حداقل سطح API پشتیبانی شده برای همه بسته‌های کتابخانه پشتیبانی به Android 4.0 (سطح API 14) تغییر کرده است. به همین دلیل، هنگام کار با هر نسخه اخیر از کتابخانه پشتیبانی، نباید فرض کنید که نماد بسته v# حداقل سطح پشتیبانی API را نشان می دهد. این تغییر در نسخه‌های اخیر همچنین به این معنی است که بسته‌های کتابخانه‌ای با v4 و v7 اساساً در حداقل سطح API که پشتیبانی می‌کنند معادل هستند. به عنوان مثال، بسته support-v4 و support-v7 هر دو حداقل سطح API 14 را برای نسخه های پشتیبانی کتابخانه از نسخه 26.0.0 و بالاتر پشتیبانی می کنند.
پشتیبانی از نسخه های انتشار کتابخانه
نسخه انتشار کتابخانه پشتیبانی، مانند 24.2.0 یا 25.0.1، با حداقل سطح API پشتیبانی شده توسط هر کتابخانه در آن نسخه متفاوت است. شماره نسخه انتشار نشان می دهد که بر اساس کدام نسخه از API پلت فرم ساخته شده است، و بنابراین، آخرین APIها ممکن است در این نسخه از کتابخانه ها گنجانده شوند .
به طور خاص، بخش اول شماره نسخه انتشار، به عنوان مثال 24 در نسخه 24.2.0، به طور کلی با نسخه API پلتفرم موجود در هنگام انتشار مطابقت دارد. سطح نسخه انتشار کتابخانه پشتیبانی نشان می‌دهد که برخی از ویژگی‌های آن سطح API را در خود جای داده است، اما نباید تصور کنید که با تمام ویژگی‌های منتشر شده در نسخه API پلتفرم جدید سازگاری دارد.
وابستگی های کتابخانه
اکثر کتابخانه‌های مجموعه کتابخانه پشتیبانی Android به یک یا چند کتابخانه وابستگی دارند. به عنوان مثال، تقریباً تمام کتابخانه های پشتیبانی به بسته support-compat وابستگی دارند. به طور کلی، شما نیازی به نگرانی در مورد پشتیبانی از وابستگی های کتابخانه ندارید، زیرا ابزار ساخت gradle، وابستگی های کتابخانه را برای شما مدیریت می کند، با درج خودکار کتابخانه های وابسته.
اگر می‌خواهید ببینید چه کتابخانه‌ها و وابستگی‌های کتابخانه‌ای در برنامه شما گنجانده شده‌اند، دستور زیر را در ریشه ساخت پروژه توسعه برنامه خود اجرا کنید تا گزارشی از وابستگی‌های آن پروژه، از جمله کتابخانه‌های پشتیبانی Android و کتابخانه‌های دیگر دریافت کنید:
gradle -q dependencies your-app-project:dependencies
برای اطلاعات بیشتر در مورد افزودن کتابخانه های پشتیبانی به پروژه توسعه خود با استفاده از Gradle، به راه اندازی کتابخانه پشتیبانی مراجعه کنید. برای اطلاعات بیشتر در مورد کار با Gradle، به پیکربندی ساخت خود مراجعه کنید.
توجه داشته باشید که همه کتابخانه‌های پشتیبانی Android برای نسخه‌های اخیر به سطح پایه پلتفرم نیز وابسته هستند، یعنی Android 4.0 (سطح API 14) یا بالاتر.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-01-10 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-01-10 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Support Library\n\n**Note:** With the release of Android 9.0 (API level 28) there is\na new version of the support library called\n[AndroidX](/jetpack/androidx) which is part of [Jetpack](/jetpack).\nThe AndroidX library\ncontains the existing support library and also includes the latest Jetpack components.\n\n\u003cbr /\u003e\n\n\nYou can continue to use the support library.\nHistorical artifacts (those versioned 27 and earlier, and packaged as `android.support.*`) will\nremain available on Google Maven. However, all new library development\nwill occur in the [AndroidX](/jetpack/androidx) library.\n\n\u003cbr /\u003e\n\n\nWe recommend using the AndroidX libraries in all new projects. You should also consider\n[migrating](/jetpack/androidx/migrate) existing projects to AndroidX as well.\n\n\nWhen developing apps that support multiple API versions, you may want a\nstandard way to provide newer features on earlier versions of Android or\ngracefully fall back to equivalent functionality. Rather than building code\nto handle earlier versions of the platform, you can leverage these libraries\nto provide that compatibility layer. In addition, the Support Libraries\nprovide additional convenience classes and features not available in the\nstandard Framework API for easier development and support across more\ndevices.\n\n\nOriginally a single binary library for apps, the Android Support Library has\nevolved into a suite of libraries for app development. Many of these\nlibraries are now a strongly recommended, if not essential, part of app\ndevelopment.\n\n\nThis document provides an overview of the support library to help you\nunderstand its components and how to use it effectively in your app.\n\n\n**Caution:** Starting with Support Library release 26.0.0\n(July 2017), the minimum supported API level across most support libraries\nhas increased to Android 4.0 (API level 14) for most library packages. For\nmore information, see [Version Support and Package\nNames](#api-versions) on this page.\n\nUses for the Support Libraries\n------------------------------\n\n\nThere are a few distinct uses for the support libraries. Backward\ncompatibility classes for earlier versions of the platform is just one of\nthem. Here is a more complete list of ways you can use the support libraries\nin your app:\n\n- **Backward Compatibility for newer APIs** - A large amount of the support libraries provide backward compatibility for newer framework classes and methods. For example, the [Fragment](/reference/androidx/fragment/app/Fragment) support class provides support for fragments on devices running versions earlier than Android 3.0 (API level 11).\n- **Convenience and Helper Classes** - The support libraries provides a number of helper classes, particularly for user interface development. For example the [RecyclerView](/reference/androidx/recyclerview/widget/RecyclerView) class provides a user interface widget for displaying and managing very long lists, useable on versions of Android from API level 7 and up.\n- **Debugging and Utilities** - There are a number of features that provide utility beyond code you incorporate into your app, including the [`support-annotations`](/studio/write/annotations) library for improved code lint checks on method inputs and [Multidex support](/studio/build/multidex) for configuring and distributing apps with over 65,536 methods.\n\nUsing Support versus Framework APIs\n-----------------------------------\n\n\nSupport Libraries provide classes and methods that closely resemble APIs in\nthe Android Framework. Upon discovering this, you may wonder if you should\nuse the framework version of the API or the support library equivalent. Here\nare the guidelines for when you should use support library classes in place\nof Framework APIs:\n\n- **Compatibility for a Specific Feature** - If you want to support a recent platform feature on devices that are running earlier versions of the platform, use the equivalent classes and methods from the support library.\n- **Compatibility for Related Library Features** - More sophisticated support library classes may depend on one or more additional support library classes, so you should use support library classes for those dependencies. For example, the [ViewPager](/reference/androidx/viewpager/widget/ViewPager) support class should be used with [FragmentPagerAdapter](/reference/androidx/fragment/app/FragmentPagerAdapter) or the [FragmentStatePagerAdapter](/reference/androidx/fragment/app/FragmentStatePagerAdapter) support classes.\n- **General Device Compatibility** - If you do not have a specific platform feature you intend to use with your app in a backward compatible way, it is still a good idea to use support library classes in your app. For example, you may want to use [ActivityCompat](/reference/androidx/core/app/ActivityCompat) in place of the framework [Activity](/reference/android/app/Activity) class, so you can take advantage of newer features later on, such as incorporating the new permissions model introduced in Android 6.0 (API level 23).\n\n\nSupport Library classes that provide a compatible implementation of platform\nAPI classes may not be able to provide the full set of functionality\navailable in the latest release, due to the limitations of the host device\nplatform version. In these cases, Support Library classes are designed to\ndegrade gracefully, and may not provide the all the functionality or data of\nthe current, platform API. For this reason, you should review the reference\ndocumentation for the library classes and methods you use, and thoroughly\ntest on devices running the earliest version of the platform supported by\nyour app.\n\n\n**Note:** The support libraries do not provide equivalent\nclasses and methods for each framework API. In some cases, you may need to\nwrap a framework method call with an explicit SDK version check and provide\nalternative code to handle methods not available on a device. For more\ninformation on using version checks in your code, see [Supporting Different\nPlatform Versions](/training/basics/supporting-devices/platforms).\n\nVersion Support and Package Names\n---------------------------------\n\n\nSome of the Support Library packages have package names to indicate the\nminimum level of the API they originally supported,\nusing a v# notation, such as the\nsupport-v4 package. Starting with Support Library version 26.0.0 (released in\nJuly 2017), the minimum supported API level has changed to Android 4.0 (API\nlevel 14) for all support library packages. For this reason, when working with\nany recent release of the support library, you should not assume that the\nthe *v#* package notation indicates a minimum API support level.\nThis change in recent releases also means that library packages with the v4\nand v7 are essentially equivalent in the minimum level of API they support.\nFor example, the support-v4 and the support-v7 package both support a minimum\nAPI level of 14, for releases of the Support Library from 26.0.0 and higher.\n\n### Support Library Release Versions\n\n\nThe [release version](/topic/libraries/support-library/revisions) of the Support Library, such as 24.2.0 or 25.0.1, is\ndifferent from the minimum API level supported by any library in that\nrelease.The release version number indicates which version of the platform\nAPI it was built against, and therefore, what the most recent APIs *may be\nincluded* in this version of the libraries.\n\n\nSpecifically, the first section of the release version number, for example\nthe 24 in version 24.2.0, generally corresponds with the version of the\nplatform API available when it was released. The release version level of the\nsupport library indicates it incorporates *some* features of that API\nlevel, but you should not assume it provides compatibility with *all*\nfeatures released in the new platform API version.\n\nLibrary Dependencies\n--------------------\n\n\nMost libraries in the Android Support Library suite have some dependency on\none or more libraries. For example, nearly all support libraries have a\ndependency on the `support-compat` package. In general, you do not\nneed to worry about support library dependencies, because the gradle build\ntool manages library dependencies for you, by automatically including\ndependent libraries.\n\n\nIf you want to see what libraries and library dependencies are included in\nyour app, run the following command at the build root of your app development\nproject to get a report of the dependencies for that project, including\nAndroid Support Libraries and other libraries: \n\n```\ngradle -q dependencies your-app-project:dependencies\n```\n\n\nFor more information about adding support libraries to your development\nproject using Gradle, see [Support\nLibrary Setup](/topic/libraries/support-library/setup). For more information about working with Gradle, see\n[Configure\nYour Build](/studio/build).\n\n\nNote that *all* Android Support Libraries also depend on some base level\nof the platform, for recent releases, that is Android 4.0 (API level 14) or\nhigher."]]
