Общие сведения об уровнях API Android

Статья
03/08/2024

Xamarin.Android имеет несколько параметров уровня API Android, определяющих совместимость приложения с несколькими версиями Android. В этом руководстве объясняется, что такое параметры означают, как настроить их и какие последствия они влияют на приложение во время выполнения.

Быстрое начало работы

Xamarin.Android предоставляет три параметра проекта уровня API Android:

Целевая платформа — указывает, какую платформу следует использовать при создании приложения. Этот уровень API используется во время компиляции Xamarin.Android.
Минимальная версия Android — указывает старую версию Android, которую вы хотите поддерживать. Этот уровень API используется во время выполнения Android.
Целевая версия Android — указывает версию Android, в которую должно работать ваше приложение. Этот уровень API используется во время выполнения Android.

Прежде чем настроить уровень API для проекта, необходимо установить компоненты платформы SDK для этого уровня API. Дополнительные сведения о скачивании и установке компонентов пакета SDK для Android см. в разделе "Настройка пакета SDK для Android".

Примечание.

Начиная с августа 2021 года консоль Google Play требует, чтобы новые приложения предназначены для API уровня 30 (Android 11.0) или более поздней версии. Существующие приложения необходимы для целевого уровня API 30 или выше, начиная с ноября 2021 года. Дополнительные сведения см. в разделе "Требования к уровню целевого API" для консоли воспроизведения в разделе "Создание и настройка приложения" в документации по консоли воспроизведения.

Visual Studio
Visual Studio для Mac

Как правило, для всех трех уровней API Xamarin.Android задано одно и то же значение. На странице приложения задайте для компиляции версию Android (Target Framework) последнюю стабильную версию API (или, как минимум, до версии Android, которая содержит все необходимые функции). На следующем снимке экрана целевая платформа имеет значение Android 7.1 (уровень API 25 — Nougat):<

На странице манифеста Android задайте минимальную версию Android для компиляции с помощью пакета SDK и задайте для целевой версии Android то же значение, что и версия Target Framework (на следующем снимке экрана целевая платформа Android имеет значение Android 7.1 (Nougat)):

Если вы хотите обеспечить обратную совместимость с более ранней версией Android, установите минимальную версию Android, чтобы она соответствовала старой версии Android, которую требуется поддерживать ваше приложение. (Обратите внимание, что уровень API 14 является минимальным уровнем API, необходимым для Службы Google Play и поддержка Firebase.) В следующем примере конфигурации поддерживаются версии Android с уровня 14 по уровень API 25:

Если приложение поддерживает несколько версий Android, код должен включать проверка среды выполнения, чтобы убедиться, что приложение работает с параметром минимальной версии Android (см. сведения о проверках среды выполнения для версий Android ниже). Если вы используете или создаете библиотеку, ознакомьтесь со следующими рекомендациями по настройке параметров уровня API для библиотек.

Версии Android и уровни API

По мере развития платформы Android и выпуска новых версий Android каждая версия Android назначается уникальным целым идентификатором, называемым уровнем API. Поэтому каждая версия Android соответствует одному уровню API Android. Так как пользователи устанавливают приложения на старые, а также самые последние версии Android, приложения Android реального мира должны быть разработаны для работы с несколькими уровнями API Android.

Версии Android

Каждый выпуск Android проходит по нескольким именам:

Версия Android, например Android 9.0
Имя кода (или десерта), например Pie
Соответствующий уровень API, например уровень API 28

Имя кода Android может соответствовать нескольким версиям и уровням API (как показано в таблице ниже), но каждая версия Android соответствует ровно одному уровню API.

Кроме того, Xamarin.Android определяет коды версий сборки, которые сопоставляют с текущими известными уровнями API Android. В следующей таблице можно преобразовать код версии API, версию Android, имя кода и код сборки Xamarin.Android (коды версий сборки определяются в Android.OS пространстве имен):

Имя.	Версия	Уровень API	Выпущено	Код версии сборки
К	10.0	29	Авг 2020	`BuildVersionCodes.Q`
Круговая	9.0	28	Авг-2018	`BuildVersionCodes.P`
Oreo	8.1	27	Дек 2017	`BuildVersionCodes.OMr1`
Oreo	8.0	26	Авг 2017	`BuildVersionCodes.O`
Nougat	7.1	25	Декабрь 2016 г.	`BuildVersionCodes.NMr1`
Nougat	7.0	24	Август 2016 г.	`BuildVersionCodes.N`
Marshmallow	6,0	23	Август 2015 г.	`BuildVersionCodes.M`
Lollipop	5.1	22	Мар 2015 г.	`BuildVersionCodes.LollipopMr1`
Lollipop	5,0	21	Ноя 2014	`BuildVersionCodes.Lollipop`
Kitkat Watch	4.4W	20	Июн 2014	`BuildVersionCodes.KitKatWatch`
Kitkat	4.4.	19	Октябрь 2013 г.	`BuildVersionCodes.KitKat`
Желе-боб	4.3	18	Июл 2013	`BuildVersionCodes.JellyBeanMr2`
Желе-боб	4.2-4.2.2	17	Ноябрь 2012 г.	`BuildVersionCodes.JellyBeanMr1`
Желе-боб	4.1-4.1.1	16	Июнь 2012 г.	`BuildVersionCodes.JellyBean`
Ice Cream Sandwich	4.0.3-4.0.4	15	Декабрь 2011 г.	`BuildVersionCodes.IceCreamSandwichMr1`
Ice Cream Sandwich	4.0-4.0.2	14	Окт 2011	`BuildVersionCodes.IceCreamSandwich`
Соты	3.2	13	Июнь 2011 г.	`BuildVersionCodes.HoneyCombMr2`
Соты	3.1.x	12	Май 2011 г.	`BuildVersionCodes.HoneyCombMr1`
Соты	3.0.x	11	Февраль 2011 г.	`BuildVersionCodes.HoneyComb`
Пряник	2.3.3-2.3.4	10	Февраль 2011 г.	`BuildVersionCodes.GingerBreadMr1`
Пряник	2.3-2.3.2	9	Ноя 2010	`BuildVersionCodes.GingerBread`
Froyo	2.2.x	8	Июнь 2010 г.	`BuildVersionCodes.Froyo`
Eclair	2.1.x	7	янв 2010	`BuildVersionCodes.EclairMr1`
Eclair	2.0.1	6	Декабрь 2009 г.	`BuildVersionCodes.Eclair01`
Eclair	2.0	5	Ноябрь 2009 г.	`BuildVersionCodes.Eclair`
Кольцо	1,6	4	Сентябрь 2009 г.	`BuildVersionCodes.Donut`
Кекс	1.5	3	Май 2009 г.	`BuildVersionCodes.Cupcake`
База	1,1	2	Февраль 2009 г.	`BuildVersionCodes.Base11`
База	1.0	1	Октябрь 2008 г.	`BuildVersionCodes.Base`

Как указано в этой таблице, новые версии Android выпускаются часто — иногда более одного выпуска в год. В результате вселенная устройств Android, которые могут запускать приложение, включает в себя широкий спектр старых и новых версий Android. Как вы можете гарантировать, что ваше приложение будет работать согласованно и надежно на столь разных версиях Android? Уровни API Android помогут вам решить эту проблему.

Уровни API Android

Каждое устройство Android выполняется на одном уровне API. Этот уровень API гарантированно будет уникальным для каждой версии платформы Android. Уровень API точно определяет версию набора API, в которую приложение может вызываться; Он определяет сочетание элементов манифеста, разрешений и т. д. код для разработчика. Система уровней API Android помогает Android определить, совместимо ли приложение с системным образом Android перед установкой приложения на устройстве.

При создании приложения он содержит следующие сведения об уровне API:

Целевой уровень API Android, на который будет создано приложение.
Минимальный уровень API Android, который должен быть запущен устройством Android.

Эти параметры используются для обеспечения правильности работы приложения на устройстве Android во время установки. Если нет, приложение заблокировано на этом устройстве. Например, если уровень API устройства Android ниже минимального уровня API, указанного для приложения, устройство Android не позволит пользователю устанавливать приложение.

Параметры уровня API проекта

В следующих разделах объясняется, как использовать диспетчер SDK для подготовки среды разработки к целевым уровням API, а также подробные объяснения настройки целевой платформы, минимальной версии Android и параметров целевой версии Android в Xamarin.Android.

Платформы пакета SDK для Android

Прежде чем выбрать уровень целевого или минимального API в Xamarin.Android, необходимо установить версию платформы ПАКЕТА SDK для Android, соответствующую уровню API. Диапазон доступных вариантов для Целевой платформы, минимальной версии Android и целевой версии Android ограничен диапазоном установленных версий пакета SDK для Android. Диспетчер SDK можно использовать для проверки того, установлены ли необходимые версии пакета SDK для Android, и его можно использовать для добавления новых уровней API, необходимых для приложения. Если вы не знакомы с установкой уровней API, см . статью "Настройка пакета SDK для Android".

Целевая платформа

Целевая платформа (также известная как compileSdkVersion) — это конкретная версия платформы Android (уровень API), для которую приложение компилируется во время сборки. Этот параметр указывает, какие API приложение ожидает использовать при выполнении, но не влияет на то, какие API фактически доступны приложению при его установке. В результате изменение параметра Target Framework не изменяет поведение среды выполнения.

Целевая платформа определяет, какие версии библиотеки связаны с приложением. Этот параметр определяет, какие API можно использовать в приложении. Например, если вы хотите использовать метод NotificationBuilder.SetCategory , который был представлен в Android 5.0 Lollipop, необходимо задать target Framework уровень 21 (Lollipop) или более поздней версии. Если вы настроите целевую платформу проекта на уровень API, например уровень API 19 (KitKat) и попытаетесь вызвать SetCategory метод в коде, вы получите ошибку компиляции.

Рекомендуется всегда компилировать последнюю доступную версию Target Framework. Это обеспечивает полезные предупреждения для любых устаревших API, которые могут вызываться кодом. Использование последней версии Target Framework особенно важно при использовании последних выпусков библиотеки поддержки. Каждая библиотека ожидает, что ваше приложение будет скомпилировано на минимальном уровне API библиотеки поддержки или выше.

Visual Studio
Visual Studio для Mac

Чтобы получить доступ к параметру Target Framework в Visual Studio, откройте свойства проекта в Обозреватель решений и выберите страницу приложения:

Задайте целевую платформу, выбрав уровень API в раскрывающемся меню в разделе Компиляция с помощью версии Android, как показано выше.

Минимальная версия Android

Минимальная версия Android (также известная как minSdkVersion) является самой старой версией ОС Android (т. е. наименьшим уровнем API), которая может устанавливать и запускать приложение. По умолчанию приложение можно установить только на устройствах, соответствующих параметру Целевой платформы или выше; Если минимальный параметр версии Android меньше параметра Target Framework, приложение также может работать в более ранних версиях Android. Например, если для Целевой платформы задано значение Android 7.1 (Nougat) и задана минимальная версия Android 4.0.3 (Ice Cream Sandwich), ваше приложение можно установить на любой платформе с уровня API 15 до уровня API 25 включительно.

Хотя ваше приложение может успешно создавать и устанавливать на этих платформах, это не гарантирует успешное выполнение на всех этих платформах. Например, если приложение установлено в Android 5.0 (Lollipop) и код вызывает API, доступный только в Android 7.1 (Nougat) и более поздней версии, ваше приложение получит ошибку среды выполнения и, возможно, сбой. Поэтому код должен гарантировать, что во время выполнения он вызывает только те API, которые поддерживаются устройством Android, на котором он работает. Другими словами, код должен включать явные проверка среды выполнения, чтобы обеспечить, чтобы приложение использовало более новые API только на устройствах, которые достаточно недавно поддерживают их. Проверки среды выполнения для версий Android, далее в этом руководстве объясняется, как добавить эти проверка среды выполнения в код.

Visual Studio
Visual Studio для Mac

Чтобы получить доступ к параметру минимальной версии Android в Visual Studio, откройте свойства проекта в Обозреватель решений и выберите страницу манифеста Android. В раскрывающемся меню в разделе "Минимальная версия Android" можно выбрать минимальную версию Android для приложения:

Если выбрать команду "Использовать компиляцию с помощью пакета SDK", минимальная версия Android будет совпадать с параметром Target Framework.

Целевая версия Android

Целевая версия Android (также известная как targetSdkVersion) — это уровень API устройства Android, где приложение ожидает запуска. Android использует этот параметр, чтобы определить, следует ли включить любое поведение совместимости. Это гарантирует, что ваше приложение продолжает работать так, как вы ожидаете. Android использует целевой параметр версии Android для определения того, какие изменения поведения можно применить к приложению, не нарушая его (это то, как Android обеспечивает прямую совместимость).

Целевая платформа и целевая версия Android, имея очень похожие имена, не совпадают. Параметр Target Framework передает сведения о уровне целевого API Xamarin.Android для использования во время компиляции, в то время как целевая версия Android передает сведения о целевом уровне API в Android для использования во время выполнения (когда приложение установлено и запущено на устройстве).

Visual Studio
Visual Studio для Mac

Чтобы получить доступ к этому параметру в Visual Studio, откройте свойства проекта в Обозреватель решений и выберите страницу манифеста Android. В раскрывающемся меню в разделе "Целевая версия Android" можно выбрать целевую версию Android для приложения:

Мы рекомендуем явно установить целевую версию Android на последнюю версию Android, которую вы используете для тестирования приложения. В идеале оно должно быть установлено в последнюю версию пакета SDK для Android. Это позволяет использовать новые API перед выполнением изменений в поведении. Для большинства разработчиков не рекомендуется устанавливать целевую версию Android для использования компиляции с помощью версии ПАКЕТА SDK.

Как правило, целевая версия Android должна быть привязана минимальной версией Android и целевой платформой. Это означает следующее.

Минимальная версия Android = целевая версия <Android = целевая платформа <

Дополнительные сведения об уровнях sdk см. в документации разработчика android, использующего пакет SDK .

Проверка среды выполнения для версий Android

По мере выпуска каждой новой версии Android API платформы обновляется для предоставления новых или заменных функций. За исключением нескольких исключений, функции API из предыдущих версий Android переносились в более новые версии Android без изменений. В результате, если приложение работает на определенном уровне API Android, обычно оно сможет работать на более позднем уровне API Android без изменений. Но что делать, если вы также хотите запустить приложение в более ранних версиях Android?

Если выбрать минимальную версию Android, которая ниже целевой платформы, некоторые API могут быть недоступны для приложения во время выполнения. Однако ваше приложение по-прежнему может работать на более ранних устройствах, но с ограниченными возможностями. Для каждого API, недоступного на платформах Android, соответствующих параметру минимальной версии Android, код должен явно проверка значение Android.OS.Build.VERSION.SdkInt свойства, чтобы определить уровень API платформы, на которую работает приложение. Если уровень API ниже минимальной версии Android, поддерживающей API, которую вы хотите вызвать, код должен найти способ правильной работы без вызова этого API.

Например, предположим, что мы хотим использовать метод NotificationBuilder.SetCategory для классификации уведомлений при запуске в Android 5.0 Lollipop (и более поздних версиях), но мы по-прежнему хотим, чтобы наше приложение работало на более ранних версиях Android, таких как Android 4.1 Jelly Bean (где SetCategory недоступно). Ссылаясь на таблицу версий Android в начале этого руководства, мы видим, что код версии сборки для Android 5.0 Lollipop является Android.OS.BuildVersionCodes.Lollipop. Чтобы поддерживать более старые версии Android, где SetCategory недоступно, наш код может обнаружить уровень API во время выполнения и условно вызывать SetCategory только в том случае, если уровень API больше или равен коду версии сборки Lollipop:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

В этом примере целевая платформа нашего приложения имеет значение Android 5.0 (уровень API 21), а ее минимальная версия Android имеет значение Android 4.1 (уровень API 16). Так как SetCategory этот код доступен на уровне API и более поздних версийAndroid.OS.BuildVersionCodes.Lollipop, этот пример кода будет вызываться только в том случае, если он фактически доступен, он не будет пытаться вызывать SetCategorySetCategory, если уровень API равен 16, 17, 18, 19 или 20. Эти более ранние версии Android сокращаются только в том объеме, в котором уведомления отсортированы неправильно (так как они не классифицируются по типу), но уведомления по-прежнему публикуются для оповещения пользователя. Наше приложение по-прежнему работает, но его функциональность немного уменьшается.

Как правило, версия сборки проверка помогает вашему коду решать во время выполнения между тем, что-то новое и старое. Например:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

Нет быстрого и простого правила, объясняющего, как уменьшить или изменить функциональные возможности приложения при запуске в более старых версиях Android, которые не имеют одного или нескольких API. В некоторых случаях (например, в SetCategory приведенном выше примере), достаточно опустить вызов API, если он недоступен. Однако в других случаях может потребоваться реализовать альтернативные функциональные возможности, если Android.OS.Build.VERSION.SdkInt обнаруживается меньше уровня API, который требуется вашему приложению для оптимального взаимодействия.

При создании проекта библиотеки Xamarin.Android (например, библиотеки классов или библиотеки привязок) можно настроить только параметр Target Framework — минимальная версия Android и параметры версии Target Android недоступны. Это связано с отсутствием страницы манифеста Android:

Минимальные параметры версии Android и целевой версии Android недоступны, так как результирующая библиотека не является автономным приложением. Библиотека может быть запущена в любой версии Android в зависимости от приложения, с которым оно упаковано. Вы можете указать способ компиляции библиотеки, но вы не можете предсказать, на каком уровне API платформы будет выполняться библиотека. Учитывая это, при использовании или создании библиотек следует учитывать следующие рекомендации.

При использовании библиотеки Android — если вы используете библиотеку Android в приложении, обязательно задайте для целевой платформы приложения уровень API, который по крайней мере равен параметру Target Framework целевой платформы.
При создании библиотеки Android — если вы создаете библиотеку Android для использования другими приложениями, обязательно задайте для целевой платформы минимальный уровень API, который требуется для компиляции.

Эти рекомендации помогут предотвратить ситуацию, когда библиотека пытается вызвать API, который недоступен во время выполнения (что может привести к сбою приложения). Если вы являетесь разработчиком библиотеки, необходимо ограничить использование вызовов API небольшим и хорошо установленным подмножеством общей области поверхности API. Это помогает обеспечить безопасное использование библиотеки в более широком диапазоне версий Android.

Итоги

В этом руководстве объясняется, как уровни API Android используются для управления совместимостью приложений в разных версиях Android. В ней приведены подробные инструкции по настройке параметров проекта версии Xamarin.Android Target Framework, минимальной версии Android и целевой версии Android. В ней приведены инструкции по использованию диспетчера ПАКЕТОВ SDK для Android для установки пакетов SDK, в том числе примеры написания кода для работы с различными уровнями API во время выполнения, а также объясняется, как управлять уровнями API при создании или использовании библиотек Android. Он также предоставляет полный список, который связывает уровни API с номерами версий Android (например, Android 4.4), именами версий Android (например, Kitkat) и кодами версий сборки Xamarin.Android.