Principy úrovní rozhraní ANDROID API
Xamarin.Android má několik nastavení na úrovni rozhraní ANDROID API, která určují kompatibilitu vaší aplikace s několika verzemi Androidu. Tato příručka vysvětluje, co tato nastavení znamenají, jak je nakonfigurovat a jaký vliv mají na vaši aplikaci za běhu.
Rychlý start
Xamarin.Android zveřejňuje tři nastavení projektu na úrovni rozhraní ANDROID API:
Cílová architektura – Určuje, která architektura se má použít při sestavování aplikace. Tato úroveň rozhraní API se používá v době kompilace xamarin.Android.
Minimální verze Androidu – Určuje nejstarší verzi Androidu, kterou má vaše aplikace podporovat. Tato úroveň rozhraní API se používá v době běhu v Androidu.
Cílová verze Androidu – Určuje verzi Androidu, na které má vaše aplikace běžet. Tato úroveň rozhraní API se používá v době běhu v Androidu.
Než budete moct pro svůj projekt nakonfigurovat úroveň rozhraní API, musíte pro danou úroveň rozhraní API nainstalovat komponenty platformy sady SDK. Další informace o stahování a instalaci komponent sady Android SDK naleznete v tématu Instalace sady Android SDK.
Poznámka:
Od srpna 2021 vyžaduje konzola Google Play, aby nové aplikace cílové rozhraní API úrovně 30 (Android 11.0) nebo vyšší. Stávající aplikace se od listopadu 2021 vyžadují pro cílovou úroveň rozhraní API 30 nebo vyšší. Další informace najdete v tématu Požadavky na úroveň cílového rozhraní API pro konzolu Play v části Vytvoření a nastavení aplikace v dokumentaci ke konzole Play.
Za normálních okolností jsou všechny tři úrovně rozhraní API Xamarin.Android nastaveny na stejnou hodnotu. Na stránce Aplikace nastavte možnost Zkompilovat pomocí verze Androidu (cílová architektura) na nejnovější stabilní verzi rozhraní API (nebo minimálně na verzi Androidu, která má všechny funkce, které potřebujete). Na následujícím snímku obrazovky je cílová architektura nastavená na Android 7.1 (API Level 25 – Nougat):
Na stránce manifestu Androidu nastavte minimální verzi Androidu na použití kompilátoru pomocí verze sady SDK a nastavte cílovou verzi Androidu na stejnou hodnotu jako verze cílové architektury (na následujícím snímku obrazovky je cílová verze Android Framework nastavená na Android 7.1 (Nougat)):
Pokud chcete zachovat zpětnou kompatibilitu se starší verzí Androidu, nastavte minimální verzi Androidu tak, aby cílila na nejstarší verzi Androidu, kterou má vaše aplikace podporovat. (Všimněte si, že úroveň rozhraní API 14 je minimální požadovaná úroveň rozhraní API pro Služby Google Play a podpora Firebase.) Následující příklad konfigurace podporuje verze Androidu z rozhraní API úrovně 14 až API úrovně 25:
Pokud vaše aplikace podporuje více verzí Androidu, musí váš kód obsahovat kontroly za běhu, aby se zajistilo, že vaše aplikace funguje s nastavením minimální verze Androidu (podrobnosti najdete v části Kontroly modulu runtime pro verze Androidu níže). Pokud knihovnu využíváte nebo vytváříte, přečtěte si níže uvedené úrovně rozhraní API a knihovny , kde najdete osvědčené postupy při konfiguraci nastavení na úrovni rozhraní API pro knihovny.
Verze Androidu a úrovně rozhraní API
S vývojem platformy Android a vydáním nových verzí Androidu je každá verze Androidu přiřazena jedinečnému celočíselnému identifikátoru , kterému se říká úroveň rozhraní API. Každá verze Androidu proto odpovídá jedné úrovni rozhraní ANDROID API. Vzhledem k tomu, že uživatelé instalují aplikace na starší i nejnovější verze Androidu, musí být aplikace pro Android navržené tak, aby fungovaly s několika úrovněmi rozhraní ANDROID API.
Verze Androidu
Každá verze Androidu má více názvů:
- Verze Androidu, například Android 9.0
- Název kódu (nebo dezertu), například výsečový
- Odpovídající úroveň rozhraní API, například úroveň rozhraní API 28
Název kódu Androidu může odpovídat více verzím a úrovním rozhraní API (jak je vidět v následující tabulce), ale každá verze Androidu odpovídá přesně jedné úrovni rozhraní API.
Kromě toho Xamarin.Android definuje kódy verzí sestavení, které se mapují na aktuálně známé úrovně rozhraní Android API. Následující tabulka vám pomůže přeložit mezi úrovní rozhraní API, verzí Androidu, názvem kódu a kódem verze sestavení Xamarin.Android (kódy verzí sestavení jsou definovány v Android.OS oboru názvů):
| Název | Verze | Úroveň rozhraní API | Vydáno | Kód verze sestavení |
|---|---|---|---|---|
| Q | 10.0 | 29 | 2020 | BuildVersionCodes.Q |
| Výsečový | 9.0 | 28 | Srpen 2018 | BuildVersionCodes.P |
| Oreo | 8.1 | 27 | Prosinec 2017 | BuildVersionCodes.OMr1 |
| Oreo | 8.0 | 26 | 2017 | BuildVersionCodes.O |
| Nugát | 7.1 | 25 | Prosinec 2016 | BuildVersionCodes.NMr1 |
| Nugát | 7.0 | 24 | 2016 | BuildVersionCodes.N |
| Marshmallow | 6.0 | 23 | 2015 | BuildVersionCodes.M |
| Lízátko | 5,1 | 22 | Bře 2015 | BuildVersionCodes.LollipopMr1 |
| Lízátko | 5,0 | 21 | Nov 2014 | BuildVersionCodes.Lollipop |
| Kitkat Watch | 4.4W | 20 | Červen 2014 | BuildVersionCodes.KitKatWatch |
| Kitkat | 4.4 | 19 | Října 2013 | BuildVersionCodes.KitKat |
| Želé Bean | 4.3 | 18 | Červenec 2013 | BuildVersionCodes.JellyBeanMr2 |
| Želé Bean | 4.2-4.2.2 | 17 | Listopad 2012 | BuildVersionCodes.JellyBeanMr1 |
| Želé Bean | 4.1-4.1.1 | 16 | Červen 2012 | BuildVersionCodes.JellyBean |
| Ice Cream Sandwich | 4.0.3-4.0.4 | 15 | Prosinec 2011 | BuildVersionCodes.IceCreamSandwichMr1 |
| Ice Cream Sandwich | 4.0-4.0.2 | 14 | Říj 2011 | BuildVersionCodes.IceCreamSandwich |
| Plástev | 3.2 | 13 | Červen 2011 | BuildVersionCodes.HoneyCombMr2 |
| Plástev | 3.1.x | 12 | Květen 2011 | BuildVersionCodes.HoneyCombMr1 |
| Plástev | 3.0.x | 11 | Únor 2011 | BuildVersionCodes.HoneyComb |
| Perník | 2.3.3-2.3.4 | 10 | Únor 2011 | BuildVersionCodes.GingerBreadMr1 |
| Perník | 2.3-2.3.2 | 9 | Listopad 2010 | BuildVersionCodes.GingerBread |
| Froyo | 2.2.x | 8 | Červen 2010 | BuildVersionCodes.Froyo |
| Eklair | 2.1.x | 7 | Jan 2010 | BuildVersionCodes.EclairMr1 |
| Eklair | 2.0.1 | 6 | Prosinec 2009 | BuildVersionCodes.Eclair01 |
| Eklair | 2.0 | 5 | Listopad 2009 | BuildVersionCodes.Eclair |
| Kobliha | 1.6 | 4 | Zář 2009 | BuildVersionCodes.Donut |
| Košíček | 1.5 | 3 | Květen 2009 | BuildVersionCodes.Cupcake |
| Základ | 1,1 | 2 | Únor 2009 | BuildVersionCodes.Base11 |
| Základ | 1.0 | 0 | Října 2008 | BuildVersionCodes.Base |
Jak tato tabulka uvádí, nové verze Androidu se vydávají často – někdy více než jedno vydání za rok. Výsledkem je, že vesmír zařízení s Androidem, která můžou vaši aplikaci spouštět, zahrnuje širokou škálu starších a novějších verzí Androidu. Jak můžete zaručit, že vaše aplikace bude spouštět konzistentně a spolehlivě na tolik různých verzích Androidu? Tyto potíže vám můžou pomoct úrovně rozhraní API androidu.
Úrovně rozhraní API Androidu
Každé zařízení s Androidem běží na přesně jedné úrovni rozhraní API – tato úroveň rozhraní API je zaručená jedinečná pro každou verzi platformy Android. Úroveň rozhraní API přesně identifikuje verzi sady rozhraní API, do které může vaše aplikace volat; identifikuje kombinaci prvků manifestu, oprávnění atd. kóduje jako vývojář. Systém rozhraní API androidu pomáhá Systému Android určit, jestli je aplikace kompatibilní se systémovou imagí Androidu před instalací aplikace na zařízení.
Při vytváření aplikace obsahuje následující informace na úrovni rozhraní API:
Cílová úroveň rozhraní API androidu, na které je aplikace vytvořená, aby běžela.
Minimální úroveň rozhraní Android API, kterou zařízení s Androidem musí mít ke spuštění vaší aplikace.
Tato nastavení slouží k zajištění správné dostupnosti funkcí potřebných ke správnému spuštění aplikace na zařízení s Androidem v době instalace. Pokud ne, aplikace se na daném zařízení nespouštět. Pokud je například úroveň rozhraní API zařízení s Androidem nižší než minimální úroveň rozhraní API, kterou pro aplikaci zadáte, zabrání zařízení s Androidem uživateli v instalaci aplikace.
Nastavení na úrovni rozhraní Project API
Následující části vysvětlují, jak pomocí Správce sady SDK připravit vývojové prostředí na úrovně rozhraní API, na které chcete cílit, a podrobně vysvětluje, jak nakonfigurovat cílovou architekturu, minimální verzi Androidu a nastavení cílové verze Androidu v Xamarin.Androidu.
Platformy Android SDK
Než budete moct vybrat cílovou nebo minimální úroveň rozhraní API v Xamarin.Androidu, musíte nainstalovat verzi platformy Sady Android SDK, která odpovídá této úrovni rozhraní API. Rozsah dostupných možností pro cílovou architekturu, minimální verzi Androidu a cílovou verzi Androidu je omezený na rozsah nainstalovaných verzí sady Android SDK. Pomocí Správce sady SDK můžete ověřit, jestli jsou nainstalované požadované verze sady Android SDK, a můžete ho použít k přidání všech nových úrovní rozhraní API, které potřebujete pro vaši aplikaci. Pokud nevíte, jak nainstalovat úrovně rozhraní API, přečtěte si téma Instalace sady Android SDK.
Cílová architektura
Cílová architektura (označovaná také jakocompileSdkVersion) je konkrétní verze rozhraní Android Framework (úroveň rozhraní API), pro kterou je vaše aplikace zkompilována v době sestavení. Toto nastavení určuje, která rozhraní API vaše aplikace očekává při spuštění, ale nemá žádný vliv na to, která rozhraní API jsou ve skutečnosti dostupná pro vaši aplikaci při instalaci. V důsledku toho změna nastavení cílové architektury nezmění chování modulu runtime.
Cílová architektura identifikuje, které verze knihovny je vaše aplikace propojená – toto nastavení určuje, která rozhraní API můžete ve své aplikaci použít. Pokud například chcete použít metodu NotificationBuilder.SetCategory , která byla zavedena v Androidu 5.0 Lollipop, musíte nastavit cílovou architekturu na úroveň ROZHRANÍ API 21 (Lollipop) nebo novější. Pokud nastavíte cílovou architekturu projektu na úroveň rozhraní API, jako je api level 19 (KitKat) a pokusíte se volat metodu SetCategory v kódu, zobrazí se chyba kompilace.
Doporučujeme vždy zkompilovat nejnovější dostupnou verzi cílové architektury. To vám poskytne užitečné zprávy s upozorněním pro všechna zastaralá rozhraní API, která by mohla být volána vaším kódem. Použití nejnovější verze cílové architektury je zvlášť důležité, pokud používáte nejnovější verze knihovny podpory – každá knihovna očekává, že se vaše aplikace zkompiluje na minimální nebo vyšší úrovni rozhraní API této knihovny podpory.
Pokud chcete získat přístup k nastavení cílové architektury v sadě Visual Studio, otevřete vlastnosti projektu v Průzkumník řešení a vyberte stránku Aplikace:
Nastavte cílovou architekturu výběrem úrovně rozhraní API v rozevírací nabídce v části Zkompilovat pomocí verze Androidu, jak je znázorněno výše.
Minimální verze Androidu
Minimální verze Androidu (označovaná také jako minSdkVersion) je nejstarší verze operačního systému Android (tj. nejnižší úroveň rozhraní API), která může nainstalovat a spustit vaši aplikaci. Ve výchozím nastavení je možné aplikaci nainstalovat jenom na zařízení, která odpovídají nastavení cílové architektury nebo vyšší. Pokud je nastavení minimální verze Androidu nižší než nastavení cílové architektury, může aplikace běžet i ve starších verzích Androidu. Pokud například nastavíte cílovou architekturu na Android 7.1 (Nougat) a nastavíte minimální verzi Androidu na Android 4.0.3 (Ice Cream Sandwich), můžete aplikaci nainstalovat na libovolnou platformu z rozhraní API úrovně 15 na úroveň 25 včetně.
I když se vaše aplikace může úspěšně sestavit a nainstalovat na tuto řadu platforem, nezaručuje, že se úspěšně spustí na všech těchto platformách. Pokud je například vaše aplikace nainstalovaná v Androidu 5.0 (Lollipop) a váš kód volá rozhraní API, které je dostupné jenom v Androidu 7.1 (Nougat) a novějším, aplikace se zobrazí chyba za běhu a může dojít k chybovému ukončení. Váš kód proto musí za běhu zajistit, že volá pouze rozhraní API podporovaná zařízením s Androidem, na kterém běží. Jinými slovy, váš kód musí obsahovat explicitní kontroly za běhu, aby se zajistilo, že vaše aplikace používá novější rozhraní API pouze na zařízeních, která jsou dostatečná k jejich podpoře. Kontroly modulu runtime pro verze Androidu, dále v této příručce, vysvětluje, jak tyto kontroly modulu runtime přidat do kódu.
Pokud chcete v sadě Visual Studio získat přístup k nastavení minimální verze Androidu, otevřete vlastnosti projektu v Průzkumník řešení a vyberte stránku Manifest androidu. V rozevírací nabídce v části Minimální verze Androidu můžete vybrat minimální verzi Androidu pro vaši aplikaci:
Pokud vyberete Možnost Použít kompilaci pomocí verze sady SDK, bude minimální verze Androidu stejná jako nastavení cílové architektury.
Cílová verze Androidu
Cílová verze Androidu (označovaná také jako targetSdkVersion) je úroveň rozhraní API zařízení s Androidem, kde aplikace očekává spuštění. Android toto nastavení používá k určení, jestli se má povolit jakékoli chování kompatibility – tím zajistíte, že vaše aplikace bude dál fungovat očekávaným způsobem. Android používá nastavení cílové verze androidu vaší aplikace k zjištění toho, jaké změny chování se dají v aplikaci použít, aniž by došlo k jejímu narušení (takto Android poskytuje přesměrovací kompatibilitu).
Cílová architektura a verze Cílového Androidu, i když mají velmi podobné názvy, nejsou stejné. Nastavení cílové architektury komunikuje s Xamarin.Androidem informace na úrovni cílového rozhraní API pro použití v době kompilace, zatímco cílová verze Androidu komunikuje s Androidem informace o úrovni cílového rozhraní API pro použití za běhu (když je aplikace nainstalovaná a spuštěná na zařízení).
Pokud chcete získat přístup k tomuto nastavení v sadě Visual Studio, otevřete vlastnosti projektu v Průzkumník řešení a vyberte stránku Manifest androidu. V rozevírací nabídce v části Cílová verze Androidu můžete vybrat cílovou verzi Androidu pro vaši aplikaci:
Doporučujeme explicitně nastavit cílovou verzi Androidu na nejnovější verzi Androidu, kterou používáte k otestování aplikace. V ideálním případě by měla být nastavená na nejnovější verzi sady Android SDK – to vám umožní používat nová rozhraní API před provedením změn chování. Pro většinu vývojářů nedoporučujeme nastavit cílovou verzi Androidu tak, aby používala kompilaci pomocí verze sady SDK.
Obecně platí, že cílová verze Androidu by měla být vázána minimální verzí Androidu a cílovou architekturou. To znamená:
Minimální verze Androidu = Cílová verze <<Androidu = Cílová architektura
Další informace o úrovních sady SDK najdete v dokumentaci k sadě Android Developer uses-sdk .
Kontrola verzí Androidu za běhu
Při vydání každé nové verze Androidu se rozhraní API architektury aktualizuje tak, aby poskytovalo nové nebo náhradní funkce. S několika výjimkami se funkce rozhraní API ze starších verzí Androidu přenesou do novějších verzí Androidu bez úprav. To znamená, že pokud vaše aplikace běží na konkrétní úrovni rozhraní ANDROID API, bude ji obvykle možné spustit na novější úrovni rozhraní Android API bez úprav. Ale co když chcete aplikaci spustit i ve starších verzích Androidu?
Pokud vyberete minimální verzi Androidu, která je nižší než nastavení cílové architektury, nemusí být některá rozhraní API dostupná pro vaši aplikaci za běhu. Vaše aplikace ale může běžet na starším zařízení, ale s omezenou funkčností. Pro každé rozhraní API, které není dostupné na platformách Android odpovídající vašemu nastavení minimální verze Androidu, musí váš kód explicitně zkontrolovat hodnotu Android.OS.Build.VERSION.SdkInt vlastnosti a určit úroveň rozhraní API platformy, na které aplikace běží. Pokud je úroveň rozhraní API nižší než minimální verze Androidu, která podporuje rozhraní API, které chcete volat, pak váš kód musí najít způsob, jak správně fungovat bez volání tohoto rozhraní API.
Předpokládejme například, že chceme použít metodu NotificationBuilder.SetCategory k kategorizaci oznámení při spuštění v Androidu 5.0 Lollipop (a novějším), ale přesto chceme, aby naše aplikace běžela v dřívějších verzích Androidu, jako je Android 4.1 Jelly Bean (kde SetCategory není k dispozici). Odkazující na tabulku verzí Androidu na začátku této příručky vidíme, že kód verze sestavení pro Android 5.0 Lollipop je Android.OS.BuildVersionCodes.Lollipop. Pro podporu starších verzí Androidu, kde SetCategory není k dispozici, může náš kód zjistit úroveň rozhraní API za běhu a podmíněně volat SetCategory pouze v případě, že je úroveň rozhraní API vyšší nebo rovna kódu verze sestavení Lollipop:
if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
builder.SetCategory(Notification.CategoryEmail);
}
V tomto příkladu je cílová architektura naší aplikace nastavená na Android 5.0 (úroveň rozhraní API 21) a její minimální verze Androidu je nastavená na Android 4.1 (úroveň rozhraní API 16). Vzhledem k tomuSetCategory, že je k dispozici na úrovni Android.OS.BuildVersionCodes.Lollipop rozhraní API a později, bude tento ukázkový kód volat SetCategory pouze tehdy, když je skutečně dostupný – nebude se pokoušet volatSetCategory, když je úroveň rozhraní API 16, 17, 18, 19 nebo 20. Funkce se v těchto starších verzích Androidu zmenší jenom v rozsahu, kdy nejsou oznámení seřazená správně (protože nejsou kategorizovány podle typu), ale oznámení jsou stále publikovaná tak, aby upozorňovala uživatele. Naše aplikace stále funguje, ale její funkce se mírně snižuje.
Obecně platí, že kontrola verze sestavení pomáhá vašemu kódu rozhodnout se za běhu mezi provedením něčeho nového a starého. Příklad:
if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
// Do things the Lollipop way
}
else
{
// Do things the pre-Lollipop way
}
Neexistuje žádné rychlé a jednoduché pravidlo, které vysvětluje, jak omezit nebo upravit funkce aplikace, když běží ve starších verzích Androidu, které nemají jedno nebo více rozhraní API. V některých případech (například v příkladu SetCategory výše) stačí vynechat volání rozhraní API, když není k dispozici. V jiných případech ale možná budete muset implementovat alternativní funkce, pro které Android.OS.Build.VERSION.SdkInt se zjistí, že je nižší než úroveň rozhraní API, kterou vaše aplikace potřebuje k zajištění optimálního prostředí.
Úrovně rozhraní API a knihovny
Když vytvoříte projekt knihovny Xamarin.Android (například knihovnu tříd nebo knihovnu vazeb), můžete nakonfigurovat pouze nastavení cílové architektury – minimální verze Androidu a nastavení cílové verze Androidu nejsou k dispozici. Je to proto, že neexistuje žádná stránka manifestu Androidu:
Nastavení minimální verze Androidu a cílové verze Androidu nejsou k dispozici, protože výsledná knihovna není samostatná aplikace – knihovnu je možné spustit na libovolné verzi Androidu v závislosti na aplikaci, se kterou je zabalená. Můžete určit, jak se má knihovna zkompilovat, ale nemůžete předpovědět, na které úrovni rozhraní API platformy bude knihovna spuštěna. S ohledem na to by se při používání nebo vytváření knihoven měly pozorovat následující osvědčené postupy:
Pokud používáte knihovnu pro Android – pokud ve své aplikaci využíváte knihovnu pro Android, nezapomeňte nastavit cílové rozhraní vaší aplikace na úroveň rozhraní API, která je alespoň tak vysoká jako nastavení cílové architektury knihovny.
Při vytváření knihovny pro Android – Pokud vytváříte knihovnu pro Android pro použití jinými aplikacemi, nezapomeňte nastavit její cílové rozhraní na minimální úroveň rozhraní API, kterou potřebuje ke kompilaci.
Tyto osvědčené postupy se doporučují, aby se zabránilo situaci, kdy se knihovna pokusí volat rozhraní API, které není za běhu dostupné (což může způsobit chybové ukončení aplikace). Pokud jste vývojář knihovny, měli byste se snažit omezit využití volání rozhraní API na malou a dobře vytvořenou podmnožinu celkové plochy rozhraní API. To pomáhá zajistit, aby se vaše knihovna bezpečně používala v širší škále verzí Androidu.
Shrnutí
Tento průvodce vysvětluje, jak se úrovně rozhraní ANDROID API používají ke správě kompatibility aplikací v různých verzích Androidu. Poskytuje podrobné kroky pro konfiguraci cílové architektury Xamarin.Android, minimální verze Androidu a nastavení projektu cílové verze Androidu. Poskytuje pokyny pro použití Správce sady Android SDK k instalaci balíčků SDK, včetně příkladů psaní kódu pro řešení různých úrovní rozhraní API za běhu a vysvětlení správy úrovní rozhraní API při vytváření nebo využívání knihoven Android. Poskytuje také komplexní seznam, který souvisí s úrovněmi rozhraní API s čísly verzí Androidu (například Android 4.4), názvy verzí Androidu (například Kitkat) a kódy verzí buildu Xamarin.Android.