Обзор манифеста приложения

Каждый проект приложения должен иметь файл AndroidManifest.xml с точно таким же именем в корневом наборе исходных кодов проекта . Файл манифеста содержит важную информацию о вашем приложении для инструментов сборки Android, операционной системы Android и Google Play.

Помимо прочего, в файле манифеста должно быть указано следующее:

• Компоненты приложения, включая все активности, сервисы, приёмники широковещательных сообщений и поставщики контента. Каждый компонент должен определять базовые свойства, такие как имя класса Kotlin или Java. Он также может объявлять возможности, например, какие конфигурации устройств он может обрабатывать, и фильтры намерений, описывающие способ запуска компонента. Подробнее о компонентах приложения читайте в следующем разделе.
• Разрешения, необходимые приложению для доступа к защищённым разделам системы или другим приложениям. Также определяются разрешения, необходимые другим приложениям для доступа к контенту этого приложения. Подробнее о разрешениях читайте в следующем разделе.
• Аппаратные и программные характеристики, требуемые приложению, влияют на то, на какие устройства можно установить приложение из Google Play. Подробнее о совместимости устройств читайте в следующем разделе.

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

Особенности файла

В следующих разделах описывается, как некоторые наиболее важные характеристики вашего приложения отражаются в файле манифеста.

Компоненты приложения

Для каждого компонента приложения , создаваемого в вашем приложении, объявите соответствующий элемент XML в файле манифеста:

• <activity> для каждого подкласса Activity
• <service> для каждого подкласса Service
• <receiver> для каждого подкласса BroadcastReceiver
• <provider> для каждого подкласса ContentProvider

Если вы создадите подкласс любого из этих компонентов, не объявив его в файле манифеста, система не сможет его запустить.

Укажите имя подкласса с помощью атрибута name , используя полное обозначение пакета. Например, подкласс Activity объявляется следующим образом:

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

Однако если первый символ в значении name — точка, к имени добавляется префикс пространства имён приложения из свойства namespace файла build.gradle на уровне модуля. Например, если пространство имён — "com.example.myapp" , следующее имя активности преобразуется в com.example.myapp.MainActivity :

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

Дополнительные сведения об установке имени пакета или пространства имен см. в разделе Установка пространства имен .

Если у вас есть компоненты приложения, которые находятся в подпакетах, например, в com.example.myapp.purchases , то значение name должно добавлять отсутствующие имена подпакетов, например ".purchases.PayActivity" , или использовать полное имя пакета.

Фильтры намерений

Действия приложения, службы и приёмники широковещательных сообщений активируются намерениями . Намерение — это сообщение, определяемое объектом Intent , которое описывает действие, которое необходимо выполнить, включая данные, над которыми оно должно выполняться, категорию компонента, который должен выполнить действие, и другие инструкции.

Когда приложение отправляет системе намерение (Intent), система находит компонент приложения, способный обработать это намерение, на основе объявлений фильтра намерений в файле манифеста каждого приложения. Система запускает экземпляр соответствующего компонента и передаёт объект Intent этому компоненту. Если несколько приложений могут обработать намерение, пользователь может выбрать, какое из них использовать.

Компонент приложения может иметь любое количество фильтров намерений (определяемых с помощью элемента <intent-filter> ), каждый из которых описывает отдельную возможность этого компонента.

Более подробную информацию см. в документе Намерения и фильтры намерений .

Значки и этикетки

Ряд элементов манифеста имеют атрибуты icon и label для отображения пользователям небольшого значка и текстовой метки соответствующего компонента приложения.

В каждом случае значок и метка, заданные в родительском элементе, становятся icon и label по умолчанию для всех дочерних элементов. Например, значок и метка, заданные в элементе <application> , являются значком и меткой по умолчанию для каждого компонента приложения, например, для всех действий.

Значок и метка, заданные в элементе <intent-filter> компонента, отображаются пользователю всякий раз, когда компонент предлагается в качестве варианта для выполнения намерения. По умолчанию этот значок наследуется от значка, объявленного для родительского компонента, будь то элемент <activity> или <application> .

Вы можете изменить значок фильтра намерений, если он предоставляет уникальное действие, которое вы хотите лучше обозначить в диалоговом окне выбора. Подробнее см. в разделе «Разрешить другим приложениям запускать вашу активность» .

Разрешения

Приложения Android должны запрашивать разрешение на доступ к конфиденциальным данным пользователя, таким как контакты и SMS, или к определенным функциям системы, таким как камера и доступ в Интернет. Каждое разрешение идентифицируется уникальной меткой. Например, приложение, которому требуется отправлять SMS-сообщения, должно иметь следующую строку в манифесте:

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

Начиная с Android 6.0 (уровень API 23), пользователь может одобрить или отклонить некоторые разрешения приложения во время выполнения. Но независимо от того, какую версию Android поддерживает ваше приложение, все запросы на разрешения необходимо декларировать с помощью элемента <uses-permission> в манифесте. Если разрешение предоставлено, приложение может использовать защищённые функции. В противном случае попытки доступа к этим функциям завершаются неудачей.

Ваше приложение также может защищать свои компоненты с помощью разрешений. Оно может использовать любые разрешения, определённые Android, как указано в android.Manifest.permission , или разрешения, объявленные в другом приложении. Ваше приложение также может определять собственные разрешения. Новое разрешение объявляется с помощью элемента <permission> .

Более подробную информацию см. в разделе Разрешения на Android .

Совместимость устройств

В файле манифеста также можно указать, какие типы аппаратных и программных функций требуются вашему приложению, и, соответственно, с какими типами устройств оно совместимо. Магазин Google Play не позволяет пользователям устанавливать ваше приложение на устройства, которые не предоставляют требуемые вашему приложению функции или версию системы.

Существует несколько тегов манифеста, которые определяют, с какими устройствами совместимо ваше приложение. Ниже приведены некоторые из наиболее распространённых.

<uses-feature>

Элемент <uses-feature> позволяет объявить аппаратные и программные функции, необходимые вашему приложению. Например, если ваше приложение не может реализовать базовую функциональность на устройстве без компаса, вы можете объявить наличие компаса как необходимого с помощью следующего тега манифеста:

<manifest ... >
    <uses-feature android:name="android.hardware.sensor.compass"
                  android:required="true" />
    ...
</manifest>

Примечание : Если вы хотите, чтобы ваше приложение было доступно на устройствах Chromebook, следует учитывать некоторые важные ограничения аппаратных и программных функций. Подробнее см. в разделе «Совместимость манифеста приложения для устройств Chromebook» .

<uses-sdk>

Каждая последующая версия платформы часто добавляет новые API, недоступные в предыдущей версии. Чтобы указать минимальную версию, с которой совместимо ваше приложение, ваш манифест должен включать тег <uses-sdk> и его атрибут minSdkVersion .

Однако имейте в виду, что атрибуты в элементе <uses-sdk> переопределяются соответствующими свойствами в файле build.gradle . Поэтому, если вы используете Android Studio, укажите значения minSdkVersion и 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)
        ...
    }
}

For more information about the build.gradle file, read about how to configure your build .

Дополнительную информацию о том, как объявить о поддержке вашего приложения различными устройствами, см. в разделе Обзор совместимости устройств .

Соглашения о файлах

В этом разделе описываются соглашения и правила, которые обычно применяются ко всем элементам и атрибутам в файле манифеста.

Элементы

Обязательными являются только элементы <manifest> и <application> . Каждый из них должен встречаться только один раз. Большинство остальных элементов могут встречаться ноль или более раз. Однако некоторые из них должны присутствовать, чтобы файл манифеста был полезен.

Все значения задаются через атрибуты, а не как символьные данные внутри элемента.

Элементы на одном уровне, как правило, не упорядочены. Например, элементы <activity> , <provider> и <service> могут располагаться в любом порядке. Из этого правила есть два ключевых исключения:

• Элемент <activity-alias> должен следовать за <activity> , для которого он является псевдонимом.
• Элемент <application> должен быть последним элементом внутри элемента <manifest> .

Атрибуты

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

За исключением некоторых атрибутов корневого элемента <manifest> , все имена атрибутов начинаются с префикса android: например, android:alwaysRetainTaskState . Поскольку этот префикс универсален, в документации он обычно опускается при ссылке на атрибуты по имени.

Множественные значения

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

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

Ценности ресурсов

Значения некоторых атрибутов отображаются для пользователей, например, название действия или значок приложения. Значения этих атрибутов могут различаться в зависимости от языка пользователя или других настроек устройства (например, размер значка может меняться в зависимости от плотности пикселей устройства), поэтому значения следует задавать из ресурса или темы, а не жестко прописывать в файле манифеста. Фактическое значение может изменяться в зависимости от альтернативных ресурсов , предоставляемых вами для различных конфигураций устройства.

Ресурсы выражаются в виде значений в следующем формате:

"@[ package :] type / name "

Вы можете опустить имя package , если ресурс предоставляется вашим приложением (в том числе, если он предоставляется зависимостью от библиотеки, поскольку ресурсы библиотеки объединены с вашими ). Единственное другое допустимое имя пакета — android , если вы хотите использовать ресурс из фреймворка Android.

type — это тип ресурса, например, string или drawable , а name — это имя, идентифицирующее конкретный ресурс. Вот пример:

<activity android:icon="@drawable/smallPic" ... >

Дополнительную информацию о том, как добавлять ресурсы в проект, см. в разделе Обзор ресурсов приложения .

Чтобы вместо этого применить значение, определенное в теме , первым символом должен быть ? вместо @ :

"?[ package :] type / name "

Строковые значения

Where an attribute value is a string, use double backslashes ( \\ ) to escape characters, such as \\n for a newline or \\uxxxx for a Unicode character.

Ссылка на элементы манифеста

В следующей таблице приведены ссылки на справочные документы для всех допустимых элементов в файле AndroidManifest.xml .

Пределы

Следующие теги имеют ограничение на количество появлений в файле манифеста:

Следующие атрибуты имеют ограничение на максимальную длину:

Пример файла манифеста

Приведенный ниже XML представляет собой простой пример AndroidManifest.xml , в котором объявляются два действия для приложения.

<?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>