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

В каждом проекте приложения должен быть файл 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 в файле манифеста каждого приложения. Система запускает экземпляр соответствующего компонента и передает объект 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 Store не позволяет пользователям устанавливать ваше приложение на устройства, которые не поддерживают необходимые функции или версию системы.

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

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