مكتبة الدعم
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
ملاحظة: مع إصدار Android 9.0 (المستوى 28 من واجهة برمجة التطبيقات)، لن يكون هناك
لإصدار جديد من مكتبة الدعم يسمى
نظام AndroidX الذي يُعدّ جزءًا من Jetpack
مكتبة AndroidX
ويحتوي على مكتبة الدعم الحالية، بالإضافة إلى أحدث مكوّنات Jetpack.
يمكنك مواصلة استخدام مكتبة الدعم.
ستكون العناصر التاريخية (التي تم إطلاقها في الإصدار 27 أو الإصدارات الأقدم والمضمّنة في شكل android.support.*) جاهزة.
متاحة على Google Maven. ومع ذلك، فإن جميع عمليات تطوير المكتبات الجديدة
سيحدث في مكتبة AndroidX.
ننصح باستخدام مكتبات AndroidX في جميع المشاريع الجديدة. يجب عليك أيضًا مراعاة
نقل المشاريع الحالية إلى AndroidX أيضًا.
عند تطوير التطبيقات التي تدعم إصدارات متعددة من واجهة برمجة التطبيقات، قد تحتاج إلى
طريقة قياسية لتوفير ميزات أحدث في الإصدارات السابقة من Android أو
بسلاسة إلى الوظيفة المكافئة. بدلاً من إنشاء التعليمات البرمجية
للتعامل مع الإصدارات السابقة من المنصة، يمكنكم الاستفادة من هذه المكتبات
لتوفير طبقة التوافق هذه. بالإضافة إلى ذلك، تقدم "مكتبات الدعم"
توفير فئات ملائمة وميزات إضافية غير متوفرة في
وFrame API العادية لتسهيل التطوير والدعم عبر
الأجهزة.
كانت مكتبة دعم Android في الأصل مكتبة ثنائية واحدة للتطبيقات،
إلى مجموعة من المكتبات لتطوير التطبيقات. فالعديد من هذه
فإن المكتبات يوصى بشدة بإضافتها إن لم يكن ضروريًا
والتطوير.
يقدم هذا المستند نظرة عامة على مكتبة الدعم لمساعدتك
فهم مكوّناتها وكيفية استخدامها بفعالية في تطبيقك.
تنبيه: بدءًا من الإصدار 26.0.0 من Support Library
(تموز (يوليو) 2017)، وهو الحد الأدنى لمستوى واجهة برمجة التطبيقات المعتمد في معظم مكتبات الدعم
إلى Android 4.0 (المستوى 14 من واجهة برمجة التطبيقات) لمعظم حزم المكتبات. بالنسبة
للحصول على مزيد من المعلومات، يُرجى مراجعة دعم الإصدار والحزمة
الأسماء في هذه الصفحة.
استخدامات مكتبات الدعم
وهناك عدد قليل من الاستخدامات المختلفة لمكتبات الدعم. الرجوع
وفئات التوافق الخاصة بالإصدارات السابقة من النظام الأساسي هي واحدة فقط من
معهم. إليك قائمة أكثر شمولاً بالطرق التي يمكنك من خلالها استخدام مكتبات الدعم.
في تطبيقك:
-
التوافق مع الأنظمة القديمة لواجهات برمجة التطبيقات الأحدث - كمية كبيرة من
توفر مكتبات الدعم توافقًا مع الأنظمة القديمة لإطار العمل الأحدث
الفئات والطرق. على سبيل المثال،
Fragment
فئة الدعم توفر دعم الأجزاء على الأجهزة التي تعمل بإصدارات
الأقدم من الإصدار Android 3.0 (المستوى 11 لواجهة برمجة التطبيقات).
-
فئات الراحة والمساعد - توفر مكتبات الدعم
عدد فئات المساعدة، لا سيما في ما يتعلّق بتطوير واجهة المستخدم. بالنسبة
مثال: توفر الفئة
RecyclerView للمستخدم
واجهة لعرض قوائم طويلة جدًا وإدارتها، ويمكن استخدامها على
لـ Android بدءًا من مستوى واجهة برمجة التطبيقات 7 والأعلى.
-
تصحيح الأخطاء والأدوات المساعدة - هناك عدد من الميزات
توفِّر فائدة لا تقتصر على الرموز البرمجية التي تستخدمها في تطبيقك، بما في ذلك:
support-annotations
للحصول على عمليات تحقّق محسَّنة من أداة Lint Codes لمُدخلات الطرق ودعم Multidex
لإنشاء التطبيقات وتوزيعها باستخدام أكثر من 65,536 طريقة.
استخدام واجهات برمجة تطبيقات الدعم في مقابل واجهات برمجة تطبيقات إطار العمل
توفر مكتبات الدعم فئات وطرق تشبه واجهات برمجة التطبيقات إلى حد كبير في
إطار عمل Android. عند اكتشاف ذلك، قد تتساءل عما إذا كان ينبغي عليك
استخدام إصدار إطار العمل من واجهة برمجة التطبيقات أو ما يعادلها من مكتبة الدعم. هنا
هي الإرشادات الخاصة بالحالات التي يجب فيها استخدام فصول مكتبة الدعم
من واجهات برمجة التطبيقات لإطار العمل:
-
التوافق مع ميزة معينة - إذا كنت ترغب في دعم
الميزة الأحدث على الأجهزة التي تعمل بإصدارات سابقة من
الأساسية، يمكنك استخدام الفئات والطرق المكافئة من مكتبة الدعم.
-
التوافق مع ميزات المكتبات ذات الصلة - أكثر تطورًا
وصفوف مكتبة الدعم على دعم إضافي واحد أو أكثر
بالمكتبة، لذا يجب عليك استخدام فصول مكتبة الدعم لتلك
والتبعيات لديك. على سبيل المثال،
ViewPager
يجب استخدام صف الدعم مع فئتَي الدعم "FragmentPagerAdapter" أو "FragmentStatePagerAdapter".
-
التوافق العام مع الجهاز: إذا لم يكن لديك جهاز
إحدى الميزات التي تنوي استخدامها مع تطبيقك بإصدارات متوافقة مع الأنظمة القديمة.
إلا أنه من الأفضل استخدام فصول مكتبة الدعم في تطبيقك.
على سبيل المثال، قد تحتاج إلى استخدام
ActivityCompat بدلاً من الفئة Activity في إطار العمل للاستفادة من الميزات الأحدث.
فيما بعد، مثل دمج نموذج الأذونات الجديد الذي تم تقديمه في
Android 6.0 (المستوى 23)
صفوف مكتبة الدعم التي توفّر تطبيقًا متوافقًا مع النظام الأساسي
قد لا تتمكن فئات واجهة برمجة التطبيقات من توفير المجموعة الكاملة من الوظائف
متوفّرة في أحدث إصدار، بسبب قيود الجهاز المضيف
إصدار النظام الأساسي. وفي هذه الحالات، تم تصميم فئات مكتبة الدعم
تتدهور بسلاسة، وقد لا توفر جميع الوظائف أو البيانات
واجهة برمجة التطبيقات الحالية للنظام الأساسي. لهذا السبب، يجب مراجعة المرجع.
وثائق لصفوف المكتبة وطرقها التي تستخدمها،
على الأجهزة التي تعمل بالإصدار الأقدم من النظام الأساسي
تطبيقك.
ملاحظة: لا توفّر مكتبات الدعم تطبيقات مكافئة.
والفئات والطرق لكل واجهة برمجة تطبيقات للإطار. في بعض الحالات، قد تحتاج إلى
يجب إحاطة استدعاء طريقة إطار العمل بفحص إصدار حزمة SDK الصريح وتوفير
رمز بديل للتعامل مع الطرق غير المتاحة على الجهاز. لمزيد من المعلومات،
معلومات حول استخدام عمليات التحقق من الإصدار في التعليمات البرمجية، راجع دعم مختلف
إصدارات النظام الأساسي:
دعم الإصدار وأسماء الحِزم
تحتوي بعض حزم مكتبة الدعم على أسماء حزمة للإشارة إلى
الحد الأدنى من واجهة برمجة التطبيقات التي دعمتها في الأصل،
باستخدام علامة v#، مثل
حزمة الإصدار 4 من الدعم. بدءًا من الإصدار 26.0.0 من Support Library (مكتبة الدعم)
تموز (يوليو) 2017)، حيث تغير الحد الأدنى المتاح لمستوى واجهة برمجة التطبيقات إلى Android 4.0 (واجهة برمجة التطبيقات).
المستوى 14) لكل حزم مكتبة الدعم. لهذا السبب، عند العمل مع
أي إصدار حديث من مكتبة الدعم، فلا ينبغي أن تفترض أن
يشير تدوين الحزمة v# إلى الحد الأدنى لمستوى دعم واجهة برمجة التطبيقات.
يعني هذا التغيير في الإصدارات الحديثة أيضًا أن حزم المكتبة التي تتضمن الإصدار 4
والإصدار 7 مكافئان في الحد الأدنى من واجهة برمجة التطبيقات التي تتيحهما.
على سبيل المثال، يدعم كل من حزمة support-v4 وsupport-v7 الحد الأدنى
المستوى 14 من واجهة برمجة التطبيقات (API) لإصدارات Support Library من 26.0.0 والإصدارات الأحدث
إصدارات إصدارات مكتبة الدعم
صفحة
إصدار الإصدار من مكتبة الدعم، مثل 24.2.0 أو 25.0.1، هو
مختلفًا عن الحد الأدنى لمستوى واجهة برمجة التطبيقات الذي تستخدمه أي مكتبة على حدة
إصدار.يشير رقم إصدار الإصدار إلى إصدار النظام الأساسي
واجهة برمجة التطبيقات التي تم إنشاؤها، وبالتالي، ما هي أحدث واجهات برمجة التطبيقات
المضمنة في هذا الإصدار من المكتبات.
وعلى وجه التحديد، القسم الأول من رقم إصدار الإصدار، على سبيل المثال
24 في الإصدار 24.2.0، تتوافق بشكل عام مع إصدار
Platform API المتاحة عند إصدارها. يمثِّل مستوى إصدار
إلى أنها تتضمن بعض ميزات واجهة برمجة التطبيقات
ولكن لا ينبغي أن تفترض أنه يتوافق مع جميع
في إصدار واجهة برمجة تطبيقات النظام الأساسي الجديد.
تبعيات المكتبة
تعتمد معظم المكتبات في مجموعة مكتبة دعم Android على بعض
مكتبة واحدة أو أكثر. على سبيل المثال، تحتوي جميع مكتبات الدعم تقريبًا على
والاعتماد على حزمة support-compat. بشكل عام، لا ينبغي لك
ينبغي أن تقلق بشأن تبعيات مكتبة الدعم، نظرًا لأن نظام Gradle
تبعيات المكتبة من أجلك، عن طريق تضمين
والمكتبات التابعة.
إذا كنت تريد معرفة تبعيات المكتبات المضمنة في
فشغِّل الأمر التالي في جذر الإصدار الخاص بتطوير تطبيقك
مشروعك للحصول على تقرير عن التبعيات لهذا المشروع، بما في ذلك
مكتبات دعم Android والمكتبات الأخرى:
gradle -q dependencies your-app-project:dependencies
لمزيد من المعلومات حول إضافة مكتبات الدعم إلى حزمة تطوير البرامج
باستخدام Gradle، راجع الدعم
إعداد المكتبة: لمزيد من المعلومات حول العمل باستخدام Gradle، يمكنك الاطلاع على
الإعداد
التصميم الخاص بك:
تجدر الإشارة إلى أن جميع مكتبات دعم Android تعتمد أيضًا على مستوى أساسي معيّن
للنظام الأساسي، في الإصدارات الأخيرة، أي Android 4.0 (المستوى 14 لواجهة برمجة التطبيقات) أو
أعلى.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2024-08-23 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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"]],["تاريخ التعديل الأخير: 2024-08-23 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],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."]]
