<uses-sdk>

Google Play از ویژگی‌های <uses-sdk> اعلام‌شده در مانیفست برنامه شما استفاده می‌کند تا برنامه شما را از دستگاه‌هایی که الزامات نسخه پلتفرم آن را برآورده نمی‌کنند فیلتر کند. قبل از تنظیم این ویژگی‌ها، مطمئن شوید که فیلترهای Google Play را می‌شناسید.

نحو:

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

موجود در:

<manifest>

توضیحات:

به شما امکان می دهد سازگاری یک برنامه کاربردی با یک یا چند نسخه از پلتفرم Android را با استفاده از یک عدد صحیح سطح API بیان کنید. سطح API بیان شده توسط یک برنامه با سطح API یک سیستم Android معین مقایسه می شود که می تواند در بین دستگاه های Android مختلف متفاوت باشد.

علیرغم نام آن، این عنصر برای تعیین سطح API استفاده می شود، نه شماره نسخه کیت توسعه نرم افزار (SDK) یا پلت فرم اندروید. سطح API همیشه یک عدد صحیح است. نمی‌توانید سطح API را از شماره نسخه Android مرتبط آن استخراج کنید. مثلاً با نسخه اصلی یا مجموع نسخه اصلی و فرعی یکی نیست.

همچنین سند مربوط به نسخه سازی برنامه های خود را بخوانید.

صفات:

android:minSdkVersion

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

احتیاط: اگر این ویژگی را اعلام نکنید، سیستم مقدار پیش‌فرض «1» را در نظر می‌گیرد که نشان می‌دهد برنامه شما با تمام نسخه‌های اندروید سازگار است. اگر اینطور نیست ، و شما minSdkVersion مناسب را اعلام نکرده اید، پس از نصب بر روی سیستمی با سطح API ناسازگار، برنامه در طول زمان اجرا هنگام تلاش برای دسترسی به APIهای غیرقابل دسترسی از کار می افتد. به همین دلیل، حتما سطح API مناسب را در ویژگی minSdkVersion اعلام کنید.

android:targetSdkVersion

یک عدد صحیح که سطح API مورد نظر برنامه را مشخص می کند. اگر تنظیم نشود، مقدار پیش فرض برابر با مقدار داده شده به minSdkVersion است.

این ویژگی به سیستم اطلاع می‌دهد که شما با نسخه هدف آزمایش کرده‌اید، و سیستم هیچ رفتار سازگاری را برای حفظ سازگاری رو به جلو برنامه شما با نسخه هدف فعال نمی‌کند. این برنامه همچنان می تواند در نسخه های پایین تر (تا minSdkVersion ) اجرا شود.

همانطور که اندروید با هر نسخه جدید تکامل می یابد، برخی از رفتارها و حتی ظاهر ممکن است تغییر کند. با این حال، اگر سطح API پلتفرم بالاتر از نسخه اعلام شده توسط targetSdkVersion برنامه شما باشد، سیستم می‌تواند رفتارهای سازگاری را فعال کند تا برنامه شما همانطور که انتظار دارید به کار خود ادامه دهد. می‌توانید با تعیین targetSdkVersion برای مطابقت با سطح API پلتفرمی که در آن اجرا می‌شود، چنین رفتارهای سازگاری را غیرفعال کنید.

برای مثال، تنظیم این مقدار روی «11» یا بالاتر به سیستم اجازه می‌دهد تا زمانی که در اندروید 3.0 یا بالاتر اجرا می‌شود، تم پیش‌فرض Holo را روی برنامه‌تان اعمال کند و همچنین حالت سازگاری صفحه‌نمایش را هنگام اجرا بر روی صفحه‌های بزرگ‌تر غیرفعال می‌کند، زیرا پشتیبانی از سطح API 11 به طور ضمنی پشتیبانی می‌کند. صفحه نمایش های بزرگتر

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

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

معرفی شده در: سطح API 4

android:maxSdkVersion

یک عدد صحیح که حداکثر سطح API را که برنامه برای اجرا در آن طراحی شده است را تعیین می کند.

در اندروید 1.5، 1.6، 2.0 و 2.0.1، سیستم مقدار این ویژگی را هنگام نصب یک برنامه و هنگام تأیید مجدد برنامه پس از به روز رسانی سیستم بررسی می کند. در هر صورت، اگر ویژگی maxSdkVersion برنامه کمتر از سطح API مورد استفاده خود سیستم باشد، سیستم به برنامه اجازه نصب نمی دهد. در صورت تأیید مجدد پس از به‌روزرسانی سیستم، این به طور مؤثر برنامه شما را از دستگاه حذف می‌کند.

برای نشان دادن اینکه چگونه این ویژگی می تواند بر برنامه شما پس از به روز رسانی سیستم تأثیر بگذارد، به مثال زیر توجه کنید:

برنامه ای که maxSdkVersion="5" در مانیفست خود اعلام می کند در Google Play منتشر شده است. کاربری که دستگاهش Android 1.6 (سطح API 4) را اجرا می کند، برنامه را دانلود و نصب می کند. پس از چند هفته، کاربر یک به‌روزرسانی سیستمی را به اندروید 2.0 (سطح API 5) دریافت می‌کند. پس از نصب به‌روزرسانی، سیستم maxSdkVersion برنامه را بررسی می‌کند و با موفقیت دوباره آن را تأیید می‌کند.

برنامه به طور معمول عمل می کند. با این حال، مدتی بعد، دستگاه به روز رسانی سیستم دیگری را دریافت می کند، این بار به اندروید 2.0.1 (سطح API 6). پس از به روز رسانی، سیستم دیگر نمی تواند برنامه را مجدداً تأیید کند زیرا سطح API خود سیستم (6) اکنون بالاتر از حداکثر پشتیبانی شده توسط برنامه (5) است. این سیستم از قابل مشاهده شدن برنامه برای کاربر جلوگیری می کند و در واقع آن را از دستگاه حذف می کند.

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

معرفی شده در: سطح API 4

برخی از نسخه‌های Android (فراتر از Android 2.0.1) ویژگی maxSdkVersion را در حین نصب یا تأیید مجدد بررسی یا اعمال نمی‌کنند. با این حال، گوگل پلی به استفاده از این ویژگی به عنوان فیلتر ادامه می دهد، با این حال، زمانی که برنامه های کاربردی موجود برای دانلود را به کاربران ارائه می دهد.

معرفی شده در:

API سطح 1

سطح API چیست؟

سطح API یک مقدار صحیح است که به طور منحصربه‌فرد ویرایش API چارچوب ارائه شده توسط نسخه‌ای از پلتفرم Android را شناسایی می‌کند.

پلتفرم اندروید یک چارچوب API ارائه می‌کند که برنامه‌ها می‌توانند از آن برای تعامل با سیستم اندروید زیرین استفاده کنند. چارچوب API شامل موارد زیر است:

• مجموعه ای اصلی از بسته ها و کلاس ها
• مجموعه ای از عناصر و ویژگی های XML برای اعلان یک فایل مانیفست
• مجموعه ای از عناصر و ویژگی های XML برای اعلام و دسترسی به منابع
• مجموعه ای از مقاصد
• مجموعه‌ای از مجوزهایی که برنامه‌ها می‌توانند درخواست کنند، و همچنین مجوزهای اجرایی موجود در سیستم

هر نسخه متوالی از پلتفرم Android می‌تواند شامل به‌روزرسانی‌هایی برای API چارچوب برنامه Android باشد که ارائه می‌کند.

به‌روزرسانی‌های چارچوب API به گونه‌ای طراحی شده‌اند که API جدید با نسخه‌های قبلی API سازگار باقی بماند. به این معنی که اکثر تغییرات در API افزودنی هستند و عملکردهای جدید یا جایگزین را معرفی می کنند. با ارتقاء بخش‌هایی از API، قطعات جایگزین قدیمی‌تر منسوخ می‌شوند اما حذف نمی‌شوند، بنابراین برنامه‌های موجود همچنان می‌توانند از آنها استفاده کنند.

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

چارچوب API که یک پلتفرم Android ارائه می‌کند با استفاده از یک شناسه عدد صحیح به نام سطح API مشخص می‌شود. هر نسخه پلتفرم Android دقیقاً از یک سطح API پشتیبانی می کند، اگرچه پشتیبانی برای تمام سطوح API قبلی (تا سطح API 1) ضمنی است. انتشار اولیه پلتفرم اندروید سطح 1 API را ارائه کرد و نسخه های بعدی سطح API را افزایش دادند.

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

استفاده از سطح API در اندروید

شناسه سطح API نقشی کلیدی در کمک به تضمین بهترین تجربه ممکن برای کاربران و توسعه دهندگان برنامه ایفا می کند:

• این به پلتفرم اندروید اجازه می‌دهد حداکثر ویرایش API چارچوبی را که پشتیبانی می‌کند، توصیف کند.
• این به برنامه‌ها اجازه می‌دهد تا ویرایش چارچوب API مورد نیاز خود را توصیف کنند.
• این به سیستم اجازه می‌دهد تا نصب برنامه‌ها را روی دستگاه کاربر مذاکره کند تا برنامه‌های ناسازگار با نسخه نصب نشوند.

هر نسخه پلتفرم اندروید شناسه سطح API خود را در داخل خود سیستم اندروید ذخیره می کند.

برنامه‌ها می‌توانند از عنصر مانیفست ارائه‌شده توسط چارچوب API— <uses-sdk> —برای توصیف حداقل و حداکثر سطوح API که می‌توانند تحت آن اجرا شوند و همچنین سطح API ترجیحی که برای پشتیبانی طراحی شده‌اند، استفاده کنند. این عنصر سه ویژگی کلیدی را ارائه می دهد:

• android:minSdkVersion : حداقل سطح API که برنامه قادر به اجرا در آن است. مقدار پیش فرض "1" است.
• android:targetSdkVersion : سطح API که برنامه برای اجرا در آن طراحی شده است. در برخی موارد، این به برنامه اجازه می‌دهد از عناصر یا رفتارهای مانیفست تعریف‌شده در سطح API هدف استفاده کند، نه اینکه فقط به استفاده از مواردی که برای حداقل سطح API تعریف شده‌اند محدود شود.
• android:maxSdkVersion : حداکثر سطح API که برنامه قادر به اجرا در آن است. مهم: قبل از استفاده از این ویژگی، اطلاعات مربوط به این ویژگی را در این صفحه بخوانید.

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

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

• اگر یک ویژگی android:minSdkVersion اعلام شود، مقدار آن کمتر یا برابر با عدد صحیح سطح API سیستم است. اگر اعلام نشود، سیستم فرض می کند که برنامه به سطح 1 API نیاز دارد.
• اگر یک ویژگی android:maxSdkVersion اعلام شود، مقدار آن برابر یا بیشتر از عدد صحیح سطح API سیستم است. اگر اعلام نشود، سیستم فرض می کند که برنامه حداکثر سطح API ندارد. توضیحات این ویژگی را برای اطلاعات بیشتر در مورد نحوه برخورد سیستم با آن بخوانید.

هنگامی که در مانیفست یک برنامه اعلام می شود، عنصر <uses-sdk> ممکن است به شکل زیر باشد:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

دلیل اصلی اینکه یک برنامه یک سطح API را در android:minSdkVersion اعلام می کند این است که به سیستم اندروید بگوید که از API هایی استفاده می کند که در سطح API مشخص شده معرفی شده اند.

اگر برنامه به نحوی روی پلتفرمی با سطح API پایین‌تر نصب شود، در زمان اجرا وقتی سعی می‌کند به APIهایی که وجود ندارند دسترسی پیدا کند، از کار می‌افتد. اگر پایین‌ترین سطح API مورد نیاز آن بالاتر از نسخه پلت‌فرم در دستگاه مورد نظر باشد، سیستم از این نتیجه جلوگیری می‌کند.

ملاحظات توسعه

بخش‌های زیر اطلاعات مربوط به سطح API را ارائه می‌دهند که باید هنگام توسعه برنامه خود در نظر بگیرید.

سازگاری رو به جلو برنامه

برنامه های اندروید به طور کلی با نسخه های جدید پلتفرم اندروید سازگار هستند.

از آنجایی که تقریباً تمام تغییرات در چارچوب API افزودنی هستند، یک برنامه Android که با استفاده از هر نسخه معینی از API ایجاد شده است، همانطور که در سطح API آن مشخص شده است، با نسخه‌های بعدی پلتفرم Android و سطوح بالاتر API سازگار است. این برنامه می‌تواند در تمام نسخه‌های بعدی پلتفرم اندروید اجرا شود، به جز در موارد مجزا که برنامه از بخشی از API استفاده می‌کند که بعداً به دلایلی حذف می‌شود.

سازگاری فوروارد مهم است زیرا بسیاری از دستگاه‌های مجهز به اندروید به‌روزرسانی‌های سیستم را از طریق هوا (OTA) دریافت می‌کنند. ممکن است کاربر برنامه شما را نصب کند و با موفقیت از آن استفاده کند، سپس بعداً یک به‌روزرسانی OTA برای نسخه جدید پلتفرم Android دریافت کند. پس از نصب به‌روزرسانی، برنامه شما در یک نسخه زمان اجرا جدید از محیط اجرا می‌شود، اما نسخه‌ای که هنوز دارای API و قابلیت‌های سیستمی است که برنامه شما به آن وابسته است.

تغییرات زیر API، مانند تغییراتی که در خود سیستم اصلی وجود دارد، زمانی که برنامه شما در محیط جدید اجرا می شود، می تواند بر برنامه شما تأثیر بگذارد. برای شما، به عنوان توسعه‌دهنده برنامه، مهم است که بدانید برنامه در هر محیط سیستم چگونه ظاهر و رفتار می‌کند.

برای کمک به آزمایش برنامه خود بر روی نسخه‌های مختلف پلتفرم اندروید، Android SDK شامل چندین پلتفرم است که می‌توانید دانلود کنید. هر پلتفرم شامل یک تصویر سیستمی سازگار است که می توانید آن را در یک AVD برای آزمایش برنامه خود اجرا کنید.

سازگاری به عقب برنامه

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

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

اگرچه به احتمال زیاد دستگاه‌های مجهز به اندروید به نسخه قبلی پلتفرم تنزل داده نمی‌شوند، اما مهم است که بدانیم احتمالاً دستگاه‌های زیادی در این زمینه وجود دارند که نسخه‌های قبلی این پلتفرم را اجرا می‌کنند. حتی در میان دستگاه‌هایی که به‌روزرسانی‌های OTA را دریافت می‌کنند، برخی ممکن است تاخیر داشته باشند و ممکن است برای مدت زمان قابل توجهی به‌روزرسانی دریافت نکنند.

یک نسخه پلتفرم و سطح API را انتخاب کنید

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

شما می توانید با کامپایل کردن برنامه در برابر اهداف ساخت پایین تر، پایین ترین نسخه ممکن را تعیین کنید. پس از تعیین پایین ترین نسخه، با استفاده از نسخه پلتفرم مربوطه و سطح API، یک AVD ایجاد کنید و برنامه خود را به طور کامل آزمایش کنید. مطمئن شوید که ویژگی android:minSdkVersion در مانیفست برنامه اعلام کرده و مقدار آن را روی سطح API نسخه پلتفرم تنظیم کنید.

حداقل سطح API را اعلام کنید

اگر برنامه‌ای می‌سازید که از API یا ویژگی‌های سیستمی معرفی‌شده در آخرین نسخه پلتفرم استفاده می‌کند، ویژگی android:minSdkVersion را روی سطح API آخرین نسخه پلتفرم تنظیم کنید. این به این دلیل است که کاربران تنها در صورتی می توانند برنامه شما را نصب کنند که دستگاه های آنها از نسخه سازگار پلت فرم اندروید استفاده می کنند. به نوبه خود، این کمک می کند تا اطمینان حاصل شود که برنامه شما می تواند به درستی در دستگاه های خود عمل کند.

اگر برنامه شما از API های معرفی شده در آخرین نسخه پلتفرم استفاده می کند اما ویژگی android:minSdkVersion اعلام نمی کند، در دستگاه هایی که آخرین نسخه پلتفرم را اجرا می کنند به درستی اجرا می شود، اما در دستگاه هایی که نسخه های قبلی پلتفرم را دارند اجرا نمی شود . در حالت دوم، زمانی که برنامه سعی می کند از API هایی استفاده کند که در نسخه های قبلی وجود ندارند، در زمان اجرا از کار می افتد.

در برابر سطوح بالاتر API تست کنید

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

Android SDK شامل چندین نسخه پلتفرم است که می‌توانید از آن‌ها استفاده کنید، از جمله آخرین نسخه، و یک ابزار به‌روزرسانی ارائه می‌دهد که می‌توانید در صورت لزوم از آن برای دانلود نسخه‌های پلتفرم دیگر استفاده کنید.

برای دسترسی به به‌روزرسانی، از ابزار خط فرمان android ، واقع در فهرست <sdk>/tools استفاده کنید. با اجرای android sdk می توانید به روز رسانی SDK را راه اندازی کنید. همچنین می توانید روی فایل android.bat (ویندوز) یا android (OS X/Linux) دوبار کلیک کنید.

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

اسناد مرجع را بر اساس سطح API فیلتر کنید

صفحات اسناد مرجع پلتفرم Android یک کنترل "سطح API" را در قسمت بالا سمت چپ هر صفحه ارائه می دهند. بر اساس سطح API که در ویژگی android:minSdkVersion فایل مانیفست خود مشخص می‌کند، می‌توانید از کنترل برای نمایش اسناد فقط برای بخش‌هایی از API استفاده کنید که واقعاً در دسترس برنامه شما هستند.

برای استفاده از فیلتر کردن، سطح API مشخص شده توسط برنامه خود را از منو انتخاب کنید. سپس APIهایی که در سطح API بعدی معرفی می شوند خاکستری می شوند و محتوای آنها پوشانده می شود، زیرا برای برنامه شما قابل دسترسی نیستند.

فیلتر کردن بر اساس سطح API در اسناد، نمایی از آنچه در هر سطح API جدید یا معرفی شده است ارائه نمی دهد. این روشی را برای مشاهده کل API مرتبط با یک سطح API معین ارائه می کند، در حالی که عناصر API معرفی شده در سطوح API بعدی را حذف می کند.

برای بازگشت به مشاهده مستندات کامل، REL را در بالای منوی سطح API انتخاب کنید. به‌طور پیش‌فرض، فیلتر سطح API غیرفعال است، بنابراین می‌توانید API کامل چارچوب را بدون در نظر گرفتن سطح API مشاهده کنید.

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

Google Play از ویژگی‌های <uses-sdk> اعلام‌شده در مانیفست برنامه شما استفاده می‌کند تا برنامه شما را از دستگاه‌هایی که الزامات نسخه پلتفرم آن را برآورده نمی‌کنند فیلتر کند. قبل از تنظیم این ویژگی‌ها، مطمئن شوید که فیلترهای Google Play را می‌شناسید.

نحو:

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

موجود در:

<manifest>

توضیحات:

به شما امکان می دهد سازگاری یک برنامه کاربردی با یک یا چند نسخه از پلتفرم Android را با استفاده از یک عدد صحیح سطح API بیان کنید. سطح API بیان شده توسط یک برنامه با سطح API یک سیستم Android معین مقایسه می شود که می تواند در بین دستگاه های Android مختلف متفاوت باشد.

علیرغم نام آن، این عنصر برای تعیین سطح API استفاده می شود، نه شماره نسخه کیت توسعه نرم افزار (SDK) یا پلت فرم اندروید. سطح API همیشه یک عدد صحیح است. نمی‌توانید سطح API را از شماره نسخه Android مرتبط آن استخراج کنید. مثلاً با نسخه اصلی یا مجموع نسخه اصلی و فرعی یکی نیست.

همچنین سند مربوط به نسخه سازی برنامه های خود را بخوانید.

صفات:

android:minSdkVersion

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

احتیاط: اگر این ویژگی را اعلام نکنید، سیستم مقدار پیش‌فرض «1» را در نظر می‌گیرد که نشان می‌دهد برنامه شما با تمام نسخه‌های اندروید سازگار است. اگر اینطور نیست ، و شما minSdkVersion مناسب را اعلام نکرده اید، پس از نصب بر روی سیستمی با سطح API ناسازگار، برنامه در طول زمان اجرا هنگام تلاش برای دسترسی به APIهای غیرقابل دسترسی از کار می افتد. به همین دلیل، حتما سطح API مناسب را در ویژگی minSdkVersion اعلام کنید.

android:targetSdkVersion

یک عدد صحیح که سطح API مورد نظر برنامه را مشخص می کند. اگر تنظیم نشود، مقدار پیش فرض برابر با مقدار داده شده به minSdkVersion است.

این ویژگی به سیستم اطلاع می‌دهد که شما با نسخه هدف آزمایش کرده‌اید، و سیستم هیچ رفتار سازگاری را برای حفظ سازگاری رو به جلو برنامه شما با نسخه هدف فعال نمی‌کند. این برنامه همچنان می تواند در نسخه های پایین تر (تا minSdkVersion ) اجرا شود.

همانطور که اندروید با هر نسخه جدید تکامل می یابد، برخی از رفتارها و حتی ظاهر ممکن است تغییر کند. با این حال، اگر سطح API پلتفرم بالاتر از نسخه اعلام شده توسط targetSdkVersion برنامه شما باشد، سیستم می‌تواند رفتارهای سازگاری را فعال کند تا برنامه شما همانطور که انتظار دارید به کار خود ادامه دهد. می‌توانید با تعیین targetSdkVersion برای مطابقت با سطح API پلتفرمی که در آن اجرا می‌شود، چنین رفتارهای سازگاری را غیرفعال کنید.

برای مثال، تنظیم این مقدار روی «11» یا بالاتر به سیستم اجازه می‌دهد تا زمانی که در اندروید 3.0 یا بالاتر اجرا می‌شود، تم پیش‌فرض Holo را روی برنامه‌تان اعمال کند و همچنین حالت سازگاری صفحه‌نمایش را هنگام اجرا بر روی صفحه‌های بزرگ‌تر غیرفعال می‌کند، زیرا پشتیبانی از سطح API 11 به طور ضمنی پشتیبانی می‌کند. صفحه نمایش های بزرگتر

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

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

معرفی شده در: سطح API 4

android:maxSdkVersion

یک عدد صحیح که حداکثر سطح API را که برنامه برای اجرا در آن طراحی شده است را تعیین می کند.

در اندروید 1.5، 1.6، 2.0 و 2.0.1، سیستم مقدار این ویژگی را هنگام نصب یک برنامه و هنگام تأیید مجدد برنامه پس از به روز رسانی سیستم بررسی می کند. در هر صورت، اگر ویژگی maxSdkVersion برنامه کمتر از سطح API مورد استفاده خود سیستم باشد، سیستم به برنامه اجازه نصب نمی دهد. در صورت تأیید مجدد پس از به‌روزرسانی سیستم، این به طور مؤثر برنامه شما را از دستگاه حذف می‌کند.

برای نشان دادن اینکه چگونه این ویژگی می تواند بر برنامه شما پس از به روز رسانی سیستم تأثیر بگذارد، به مثال زیر توجه کنید:

برنامه ای که maxSdkVersion="5" در مانیفست خود اعلام می کند در Google Play منتشر شده است. کاربری که دستگاهش Android 1.6 (سطح API 4) را اجرا می کند، برنامه را دانلود و نصب می کند. پس از چند هفته، کاربر یک به‌روزرسانی سیستمی را به اندروید 2.0 (سطح API 5) دریافت می‌کند. پس از نصب به‌روزرسانی، سیستم maxSdkVersion برنامه را بررسی می‌کند و با موفقیت دوباره آن را تأیید می‌کند.

برنامه به طور معمول عمل می کند. با این حال، مدتی بعد، دستگاه به روز رسانی سیستم دیگری را دریافت می کند، این بار به اندروید 2.0.1 (سطح API 6). پس از به روز رسانی، سیستم دیگر نمی تواند برنامه را مجدداً تأیید کند زیرا سطح API خود سیستم (6) اکنون بالاتر از حداکثر پشتیبانی شده توسط برنامه (5) است. این سیستم از قابل مشاهده شدن برنامه برای کاربر جلوگیری می کند و در واقع آن را از دستگاه حذف می کند.

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

معرفی شده در: سطح API 4

برخی از نسخه‌های Android (فراتر از Android 2.0.1) ویژگی maxSdkVersion را در حین نصب یا تأیید مجدد بررسی یا اعمال نمی‌کنند. با این حال، گوگل پلی به استفاده از این ویژگی به عنوان فیلتر ادامه می دهد، با این حال، زمانی که برنامه های کاربردی موجود برای دانلود را به کاربران ارائه می دهد.

معرفی شده در:

API سطح 1

سطح API چیست؟

سطح API یک مقدار صحیح است که به طور منحصربه‌فرد ویرایش API چارچوب ارائه شده توسط نسخه‌ای از پلتفرم Android را شناسایی می‌کند.

پلتفرم اندروید یک چارچوب API ارائه می‌کند که برنامه‌ها می‌توانند از آن برای تعامل با سیستم اندروید زیرین استفاده کنند. چارچوب API شامل موارد زیر است:

• مجموعه ای اصلی از بسته ها و کلاس ها
• مجموعه ای از عناصر و ویژگی های XML برای اعلان یک فایل مانیفست
• مجموعه ای از عناصر و ویژگی های XML برای اعلام و دسترسی به منابع
• مجموعه ای از مقاصد
• مجموعه‌ای از مجوزهایی که برنامه‌ها می‌توانند درخواست کنند، و همچنین مجوزهای اجرایی موجود در سیستم

هر نسخه متوالی از پلتفرم Android می‌تواند شامل به‌روزرسانی‌هایی برای API چارچوب برنامه Android باشد که ارائه می‌کند.

به‌روزرسانی‌های چارچوب API به گونه‌ای طراحی شده‌اند که API جدید با نسخه‌های قبلی API سازگار باقی بماند. به این معنی که اکثر تغییرات در API افزودنی هستند و عملکردهای جدید یا جایگزین را معرفی می کنند. با ارتقاء بخش‌هایی از API، قطعات جایگزین قدیمی‌تر منسوخ می‌شوند اما حذف نمی‌شوند، بنابراین برنامه‌های موجود همچنان می‌توانند از آنها استفاده کنند.

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

چارچوب API که یک پلتفرم Android ارائه می‌کند با استفاده از یک شناسه عدد صحیح به نام سطح API مشخص می‌شود. هر نسخه پلتفرم Android دقیقاً از یک سطح API پشتیبانی می کند، اگرچه پشتیبانی برای تمام سطوح API قبلی (تا سطح API 1) ضمنی است. انتشار اولیه پلتفرم اندروید سطح 1 API را ارائه کرد و نسخه های بعدی سطح API را افزایش دادند.

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

استفاده از سطح API در اندروید

شناسه سطح API نقشی کلیدی در کمک به تضمین بهترین تجربه ممکن برای کاربران و توسعه دهندگان برنامه ایفا می کند:

• این به پلتفرم اندروید اجازه می‌دهد حداکثر ویرایش API چارچوبی را که پشتیبانی می‌کند، توصیف کند.
• این به برنامه‌ها اجازه می‌دهد تا ویرایش چارچوب API مورد نیاز خود را توصیف کنند.
• این به سیستم اجازه می‌دهد تا نصب برنامه‌ها را روی دستگاه کاربر مذاکره کند تا برنامه‌های ناسازگار با نسخه نصب نشوند.

هر نسخه پلتفرم اندروید شناسه سطح API خود را در داخل خود سیستم اندروید ذخیره می کند.

برنامه‌ها می‌توانند از عنصر مانیفست ارائه‌شده توسط چارچوب API— <uses-sdk> —برای توصیف حداقل و حداکثر سطوح API که می‌توانند تحت آن اجرا شوند و همچنین سطح API ترجیحی که برای پشتیبانی طراحی شده‌اند، استفاده کنند. این عنصر سه ویژگی کلیدی را ارائه می دهد:

• android:minSdkVersion : حداقل سطح API که برنامه قادر به اجرا در آن است. مقدار پیش فرض "1" است.
• android:targetSdkVersion : سطح API که برنامه برای اجرا در آن طراحی شده است. در برخی موارد، این به برنامه اجازه می‌دهد از عناصر یا رفتارهای مانیفست تعریف‌شده در سطح API هدف استفاده کند، نه اینکه فقط به استفاده از مواردی که برای حداقل سطح API تعریف شده‌اند محدود شود.
• android:maxSdkVersion : حداکثر سطح API که برنامه قادر به اجرا در آن است. مهم: قبل از استفاده از این ویژگی، اطلاعات مربوط به این ویژگی را در این صفحه بخوانید.

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

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

• اگر یک ویژگی android:minSdkVersion اعلام شود، مقدار آن کمتر یا برابر با عدد صحیح سطح API سیستم است. اگر اعلام نشود، سیستم فرض می کند که برنامه به سطح 1 API نیاز دارد.
• اگر یک ویژگی android:maxSdkVersion اعلام شود، مقدار آن برابر یا بیشتر از عدد صحیح سطح API سیستم است. اگر اعلام نشود، سیستم فرض می کند که برنامه حداکثر سطح API ندارد. توضیحات این ویژگی را برای اطلاعات بیشتر در مورد نحوه برخورد سیستم با آن بخوانید.

هنگامی که در مانیفست یک برنامه اعلام می شود، عنصر <uses-sdk> ممکن است به شکل زیر باشد:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

دلیل اصلی اینکه یک برنامه یک سطح API را در android:minSdkVersion اعلام می کند این است که به سیستم اندروید بگوید که از API هایی استفاده می کند که در سطح API مشخص شده معرفی شده اند.

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

ملاحظات توسعه

بخش های زیر اطلاعات مربوط به سطح API را ارائه می دهد که هنگام تهیه برنامه خود باید در نظر بگیرید.

سازگاری رو به جلو

برنامه های Android به طور کلی با نسخه های جدید پلت فرم Android سازگار هستند.

از آنجا که تقریباً تمام تغییرات در API چارچوب افزودنی هستند ، یک برنامه اندرویدی که با استفاده از هر نسخه خاص API ، همانطور که در سطح API مشخص شده است ، تهیه شده است ، با نسخه های بعدی پلت فرم Android و سطح API بالاتر سازگار است. این برنامه می تواند در تمام نسخه های بعدی پلت فرم Android اجرا شود ، به جز در موارد جدا شده که برنامه از بخشی از API استفاده می کند که بعداً به دلایلی حذف می شود.

سازگاری رو به جلو مهم است زیرا بسیاری از دستگاه های دارای قدرت اندرویدی به روزرسانی های سیستم بیش از حد هوا (OTA) را دریافت می کنند. کاربر ممکن است برنامه شما را نصب کرده و از آن با موفقیت استفاده کند ، سپس بعداً به روزرسانی OTA را به نسخه جدیدی از پلت فرم Android دریافت کنید. پس از نصب به روزرسانی ، برنامه شما در نسخه جدید اجرا از محیط اجرا می شود ، اما هنوز هم دارای قابلیت های API و سیستم است که برنامه شما به آن بستگی دارد.

تغییرات زیر API ، مانند مواردی که در سیستم اساسی خود هستند ، می توانند در هنگام اجرای آن در محیط جدید ، بر کاربرد شما تأثیر بگذارند. برای شما ، به عنوان توسعه دهنده برنامه ، برای درک چگونگی ظاهر و رفتار برنامه در هر محیط سیستم مهم است.

برای کمک به شما در آزمایش برنامه خود در نسخه های مختلف پلت فرم Android ، Android SDK شامل چندین سیستم عامل است که می توانید بارگیری کنید. هر سیستم عامل شامل یک تصویر سیستم سازگار است که می توانید در یک AVD برای آزمایش برنامه خود اجرا کنید.

سازگاری به عقب

برنامه های Android لزوماً با نسخه های پلت فرم Android قدیمی تر از نسخه ای که در مقابل آنها تهیه شده اند سازگار نیستند.

هر نسخه جدید از پلت فرم Android می تواند شامل API های جدید Framework باشد ، مانند مواردی که به برنامه های کاربردی دسترسی به قابلیت های جدید پلتفرم یا جایگزین کردن قطعات API موجود می دهد. API های جدید هنگام اجرای روی پلت فرم جدید و همچنین هنگام اجرای نسخه های بعدی این سیستم عامل ، در دسترس برنامه ها هستند ، همانطور که توسط سطح API مشخص شده است. اما از آنجا که نسخه های قبلی این سیستم عامل شامل API های جدید نیست ، برنامه هایی که از API های جدید استفاده می کنند نمی توانند روی آن سیستم عامل ها اجرا شوند.

اگرچه احتمالاً یک دستگاه اندرویدی به نسخه قبلی این سیستم عامل کاهش نمی یابد ، اما این مهم است که بدانیم احتمالاً دستگاه های زیادی در این زمینه وجود دارند که نسخه های قبلی این سیستم عامل را اجرا می کنند. حتی در بین دستگاه هایی که به روزرسانی های OTA را دریافت می کنند ، برخی ممکن است تاخیر داشته باشند و ممکن است برای مدت زمان قابل توجهی به روزرسانی دریافت نکنند.

یک نسخه پلتفرم و سطح API را انتخاب کنید

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

می توانید با تدوین برنامه در برابر اهداف ساخت پی در پی پایین ، کمترین نسخه ممکن را در پلتفرم تعیین کنید. بعد از تعیین کمترین نسخه ، با استفاده از نسخه پلت فرم مربوطه و سطح API AVD ایجاد کنید و برنامه خود را کاملاً آزمایش کنید. اطمینان حاصل کنید که android:minSdkVersion در مانیفست برنامه اعلام کرده و مقدار آن را در سطح API نسخه پلتفرم تنظیم کنید.

حداقل سطح API را اعلام کنید

اگر برنامه ای را ایجاد می کنید که از API یا ویژگی های سیستم معرفی شده در آخرین نسخه پلت فرم استفاده می کند ، ویژگی android:minSdkVersion به سطح API آخرین نسخه پلت فرم تنظیم کنید. این به گونه ای است که کاربران فقط قادر به نصب برنامه شما در صورتی هستند که دستگاه های آنها نسخه سازگار از پلت فرم Android را اجرا می کنند. به نوبه خود ، این امر به اطمینان از عملکرد برنامه شما به درستی در دستگاه های آنها کمک می کند.

اگر برنامه شما از API های معرفی شده در آخرین نسخه پلت فرم استفاده می کند اما یک ویژگی android:minSdkVersion اعلام نمی کند ، پس به درستی روی دستگاه هایی که آخرین نسخه از پلتفرم را اجرا می کنند ، اجرا می شود ، اما نه در دستگاه هایی که نسخه های قبلی این سیستم عامل را اجرا می کنند. در حالت دوم ، وقتی سعی می کند از API استفاده کند که در نسخه های قبلی وجود ندارد ، برنامه در زمان اجرا خراب می شود.

در برابر سطح API بالاتر آزمایش کنید

پس از تدوین برنامه خود ، حتماً آن را بر روی سیستم عامل مشخص شده در android:minSdkVersion Adptribute آزمایش کنید. برای انجام این کار ، یک AVD ایجاد کنید که از نسخه پلتفرم مورد نیاز برنامه شما استفاده کند. علاوه بر این ، برای بررسی سازگاری به جلو ، برنامه را در تمام سیستم عامل هایی که از سطح API بالاتر از آنچه که توسط برنامه شما استفاده می شود استفاده می کنند ، اجرا و آزمایش کنید.

Android SDK شامل چندین نسخه پلتفرم است که می توانید از آنها استفاده کنید ، از جمله آخرین نسخه ، و ابزاری به روزرسانی را ارائه می دهد که می توانید در صورت لزوم برای بارگیری سایر نسخه های پلتفرم استفاده کنید.

برای دسترسی به Updater ، از ابزار android Command-Line ، واقع در فهرست <sdk>/Tools استفاده کنید. می توانید SDK Updater را با اجرای android sdk راه اندازی کنید. همچنین می توانید روی پرونده android.bat (Windows) یا android (OS X/Linux) دوبار کلیک کنید.

برای اجرای برنامه خود در برابر نسخه های مختلف پلت فرم در شبیه ساز ، یک AVD را برای هر نسخه پلتفرم که می خواهید آزمایش کنید ایجاد کنید. برای اطلاعات بیشتر در مورد AVD ، به ایجاد و مدیریت دستگاه های مجازی مراجعه کنید. اگر از یک دستگاه فیزیکی برای آزمایش استفاده می کنید ، حتماً سطح API پلت فرم Android را که در آن اجرا می شود ، می شناسید. برای لیستی از نسخه های پلت فرم و سطح API آنها ، جدول این سند را مشاهده کنید.

مستندات مرجع را توسط سطح API فیلتر کنید

صفحات مستندات مرجع Android Platform یک کنترل "سطح API" را در منطقه سمت چپ بالا هر صفحه ارائه می دهد. شما می توانید بر اساس سطح API که در android:minSdkVersion از پرونده مانیفست آن ، از Control برای نمایش مستندات فقط برای بخش هایی از API که در واقع برای برنامه شما قابل دسترسی هستند استفاده کنید.

برای استفاده از فیلتر ، سطح API مشخص شده توسط برنامه خود را از منو انتخاب کنید. API های معرفی شده در سطح API بعدی سپس خاکستری می شوند و محتوای آنها نقاب می شود ، زیرا آنها در دسترس برنامه شما نیستند.

فیلتر توسط سطح API در مستندات نمایی از آنچه در هر سطح API جدید یا معرفی شده است ، ارائه نمی دهد. این راهی برای مشاهده کل API مرتبط با سطح API داده شده فراهم می کند ، در حالی که به استثنای عناصر API معرفی شده در سطح API بعدی.

برای بازگشت به مشاهده مستندات کامل ، در بالای منوی سطح API ، Rel را انتخاب کنید. به طور پیش فرض ، فیلتر سطح API غیرفعال است ، به طوری که می توانید بدون توجه به سطح API ، API Full Framework را مشاهده کنید.

مستندات مرجع برای عناصر API فردی سطح API را که در آن هر عنصر معرفی می شود ، مشخص می کند. سطح API برای بسته ها و کلاس ها به عنوان "اضافه شده در سطح API" در گوشه بالا سمت راست منطقه محتوا در هر صفحه اسناد مشخص شده است. سطح API برای اعضای کلاس در هدر توضیحات مفصل آنها ، در حاشیه سمت راست مشخص شده است.