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

В корневом каталоге набора исходных файлов проекта каждого приложения должен быть файл 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-filter>), каждый из которых описывает разные возможности этого компонента.

Подробную информацию вы найдете в статье Интенты и фильтры интентов.

Значки и ярлыки

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

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

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

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

Разрешения

Приложения для 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 23

        // Specifies the API level used to test the app.
        targetSdkVersion 36
        ...
    }
}

android {
    defaultConfig {
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdkVersion(23)

        // Specifies the API level used to test the app.
        targetSdkVersion(36)
        ...
    }
}

Подробнее о настройке сборки и файле build.gradle…

Подробнее о том, как указать, какие устройства поддерживает ваше приложение…

Правила именования файлов

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

Элементы

Обязательными являются только элементы <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"

Значения строк

Если значение атрибута является строкой, используйте двойную обратную косую черту (\\) для экранирования символов, например \\n для новой строки или \\uxxxx для символа Unicode.

Справочник по элементам манифеста

В таблице ниже приведены ссылки на справочные документы для всех допустимых элементов в файле 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>