Każdy projekt aplikacji musi zawierać plik AndroidManifest.xml
o dokładnie takiej nazwie w katalogu głównym źródłowego zestawu projektu.
Plik manifestu zawiera podstawowe informacje o aplikacji dla narzędzi do kompilacji Androida, systemu operacyjnego Android i Google Play.
Plik manifestu jest wymagany m.in. do zadeklarowania tych informacji:
- Komponenty aplikacji, w tym wszystkie aktywności, usługi, odbiorniki transmisji i dostawcy treści. Każdy komponent musi definiować podstawowe właściwości, takie jak nazwa klasy Kotlin lub Java. Może też deklarować możliwości, np. które konfiguracje urządzeń może obsługiwać, oraz filtry intencji, które opisują, jak można uruchomić komponent. Więcej informacji o komponentach aplikacji znajdziesz w następnej sekcji.
- Uprawnienia, których aplikacja potrzebuje, aby uzyskać dostęp do chronionych części systemu lub innych aplikacji. Deklaruje też uprawnienia, które muszą mieć inne aplikacje, jeśli chcą uzyskać dostęp do treści z tej aplikacji. Więcej informacji o uprawnieniach znajdziesz w dalszej części.
- Wymagania sprzętowe i programowe aplikacji, które wpływają na to, na jakich urządzeniach można zainstalować aplikację z Google Play. Więcej informacji o zgodności urządzeń znajdziesz w kolejnej sekcji.
Jeśli do tworzenia aplikacji używasz Androida Studio, plik manifestu jest tworzony automatycznie, a większość niezbędnych elementów manifestu jest dodawana podczas tworzenia aplikacji, zwłaszcza gdy używasz szablonów kodu.
Funkcje plików
W sekcjach poniżej opisujemy, jak niektóre z najważniejszych cech aplikacji są odzwierciedlone w pliku manifestu.
Komponenty aplikacji
Dla każdego komponentu aplikacji utworzonego w aplikacji zadeklaruj odpowiedni element XML w pliku manifestu:
<activity>
dla każdej podklasyActivity
<service>
dla każdej podklasyService
<receiver>
dla każdej podklasyBroadcastReceiver
<provider>
dla każdej podklasyContentProvider
Jeśli utworzysz podklasę dowolnego z tych komponentów bez zadeklarowania jej w pliku manifestu, system nie będzie mógł jej uruchomić.
Określ nazwę podklasy za pomocą atrybutu name
, używając pełnej nazwy pakietu. Na przykład podklasaActivity
jest deklarowana w ten sposób:
<manifest ... > <application ... > <activity android:name="com.example.myapp.MainActivity" ... > </activity> </application> </manifest>
Jeśli jednak pierwszym znakiem w wartości name
jest kropka, do nazwy dodawana jest przestrzeń nazw aplikacji z właściwości namespace
pliku build.gradle
na poziomie modułu. Jeśli na przykład przestrzeń nazw to "com.example.myapp"
, nazwa działania "com.example.myapp"
zostanie przekształcona w "com.example.myapp"
:com.example.myapp.MainActivity
<manifest ... > <application ... > <activity android:name=".MainActivity" ... > ... </activity> </application> </manifest>
Więcej informacji o ustawianiu nazwy pakietu lub przestrzeni nazw znajdziesz w artykule Ustawianie przestrzeni nazw.
Jeśli masz komponenty aplikacji, które znajdują się w podpakietach, np. w com.example.myapp.purchases
, wartość name
musi zawierać brakujące nazwy podpakietów, np. ".purchases.PayActivity"
, lub pełną nazwę pakietu.
Filtry intencji
Aktywności, usługi i odbiorniki transmisji w aplikacji są aktywowane przez intencje. Intencja to wiadomość zdefiniowana przez obiekt Intent
, który opisuje działanie do wykonania, w tym dane, na których ma zostać wykonane działanie, kategorię komponentu, który ma wykonać działanie, oraz inne instrukcje.
Gdy aplikacja wysyła do systemu intencję, system wyszukuje komponent aplikacji, który może ją obsłużyć, na podstawie deklaracji filtrów intencji w pliku manifestu każdej aplikacji. System uruchamia instancję pasującego komponentu i przekazuje do niego obiekt Intent
. Jeśli więcej niż jedna aplikacja może obsłużyć intencję, użytkownik może wybrać, której aplikacji chce użyć.
Komponent aplikacji może mieć dowolną liczbę filtrów intencji (zdefiniowanych za pomocą elementu<intent-filter>
), z których każdy opisuje inną funkcję tego komponentu.
Więcej informacji znajdziesz w dokumencie Intencje i filtry intencji.
Ikony i etykiety
Wiele elementów pliku manifestu ma atrybuty icon
i label
, które służą do wyświetlania użytkownikom małej ikony i etykiety tekstowej odpowiedniego komponentu aplikacji.
W każdym przypadku ikona i etykieta ustawione w elemencie nadrzędnym stają się domyślną wartością icon
i label
dla wszystkich elementów podrzędnych.
Na przykład ikona i etykieta ustawione w elemencie
<application>
są domyślną ikoną i etykietą każdego komponentu aplikacji, np. wszystkich działań.
Ikona i etykieta ustawione w <intent-filter>
komponentu są wyświetlane użytkownikowi, gdy ten komponent jest prezentowany jako opcja realizacji intencji. Domyślnie ta ikona jest dziedziczona z ikony zadeklarowanej w komponencie nadrzędnym, czyli z elementu <activity>
lub <application>
.
Możesz zmienić ikonę filtra intencji, jeśli zapewnia on unikalne działanie, które chcesz lepiej wskazać w oknie wyboru. Więcej informacji znajdziesz w artykule Zezwalanie innym aplikacjom na rozpoczynanie aktywności.
Uprawnienia
Aplikacje na Androida muszą prosić o zezwolenie na dostęp do danych wrażliwych użytkownika, takich jak kontakty i SMS-y, lub do określonych funkcji systemu, takich jak aparat i dostęp do internetu. Każde uprawnienie jest identyfikowane za pomocą unikalnej etykiety. Na przykład aplikacja, która musi wysyłać SMS-y, musi mieć w pliku manifestu ten wiersz:
<manifest ... > <uses-permission android:name="android.permission.SEND_SMS"/> ... </manifest>
Począwszy od Androida 6.0 (interfejs API na poziomie 23), użytkownik może zatwierdzać lub odrzucać niektóre uprawnienia aplikacji w czasie działania aplikacji. Niezależnie od tego, którą wersję Androida obsługuje Twoja aplikacja, musisz zadeklarować wszystkie prośby o uprawnienia za pomocą elementu <uses-permission>
w manifeście. Jeśli uprawnienie zostanie przyznane, aplikacja będzie mogła korzystać z chronionych funkcji. W przeciwnym razie próby uzyskania dostępu do tych funkcji zakończą się niepowodzeniem.
Aplikacja może też chronić własne komponenty za pomocą uprawnień. Może korzystać z dowolnych uprawnień zdefiniowanych przez Androida, które są wymienione w android.Manifest.permission
, lub z uprawnień zadeklarowanych w innej aplikacji. Aplikacja może też definiować własne uprawnienia.
Nowe uprawnienie jest deklarowane za pomocą elementu
<permission>
.
Więcej informacji znajdziesz w sekcji Uprawnienia na Androidzie.
Zgodność urządzeń
W pliku manifestu możesz też zadeklarować, jakich typów funkcji sprzętowych lub programowych wymaga Twoja aplikacja, a co za tym idzie, z jakimi typami urządzeń jest ona zgodna. Google Play Store nie pozwala użytkownikom instalować aplikacji na urządzeniach, które nie zapewniają funkcji lub wersji systemu wymaganych przez aplikację.
Istnieje kilka tagów w pliku manifestu, które określają, z jakimi urządzeniami jest zgodna Twoja aplikacja. Oto niektóre z najczęstszych.
<uses-feature>
Element
<uses-feature>
umożliwia deklarowanie funkcji sprzętowych i programowych, których potrzebuje Twoja aplikacja. Jeśli na przykład aplikacja nie może działać na urządzeniu bez czujnika kompasu, możesz zadeklarować, że czujnik kompasu jest wymagany, używając tego tagu w pliku manifestu:
<manifest ... > <uses-feature android:name="android.hardware.sensor.compass" android:required="true" /> ... </manifest>
Uwaga: jeśli chcesz udostępnić aplikację na Chromebookach, musisz wziąć pod uwagę pewne ważne ograniczenia dotyczące funkcji sprzętowych i programowych. Więcej informacji znajdziesz w artykule Zgodność manifestu aplikacji z Chromebookami.
<uses-sdk>
Każda kolejna wersja platformy często dodaje nowe interfejsy API, które nie są dostępne w poprzedniej wersji. Aby wskazać minimalną wersję, z którą aplikacja jest zgodna, plik manifestu musi zawierać tag <uses-sdk>
i jego atrybut minSdkVersion
.
Pamiętaj jednak, że atrybuty w elemencie <uses-sdk>
są zastępowane przez odpowiednie właściwości w pliku build.gradle
.
Jeśli więc używasz Androida Studio, określ tam wartości minSdkVersion
i targetSdkVersion
:
Groovy
android { defaultConfig { applicationId 'com.example.myapp' // Defines the minimum API level required to run the app. minSdkVersion 21 // Specifies the API level used to test the app. targetSdkVersion 33 ... } }
Kotlin
android { defaultConfig { applicationId = "com.example.myapp" // Defines the minimum API level required to run the app. minSdkVersion(21) // Specifies the API level used to test the app. targetSdkVersion(33) ... } }
Więcej informacji o pliku build.gradle
znajdziesz w artykule o konfigurowaniu kompilacji.
Więcej informacji o deklarowaniu obsługi różnych urządzeń przez aplikację znajdziesz w omówieniu zgodności urządzeń.
Konwencje dotyczące plików
W tej sekcji opisujemy konwencje i reguły, które ogólnie obowiązują w przypadku wszystkich elementów i atrybutów w pliku manifestu.
- Elementy
- Wymagane są tylko elementy
<manifest>
i<application>
. Każdy z nich musi wystąpić tylko raz. Większość pozostałych elementów może występować zero lub więcej razy. Jednak niektóre z nich muszą być obecne, aby plik manifestu był przydatny.Wszystkie wartości są ustawiane za pomocą atrybutów, a nie jako dane znakowe w elemencie.
Elementy na tym samym poziomie zwykle nie są uporządkowane. Na przykład elementy
<activity>
,<provider>
i<service>
mogą występować w dowolnej kolejności. Istnieją 2 główne wyjątki od tej reguły:-
Element
<activity-alias>
musi następować po elemencie<activity>
, dla którego jest aliasem. -
Element
<application>
musi być ostatnim elementem w elemencie<manifest>
.
-
Element
- Atrybuty
- Technicznie wszystkie atrybuty są opcjonalne. Jednak wiele atrybutów musi być określonych, aby element mógł spełniać swoje zadanie.
W przypadku atrybutów opcjonalnych dokumentacja zawiera domyślne wartości.
Z wyjątkiem niektórych atrybutów elementu głównego
<manifest>
wszystkie nazwy atrybutów zaczynają się od prefiksuandroid:
, np.android:alwaysRetainTaskState
. Prefiks jest uniwersalny, dlatego w dokumentacji zwykle pomija się go, gdy odnosi się do atrybutów według nazwy. - Wiele wartości
- Jeśli można podać więcej niż jedną wartość, element jest prawie zawsze powtarzany, a nie wymieniany w ramach jednego elementu.
Na przykład filtr intencji może zawierać kilka działań:
<intent-filter ... > <action android:name="android.intent.action.EDIT" /> <action android:name="android.intent.action.INSERT" /> <action android:name="android.intent.action.DELETE" /> ... </intent-filter>
- Wartości zasobów
- Niektóre atrybuty mają wartości wyświetlane użytkownikom, np. tytuł aktywności lub ikona aplikacji. Wartości tych atrybutów mogą się różnić w zależności od języka użytkownika lub innych konfiguracji urządzenia (np. w celu zapewnienia innego rozmiaru ikony w zależności od gęstości pikseli urządzenia), dlatego wartości powinny być ustawiane z zasobu lub motywu, a nie zakodowane na stałe w pliku manifestu. Rzeczywista wartość może się następnie zmienić w zależności od alternatywnych zasobów, które podasz dla różnych konfiguracji urządzeń.
Zasoby są wyrażane jako wartości w tym formacie:
"@[package:]type/name"
Możesz pominąć nazwę package, jeśli zasób jest dostarczany przez aplikację (w tym przez bibliotekę, ponieważ zasoby biblioteki są scalane z Twoimi). Jedyną inną prawidłową nazwą pakietu jest
android
, gdy chcesz użyć zasobu z platformy Android.type to typ zasobu, np.
string
lubdrawable
, a name to nazwa identyfikująca konkretny zasób. Oto przykład:<activity android:icon="@drawable/smallPic" ... >
Więcej informacji o dodawaniu zasobów do projektu znajdziesz w artykule Omówienie zasobów aplikacji.
Aby zastosować wartość zdefiniowaną w motywie, pierwszym znakiem musi być
?
zamiast@
:"?[package:]type/name"
- Wartości typu ciąg znaków
- Jeśli wartość atrybutu jest ciągiem znaków, użyj podwójnego ukośnika wstecznego (
\\
), aby zmienić znaczenie znaków, np.\\n
w przypadku znaku nowego wiersza lub\\uxxxx
w przypadku znaku Unicode.
Dokumentacja elementów pliku manifestu
Tabela poniżej zawiera linki do dokumentów referencyjnych wszystkich prawidłowych elementów w pliku AndroidManifest.xml
.
<action> |
Dodaje działanie do filtra intencji. |
<activity> |
Deklaruje komponent aktywności. |
<activity-alias> |
Deklaruje alias aktywności. |
<application> |
Deklaruje aplikację. |
<category> |
Dodaje nazwę kategorii do filtra intencji. |
<compatible-screens> |
Określa każdą konfigurację ekranu, z którą aplikacja jest zgodna. |
<data> |
Dodaje specyfikację danych do filtra intencji. |
<grant-uri-permission> |
Określa podzbiory danych aplikacji, do których dostawca treści nadrzędnych ma uprawnienia dostępu. |
<instrumentation> |
Deklaruje klasę Instrumentation , która umożliwia monitorowanie interakcji aplikacji z systemem. |
<intent-filter> |
Określa typy intencji, na które może odpowiadać działanie, usługa lub odbiornik transmisji. |
<manifest> |
Element główny pliku AndroidManifest.xml . |
<meta-data> |
Para nazwa-wartość dla elementu dodatkowych, dowolnych danych, które można przekazać do komponentu nadrzędnego. |
<path-permission> |
Określa ścieżkę i wymagane uprawnienia dla określonego podzbioru danych w ramach dostawcy treści. |
<permission> |
Deklaruje uprawnienie zabezpieczające, które może służyć do ograniczania dostępu do określonych komponentów lub funkcji tej lub innych aplikacji. |
<permission-group> |
Deklaruje nazwę logicznego grupowania powiązanych uprawnień. |
<permission-tree> |
Deklaruje nazwę podstawową drzewa uprawnień. |
<provider> |
Deklaruje komponent dostawcy treści. |
<queries> |
Deklaruje zestaw innych aplikacji, do których Twoja aplikacja zamierza uzyskać dostęp. Więcej informacji znajdziesz w przewodniku po filtrowaniu widoczności pakietów. |
<receiver> |
Deklaruje komponent odbiornika. |
<service> |
Deklaruje komponent usługi. |
<supports-gl-texture>
| Deklaruje pojedynczy format kompresji tekstur GL, który jest obsługiwany przez aplikację. |
<supports-screens> |
Deklaruje rozmiary ekranu obsługiwane przez aplikację i włącza tryb zgodności ekranu w przypadku ekranów większych niż obsługiwane przez aplikację. |
<uses-configuration> |
Wskazuje konkretne funkcje wejściowe, których wymaga aplikacja. |
<uses-feature> |
Deklaruje pojedynczą funkcję sprzętową lub programową, która jest używana przez aplikację. |
<uses-library> |
Określa bibliotekę współdzieloną, z którą aplikacja musi być połączona. |
<uses-native-library> |
Określa udostępnioną przez dostawcę natywną bibliotekę współdzieloną, z którą aplikacja musi być połączona. |
<uses-permission> |
Określa uprawnienia systemowe, które użytkownik musi przyznać, aby aplikacja działała prawidłowo. |
<uses-permission-sdk-23> |
Określa, że aplikacja chce uzyskać określone uprawnienie, ale tylko wtedy, gdy jest zainstalowana na urządzeniu z Androidem 6.0 (poziom interfejsu API 23) lub nowszym. |
<uses-sdk> |
Umożliwia określenie zgodności aplikacji z co najmniej jedną wersją platformy Android za pomocą liczby całkowitej reprezentującej poziom interfejsu API. |
Limity
W pliku manifestu obowiązuje limit wystąpień tych tagów:
Nazwa tagu | Limit |
---|---|
<package> |
1000 |
<meta-data> |
1000 |
<uses-library> |
1000 |
Maksymalna długość tych atrybutów jest ograniczona:
Atrybut | Limit |
---|---|
name |
1024 |
versionName |
1024 |
host |
255 |
mimeType |
255 |
Przykładowy plik manifestu
Poniższy kod XML to prosty przykład AndroidManifest.xml
, który deklaruje 2 działania w aplikacji.
<?xml version="1.0" encoding="utf-8"?>
<manifest
xmlns:android="http://schemas.android.com/apk/res/android"
android:versionCode="1"
android:versionName="1.0">
<!-- Beware that these values are overridden by the build.gradle file -->
<uses-sdk android:minSdkVersion="15" android:targetSdkVersion="26" />
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:roundIcon="@mipmap/ic_launcher_round"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/AppTheme">
<!-- This name is resolved to com.example.myapp.MainActivity
based on the namespace property in the build.gradle file -->
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity
android:name=".DisplayMessageActivity"
android:parentActivityName=".MainActivity" />
</application>
</manifest>