Omówienie pliku manifestu aplikacji

Każdy projekt aplikacji musi zawierać plik AndroidManifest.xml o tej nazwie w katalogu głównym zbioru źródeł projektu. Plik manifestu zawiera najważniejsze informacje o aplikacji, które są potrzebne narzędziom do kompilacji Androida, systemowi operacyjnemu Android i Google Play.

Plik manifestu jest wymagany m.in. do deklarowania:

• Komponenty aplikacji, w tym wszystkie czynnoś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. Zawiera ona również deklarację wszystkich uprawnień, które muszą mieć inne aplikacje, aby uzyskać dostęp do treści z tej aplikacji. Więcej informacji o uprawnieniach znajdziesz w następnej sekcji.
• funkcje sprzętowe i programowe, których wymaga aplikacja, co wpływa na to, na jakich urządzeniach można ją zainstalować z Google Play; Więcej informacji o zgodności urządzeń znajdziesz w kolejnej sekcji.

Jeśli do kompilowania aplikacji używasz Android Studio, plik manifestu zostanie utworzony automatycznie, a większość jego najważniejszych elementów zostanie dodana podczas kompilowania aplikacji, zwłaszcza gdy używasz szablonów kodu.

Funkcje plików

W następnych sekcjach opisano, jak niektóre z najważniejszych właściwości aplikacji są odzwierciedlane w pliku manifestu.

Komponenty aplikacji

W pliku manifestu zadeklaruj odpowiedni element XML dla każdego elementu aplikacji, który utworzysz w aplikacji:

• <activity> dla każdej podklasy Activity
• <service> dla każdej podklasy Service
• <receiver> dla każdej podklasy BroadcastReceiver
• <provider> dla każdej podklasy ContentProvider

Jeśli utworzysz podklasę któregoś z tych komponentów bez zadeklarowania go w pliku manifestu, system nie będzie mógł go uruchomić.

Określ nazwę podklasy za pomocą atrybutu name, używając pełnej nazwy pakietu. Na przykład podklasa Activity jest deklarowana w ten sposób:

<manifest ... >
    <application ... >
        <activity android:name="com.example.myapp.MainActivity" ... >
        </activity>
    </application>
</manifest>

Jeśli jednak pierwszy znak w wartości name to kropka, przed nazwą zostanie dodany prefiks z przestrzeni nazw aplikacji z elementu namespace w pliku build.gradle na poziomie modułu. Jeśli na przykład przestrzeń nazw to "com.example.myapp", nazwa aktywności com.example.myapp.MainActivity zostanie przekształcona w 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 znajdujące się w podpakietach, np. com.example.myapp.purchases, wartość name musi zawierać brakujące nazwy podpakietów, np. ".purchases.PayActivity", lub musisz użyć pełnej nazwy pakietu.

Filtry intencji

Aktywności aplikacji, usługi i odbiorniki transmisji są aktywowane przez intencje. Intencja to wiadomość zdefiniowana przez obiekt Intent, która opisuje działanie do wykonania, w tym dane, na których ma ono polegać, kategorię komponentu, który ma je wykonać, oraz inne instrukcje.

Gdy aplikacja wysyła intencję do systemu, system znajduje komponent aplikacji, który może obsłużyć intencję na podstawie deklaracji filtru intencji w pliku manifestu każdej aplikacji. System uruchamia instancję pasującego komponentu i przekazuje mu obiekt Intent. Jeśli więcej niż 1 aplikacja może obsłużyć intencję, użytkownik może wybrać, której aplikacji 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 dokumentacji Intencje i filtry intencji.

Ikony i etykiety

Niektóre elementy pliku manifestu mają atrybuty icon i label, które służą do wyświetlania użytkownikom odpowiedniego elementu aplikacji odpowiednio w postaci małej ikony lub etykiety tekstowej.

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 komponencie<intent-filter>są wyświetlane użytkownikowi, gdy komponent jest prezentowany jako opcja realizacji zamiaru. Domyślnie ta ikona jest dziedziczona z ikony zadeklarowanej dla komponentu nadrzędnego, czyli z elementu <activity> lub <application>.

Możesz zmienić ikonę filtra intencji, jeśli zawiera ono unikalne działanie, które chcesz lepiej przedstawić w oknie wyboru. Więcej informacji znajdziesz w artykule Zezwalanie innym aplikacjom na uruchamianie aktywności.

Uprawnienia

Aplikacje na Androida muszą prosić o dostęp do danych wrażliwych użytkownika, takich jak kontakty i SMS-y, lub do niektórych funkcji systemu, takich jak aparat i dostęp do internetu. Każde uprawnienie jest oznaczone unikalną etykietą. Na przykład aplikacja, która musi wysyłać SMS-y, musi zawierać w pliku manifestu tę linię:

<manifest ... >
    <uses-permission android:name="android.permission.SEND_SMS"/>
    ...
</manifest>

Począwszy od Androida 6.0 (poziom interfejsu API 23) użytkownik może zatwierdzać lub odrzucać niektóre uprawnienia aplikacji w czasie działania. Niezależnie od tego, którą wersję Androida obsługuje Twoja aplikacja, musisz zadeklarować wszystkie żądania uprawnień za pomocą elementu <uses-permission> w manifeście. Jeśli użytkownik przyzna takie uprawnienia, aplikacja będzie mogła korzystać z funkcji chronionych. W przeciwnym razie próby uzyskania dostępu do tych funkcji się nie powiedzie.

Aplikacja może też chronić swoje komponenty za pomocą uprawnień. Może ona używać dowolnych uprawnień zdefiniowanych przez Androida (wymienionych w sekcji android.Manifest.permission) lub 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 artykule Uprawnienia na Androidzie.

Zgodność urządzeń

W pliku manifestu możesz też zadeklarować, jakich funkcji sprzętowych lub oprogramowania wymaga Twoja aplikacja, a zarazem określić, z jakimi urządzeniami jest zgodna. Sklep Google Play nie pozwala użytkownikom instalować aplikacji na urządzeniach, które nie mają funkcji lub wersji systemu wymaganych przez aplikację.

Istnieje kilka tagów pliku manifestu, które określają, z jakimi urządzeniami jest zgodna aplikacja. Oto kilka najczęstszych:

<uses-feature>

Element <uses-feature> umożliwia zadeklarowanie funkcji sprzętowych i funkcji oprogramowania, których potrzebuje aplikacja. Jeśli na przykład Twoja aplikacja nie może uzyskać podstawowych funkcji na urządzeniu bez czujnika kompasu, możesz zadeklarować ten czujnik jako wymagany za pomocą tego elementu tagu 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ę ważne ograniczenia funkcji sprzętowych i programowych. Więcej informacji znajdziesz w artykule Kompatybilność pliku manifestu aplikacji na Chromebookach.

<uses-sdk>

Każda kolejna wersja platformy często zawiera nowe interfejsy API, które nie były dostępne w poprzedniej wersji. Aby wskazać minimalną wersję, z którą jest zgodna Twoja aplikacja, manifest musi zawierać tag <uses-sdk> i jego atrybut minSdkVersion.

Pamiętaj jednak, że atrybuty w elemencie <uses-sdk> są zastępowane przez odpowiadające im właściwości w pliku build.gradle. Jeśli używasz Android Studio, podaj tam wartości minSdkVersion i targetSdkVersion:

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
        ...
    }
}

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 Jak skonfigurować kompilację.

Więcej informacji o deklarowaniu obsługi różnych urządzeń przez aplikację znajdziesz w artykule Omówienie zgodności z urządzeniami.

Konwencje dotyczące plików

W tej sekcji opisano konwencje i zasady, które ogólnie dotyczą 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 aby plik manifestu był użyteczny, musi zawierać niektóre z nich.

Wszystkie wartości są ustawiane za pomocą atrybutów, a nie jako dane znakowe w elemencie.

Elementy na tym samym poziomie nie są zwykle uporządkowane. Na przykład elementy <activity>, <provider> i <service> można umieścić w dowolnej kolejności. Istnieją 2 kluczowe wyjątki od tej reguły:

• Element <activity-alias> musi znajdować się po elemencie <activity>, którego jest aliasem.
• Element <application> musi być ostatnim elementem w elemencie <manifest>.

Atrybuty

Formalnie 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 podaje wartości domyślne.

Z wyjątkiem niektórych atrybutów elementu <manifest> wszystkie nazwy atrybutów zaczynają się od prefiksu android:, na przykład android:alwaysRetainTaskState. Ponieważ prefiks jest uniwersalny, w dokumentacji zazwyczaj pomija się go, gdy mowa o atrybutach według nazwy.

Wiele wartości

Jeśli można podać więcej niż jedną wartość, element jest prawie zawsze powtarzany, a nie podaje się kilku wartości w ramach jednego elementu. Filtr intencji może na przykład 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 ikonę 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. aby zapewnić inny rozmiar ikony w zależności od gęstości pikseli urządzenia). Dlatego wartości powinny być ustawiane w zasobach lub motywie, a nie zakodowane na stałe w pliku manifestu. Rzeczywista wartość może się zmieniać w zależności od zasobów alternatywnych, które udostępniasz 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 Twoją aplikację (w tym przez bibliotekę zależną, ponieważ zasoby biblioteki są scalane z Twoimi). Jeśli chcesz użyć zasobu z ramy Androida, jedyną prawidłową nazwą pakietu jest android.

type to typ zasobu, np. string lub drawable, 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ć ?, a nie @:

"?[package:]type/name"

Wartości ciągu znaków

Jeśli wartość atrybutu jest ciągiem znaków, użyj podwójnego ukośnika wstecznego (\\), aby uciec od znaków, takich jak \\n dla znaku nowego wiersza lub \\uxxxx dla znaku Unicode.

Odwołania do elementów pliku manifestu

Tabela poniżej zawiera linki do dokumentów referencyjnych wszystkich prawidłowych elementów w pliku AndroidManifest.xml.

Limity

W pliku manifestu można użyć określonej liczby wystąpień tych tagów:

Maksymalna długość tych atrybutów jest ograniczona:

Przykładowy plik manifestu

Poniżej znajduje się prosty przykład kodu XML AndroidManifest.xml, który deklaruje 2 aktywności 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>