Omówienie pliku manifestu aplikacji

Każdy projekt aplikacji musi mieć plik AndroidManifest.xml, który dokładnie imię i nazwisko, w katalogu głównym zbioru źródłowego 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 musi zawierać między innymi te elementy:

• 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 kolejnej sekcji.
• Uprawnienia wymagane przez aplikację dostęp do chronionych części systemu lub innych aplikacji. Zawiera ona również deklarację wszelkich uprawnień, które inne aplikacje muszą mieć, 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 tworzysz aplikację za pomocą Android Studio, plik manifestu jest tworzone automatycznie, a większość podstawowych elementów manifestu jest dodawana jako zwłaszcza wtedy, gdy używasz szablonów kodu.

Funkcje pliku

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 klasy BroadcastReceiver
• <provider> dla każdej podklasy klasy ContentProvider

Jeśli zmienisz klasę dowolnego z tych komponentów na podklasę bez zadeklarowania go w pliku manifestu system nie może go uruchomić.

Podaj nazwę podklasy za pomocą atrybutu name używając pełnego oznaczenia 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ą namespace zostanie dodany prefiks z przestrzeni nazw aplikacji z pliku build.gradle na poziomie modułu. Jeśli na przykład przestrzeń nazw to "com.example.myapp", ta nazwa aktywności odpowiada com.example.myapp.MainActivity:

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

Więcej informacji o ustawianiu nazwy lub przestrzeni nazw pakietu znajdziesz w artykule Ustawianie przestrzeni nazw.

Jeśli masz komponenty aplikacji, które znajdują 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ść w aplikacjach, usługi i komunikaty odbiorcy są aktywowani przez zamiary. 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ż jedna aplikacja może obsługuje intencję, użytkownik może wybrać aplikację, której 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 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, gdy komponent jest przedstawiony jako opcja realizowanych celów. 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 prośby o przyznanie uprawnień za pomocą elementu <uses-permission> w manifeście. Jeśli to uprawnienie zostanie przyznane, aplikacja będzie mogła korzystać z chronionego funkcje zabezpieczeń. W przeciwnym razie próby uzyskania dostępu do tych funkcji się nie uda.

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 zostało zadeklarowane razem z <permission> .

Więcej informacji znajdziesz w artykule Uprawnienia na Androidzie.

Zgodność urządzeń

Plik manifestu to także miejsce, w którym możesz zadeklarować, jakiego typu sprzęt lub funkcji oprogramowania wymaganych przez aplikację, a także typów urządzeń, na których aplikacja który jest zgodny z technologią. Sklep Google Play nie zezwala użytkownikom na instalowanie Twojej aplikacji na urządzeniach, które nie mają funkcji lub wersji systemu dostępnych dla aplikacji wymaga.

Istnieje kilka tagów pliku manifestu, które określają, z jakimi urządzeniami jest zgodna aplikacja. Oto najpopularniejsze z nich.

<uses-feature>

Element <uses-feature> umożliwia zadeklarowanie funkcji sprzętu i oprogramowania, których potrzebuje aplikacja. Jeśli na przykład aplikacja nie może osiągnąć podstawowych W przypadku urządzenia bez czujnika kompasu możesz zadeklarować, czujnika zgodnie z wymaganiami z następującym tagiem 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: Zgodność pliku manifestu aplikacji Chromebooki.

<uses-sdk>

Każda kolejna wersja platformy często dodaje nowe interfejsy API, 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, zamiast tego 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 o konfigurowaniu kompilacji.

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

Konwencje plików

W tej sekcji opisano konwencje i zasady, które ogólnie dotyczą wszystkich elementów i atrybutów w pliku manifestu.

Elementy

Tylko <manifest> i <application> elementów są wymagane. Każda z nich musi wystąpić tylko raz. Większość pozostałych elementów może wystąpić zero lub więcej razy. Jednak aby plik manifestu był użyteczny, musi zawierać niektóre z nich.

Wszystkie wartości są ustawiane przez atrybuty, a nie jako dane znaków w obrębie i inne elementy.

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 główne wyjątki od tej reguły reguła:

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

Atrybuty

Formalnie wszystkie atrybuty są opcjonalne. Jednak w przypadku wielu atrybutów musi być określony, aby element mógł zrealizować swoje przeznaczenie. W przypadku atrybutów naprawdę opcjonalnych zapoznaj się z dokumentacją wskazuje 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 odnosi się do atrybutów po nazwie.

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. Na przykład filtr intencji może wyświetlić listę kilku 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ą różnią się w zależności od języka użytkownika lub innych konfiguracji urządzenia (np. ikona ikony powinna mieć inny rozmiar w zależności od gęstości pikseli na ekranie). wartości powinny być ustawiane na podstawie zasobu lub motywu, a nie na stałe manifestu. Rzeczywista wartość może się następnie zmienić w zależności od parametru alternatywnego zasobów dostępnych na potrzeby 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). Jedyna inna prawidłowa nazwa pakietu to android, gdy chcesz skorzystać z zasobu z Androida platformy.

type jest typem 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

Gdy wartość atrybutu jest ciągiem znaków, użyj podwójnych ukośników lewych (\\), aby zmienić znaczenie znaków, np. \\n dla nowego wiersza lub \\uxxxx w przypadku znaku Unicode.

Odniesienie do elementów pliku manifestu

W tabeli poniżej znajdziesz linki do dokumentów referencyjnych dotyczących wszystkich prawidłowych elementów w pliku AndroidManifest.xml.

Limity

W pliku manifestu obowiązuje limit liczby wystąpień tych tagów:

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

Przykładowy plik manifestu

Poniższy kod XML to prosty przykład atrybutu AndroidManifest.xml, który deklaruje dwie 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>