The AndroidManifest.xml File

　　每个android应用程序的根目录下必须要有一个AndroidManifest.xml的配置清单文件。这份清单展示了关于这个应用程序在Android系统中的基本信息，运行这个应用程序的任何代码之前系统必须要具备的信息。Manifest清单如下：

　　.为应用程序命名了java package。java主程序包名作为android应用的唯一标识。

　　.描述了应用程序的各类组件：activities,services,broadcast receiver,content providers.它说明了那些每个组件的实现以及各自提供功能的类，比如哪些可以处理Intent 的message。这些描述让Android系统知道这些组件是什么，在什么情况下能够启动。

　　.决定哪些进程控制应用组件

　　.声明了应用必须具备哪些权限才能访问受保护的某些API，才能与其他应用程序进行交互。

　　.声明了其他与应用程序的组件进行交互的必须要具备的权限。

　　.列出了运行应用程序时提供分析和其他信息的classes清单。这些清单中的声明信息应当出现在应用程序开发和测试阶段，在应用程序发布之前应移除掉。

　　.声明了当前应用所需要的Android API的最低级别。

　　.列出了应用程序必须关联的Libraries。

Manifest文件的结构

　　下面的图展示了manifest文件的基本结构和它所包含的每个元素。每一个元素，元素下的所有属性，全部记录在一个文件中。查看任意一个元素的详细信息，可以点击图中的元素名，如下图中按字母顺序排列的元素列表，或者点击其他元素中提及的元素名。

　　

<?xml version="1.0" encoding="utf-8"?>

<manifest>

    <uses-permission />
    <permission />
    <permission-tree />
    <permission-group />
    <instrumentation />
    <uses-sdk />
    <uses-configuration />  
    <uses-feature />  
    <supports-screens />  
    <compatible-screens />  
    <supports-gl-texture />  

    <application>

        <activity>
            <intent-filter>
                <action />
                <category />
                <data />
            </intent-filter>
            <meta-data />
        </activity>

        <activity-alias>
            <intent-filter> . . . </intent-filter>
            <meta-data />
        </activity-alias>

        <service>
            <intent-filter> . . . </intent-filter>
            <meta-data/>
        </service>

        <receiver>
            <intent-filter> . . . </intent-filter>
            <meta-data />
        </receiver>

        <provider>
            <grant-uri-permission />
            <meta-data />
        </provider>

        <uses-library />

    </application>

</manifest>

　　在manifest 文件中出现的所有元素都是根据字母顺序排列的。它们都是规定的元素，不能添加自定义的元素或属性。

    <action> 
    <activity> 
    <activity-alias> 
    <application> 
    <category> 
    <data> 
    <grant-uri-permission> 
    <instrumentation> 
    <intent-filter> 
    <manifest> 
    <meta-data> 
    <permission> 
    <permission-group> 
    <permission-tree> 
    <provider> 
    <receiver> 
    <service> 
    <supports-screens> 
    <uses-configuration> 
    <uses-feature> 
    <uses-library> 
    <uses-permission> 
    <uses-sdk>

　文件约定

　　下面是一些普遍应用在清单中的所有元素和属性的约定和规则。

　    元素

　　只有 <manifest> 和 <application>元素是必须的，而且有且只出现一次。其他的元素可以出现很多次或者并不出现-但是它们出现在manifest中肯定有它的目的。

　　如果一个元素包含某些东西，那么它就是包含了其它元素。所有值通过属性来设置，不会作为元素内的字符数据。

　　同一层次上的元素排列通常是无序的。例如，<activity>，<provider>，和<service>元素可以任意排列。（<activity-alias>元素是这个规则的例外：它必须跟在被它别名的<activity>后面）

   　属性

　　从某种形式上来讲，所有属性都是可选的。然而，有些情况下，一个元素必须指定属性来实现它的目的。使用文档作为指引。对于真正可选的属性，它会提及一个默认值或讲述在规范缺少的时候会发生什么。

　　除了根<manifest>元素的一些属性外，所有属性名以一个android:前缀开头——例如，android:alwaysRetainTaskState。因为前缀是普遍的，在文档中通过名称引用属性时通常会忽略它。

   　声明类名

　　许多元素对应一个Java对象，包括表示应用程序自身的元素（<application>元素）和它的主要组件——活动（<activity>），服务（<service>），广播接收器（<receiver>），以及内容提供者（<provider>）。

　　如果你定义一个组件类（Activity，Service，BroadcastReceiver，和ContentProvider）的子类，你总是会通过name属性来声明这个子类。这个name必须指定包的全路径，例如，一个Service的子类可能被声明如下：

<manifest . . . >
    <application . . . >
        <service android:name="com.example.project.SecretService" . . . >
            . . .
        </service>
        . . .
    </application>
</manifest>

　　然而，作为简写，如果字符的第一个字符是一个点，那么字符串被尾加到应用程序的包名（正如<manifest>元素的package属性指定的那样）后面。以下赋值和上面的相同：

<manifest package="com.example.project" . . . >
    <application . . . >
        <service android:name=".SecretService" . . . >
            . . .
        </service>
        . . .
    </application>
</manifest>

　　当启动一个组件时，Android会创建这个子类名的一个实例。如果没有指定这个子类，则创建一个基类的实例。

　　多值

　　如果一个元素能够指定多个值，这个元素可以重复定义多个，而非列举多个值在这个元素中。例如，一个意图过滤器可以列举多个动作：

<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

　　如果资源是在应用程序的相同包中，资源的包名可以被忽略，type是资源的类型——诸如"string"或"drawable"——而name是标识指定资源的名称。例如：

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

　　主题的值可以用类似的方式来表达，但是它的前导是'?'而非'@'：

?[package:]type:name

　　字符串值

　　在属性值为字符串的地方，必须使用双反斜杠（'\\'）来转义字符——例如，'\\n'用作回车或'\\uxxxx'用作一个Unicode字符（注：统一码）。

文件特性

　　下面的章节描述一些Android特性如何被反映在清单文件中。

　　Intent Filters

　　应用程序的核心组件（活动，服务，和广播接收器）是通过意图来激活。一个意图是一簇描述期待动作的信息（一个Intent对象）——包含被付诸动作的数据，应该执行该动作的组件的分类，以及其它相关的指令。Android定位一个合适的组件以响应意图，启动组件的一个新实例如果需要它的话，以及把那个Intent对象传给它。

　　组件通过意图过滤器宣传它们的功能——它们可以响应的意图的类型。因为Android系统必须知道一个组件在它启动组件前可以处理哪些意图，所以意图过滤器被指定在清单中作为<intent-filter>元素。一个组件可能有任意数量的过滤器，每一个描述不同的功能。

　　一个显式命名一个目标组件的意图将激活那个组件；过滤器不扮演角色。但一个不通过名称指定目标的组件可以激活一个组件，仅当它可以传递通过组件的过滤器的其中一个。

　　想获取关于Intent对象如何和意图过滤器测试的信息，请参见单独的文档，意图和意图过滤器

　　Icons and Labels

　　一些元素拥有icon和label属性用于一个小图标和文本标签，它们可以被显示给用户。一些还拥有一个description属性用于还可以被显示在屏幕上的较长的解释性文本。例如，<permission>元素有这全部三个属性，以致于当用户被询问是否授予权限给一个曾经请求它的应用程序时，代表权限的图标，权限的名称，以及它意味的东西的描述可以全部被呈现给用户。

　　在每种情况下，设置在一个包含元素里的图标和标签成为所有容器的子元素的默认图标和标签。因此，设置在<application>元素中的图标和标签是应用程序组件中每一个的默认图标和标签。类似地，为一个组件设置的图标和标签——例如，一个<activity>元素——是该组件的<intent-filter>元素的每一个的默认设置。如果一个<application>元素设置一个标签，但一个活动和它的意图过滤器没有设置，那么应用程序的标签被视为那个活动和意图过滤器的标签。

　　设置到一个意图过滤器的图标和标签被用来代表一个组件，每当该组件向用户呈现为满足过滤器所宣传的功能时（注：待考）。例如，一个带"android.intent.action.MAIN"和"android.intent.category.LAUNCHER"设置的过滤器把一个活动宣称为初始化应用程序的活动——就是说，作为一个应该被显示在应用程序启动器中的活动。因此设置在过滤器中的图标和标签是被显示在启动器中的图标和标签。

　　Permissions

　　权限是一种限制，限制对代码的一部分或对设备上的数据的访问。施加限制是为了保护可能被误用来篡改或损坏用户体验的关键数据和代码。

　　每种权限被一个唯一的标签标识。标签经常指示被限制的动作。例如，这里有一些被Android定义的权限：

android.permission.CALL_EMERGENCY_NUMBERS 
android.permission.READ_OWNER_DATA 
android.permission.SET_WALLPAPER 
android.permission.DEVICE_POWER

　　一个特性可以被最多一个权限保护。

　　如果一个应用程序需要访问一个权限保护的特性，那么它必须在清单中用一个<uses-permission>元素声明它必需那个权限。然后，当应用程序被安装在设备上时，安装器通过检查签有应用程序证书的权威，以及在一些情况下询问用户，来决定是否授权请求的权限。如果权限被授权，那么应用程序有能力使用被包含的特性。如果没有，那么它访问那些特性的尝试将简单地失败而不会出现对用户的任何通知。

　　一个应用程序还可以用权限保护它自己的组件（活动，服务，广播接收器，以及内容提供者）。它可以借用Android定义的（列举在android.Manifest.permission中）或被其它应用程序声明的任意权限。或者它可以定义它自己的。一个新的权限用<permission>来声明。例如，一个活动可以如下所示地被保护：

<manifest . . . >
    <permission android:name="com.example.project.DEBIT_ACCT" . . . />
    <uses-permission android:name="com.example.project.DEBIT_ACCT" />
    . . .
    <application . . .>
        <activity android:name="com.example.project.FreneticActivity"
                  android:permission="com.example.project.DEBIT_ACCT"
                  . . . >
            . . .
        </activity>
    </application>
</manifest>

　　注意，在这个示例中，DEBIT_ACCT权限不只是用<permission>元素来声明，还用<uses-permission>请求使用它。它的使用必须被请求，以便应用程序的其他组件启动被保护的活动，即便保护是应用程序自身施加的。

　　如果，在相同的示例中，权限属性被设置成一个被声明在其它地方的权限（诸如android.permission.CALL_EMERGENCY_NUMBERS，没必要再次用一个<permission>元素来声明它。然而，它仍然有必要用<uses-permission>请求使用它）。（注：此处貌似少了个右括号）

　　<permission-tree>元素为一组将被定义在代码中的权限声明一个名字空间。而<permission-group>定义用于一个权限集合的标签（那些在清单中用<permission>元素声明的以及那些在其它地方声明的权限）。它只影响权限在呈现给用户的时候如何被分组。<permission-group>元素并不指定哪个权限属于该组；它只是赋予组一个名称。通过把组的名称赋给<permission>元素的permissionGroup属性，把一个权限放进组中。

　　Libraries

　　每个应用程序被链接到默认的Android库，它包含构建应用程序的基本包（带有通用类诸如Activity，Service，Intent，View，Button，Application，ContentProvider，等等

　　然而，一些包寄居在它们自己的库中。如果你的应用程序使用来自任意这些包的代码，那么它必须显式地要求链接到它们。清单必须包含一个分离的<uses-library>元素以命名这些库中的每一个。（库的名称可以在包的文档中找到。）

　　

原文：

The AndroidManifest.xml File

In this document

Every application must have an AndroidManifest.xml file (with precisely that name) in its root directory. The manifest presents essential information about the application to the Android system, information the system must have before it can run any of the application's code. Among other things, the manifest does the following:

• It names the Java package for the application. The package name serves as a unique identifier for the application.
• It describes the components of the application — the activities, services, broadcast receivers, and content providers that the application is composed of. It names the classes that implement each of the components and publishes their capabilities (for example, which Intent messages they can handle). These declarations let the Android system know what the components are and under what conditions they can be launched.
• It determines which processes will host application components.
• It declares which permissions the application must have in order to access protected parts of the API and interact with other applications.
• It also declares the permissions that others are required to have in order to interact with the application's components.
• It lists the Instrumentation classes that provide profiling and other information as the application is running. These declarations are present in the manifest only while the application is being developed and tested; they're removed before the application is published.
• It declares the minimum level of the Android API that the application requires.
• It lists the libraries that the application must be linked against.

Structure of the Manifest File

---

The diagram below shows the general structure of the manifest file and every element that it can contain. Each element, along with all of its attributes, is documented in full in a separate file. To view detailed information about any element, click on the element name in the diagram, in the alphabetical list of elements that follows the diagram, or on any other mention of the element name.

<?xml version="1.0" encoding="utf-8"?>
<manifest>
<uses-permission/>
<permission/>
<permission-tree/>
<permission-group/>
<instrumentation/>
<uses-sdk/>
<uses-configuration/>
<uses-feature/>
<supports-screens/>
<compatible-screens/>
<supports-gl-texture/>
<application>
    <activity>
        <intent-filter>
            <action/>
            <category/>
            <data/>
        </intent-filter>
        <meta-data/>
    </activity>
    <activity-alias>
        <intent-filter> . . . </intent-filter>
        <meta-data/>
    </activity-alias>
    <service>
        <intent-filter> . . . </intent-filter>
        <meta-data/>
    </service>
    <receiver>
        <intent-filter> . . . </intent-filter>
        <meta-data/>
    </receiver>
    <provider>
        <grant-uri-permission/>
        <meta-data/>
    </provider>
    <uses-library/>
</application>
</manifest>                                                            

All the elements that can appear in the manifest file are listed below in alphabetical order. These are the only legal elements; you cannot add your own elements or attributes.

<action>
<activity>
<activity-alias>
<application>
<category>
<data>
<grant-uri-permission>
<instrumentation>
<intent-filter>
<manifest>
<meta-data>
<permission>
<permission-group>
<permission-tree>
<provider>
<receiver>
<service>
<supports-screens>
<uses-configuration>
<uses-feature>
<uses-library>
<uses-permission>
<uses-sdk>

File Conventions

---

Some conventions and rules apply generally to all elements and attributes in the manifest:

Elements

Only the <manifest> and<application>elements are required, they each must be present and can occur only once. Most of the others can occur many times or not at all — although at least some of them must be present for the manifest to accomplish anything meaningful.

If an element contains anything at all, it contains other elements. All values are set through attributes, not as character data within an element.

Elements at the same level are generally not ordered. For example,<activity>, <provider>, and <service> elements can be intermixed in any sequence. (An <activity-alias>element is the exception to this rule: It must follow the <activity> it is an alias for.)

Attributes

In a formal sense, all attributes are optional. However, there are some that must be specified for an element to accomplish its purpose. Use the documentation as a guide. For truly optional attributes, it mentions a default value or states what happens in the absence of a specification.

Except for some attributes of the root <manifest> element, all attribute names begin with an android: prefix — for example, android:alwaysRetainTaskState. Because the prefix is universal, the documentation generally omits it when referring to attributes by name.

Declaring class names

Many elements correspond to Java objects, including elements for the application itself (the <application> element) and its principal components — activities (<activity>), services (<service>), broadcast receivers (<receiver>), and content providers (<provider>).

If you define a subclass, as you almost always would for the component classes (Activity, Service, BroadcastReceiver, and ContentProvider), the subclass is declared through a name attribute. The name must include the full package designation. For example, an Service subclass might be declared as follows:

<manifest . . . ><application . . . ><serviceandroid:name="com.example.project.SecretService" . . . >
            . . .
        </service>
        . . .
    </application></manifest>

However, as a shorthand, if the first character of the string is a period, the string is appended to the application's package name (as specified by the <manifest> element's package attribute). The following assignment is the same as the one above:

<manifestpackage="com.example.project" . . . ><application . . . ><serviceandroid:name=".SecretService" . . . >
            . . .
        </service>
        . . .
    </application></manifest>

When starting a component, Android creates an instance of the named subclass. If a subclass isn't specified, it creates an instance of the base class.

Multiple values

If more than one value can be specified, the element is almost always repeated, rather than listing multiple values within a single element. For example, an intent filter can list several actions:

<intent-filter . . . ><actionandroid:name="android.intent.action.EDIT"/><actionandroid:name="android.intent.action.INSERT"/><actionandroid:name="android.intent.action.DELETE"/>
    . . .
</intent-filter>

Resource values

Some attributes have values that can be displayed to users — for example, a label and an icon for an activity. The values of these attributes should be localized and therefore set from a resource or theme. Resource values are expressed in the following format,

 

@[package:]type:name

where the package name can be omitted if the resource is in the same package as the application, type is a type of resource — such as "string" or "drawable" — and name is the name that identifies the specific resource. For example:

<activityandroid:icon="@drawable/smallPic" . . . >

Values from a theme are expressed in a similar manner, but with an initial '?' rather than '@':

?[package:]type:name

String values

Where an attribute value is a string, double backslashes ('\\') must be used to escape characters — for example, '\\n' for a newline or '\\uxxxx' for a Unicode character.

File Features

---

The following sections describe how some Android features are reflected in the manifest file.

Intent Filters

The core components of an application (its activities, services, and broadcast receivers) are activated by intents. An intent is a bundle of information (an Intent object) describing a desired action — including the data to be acted upon, the category of component that should perform the action, and other pertinent instructions. Android locates an appropriate component to respond to the intent, launches a new instance of the component if one is needed, and passes it the Intent object.

Components advertise their capabilities — the kinds of intents they can respond to — through intent filters. Since the Android system must learn which intents a component can handle before it launches the component, intent filters are specified in the manifest as <intent-filter> elements. A component may have any number of filters, each one describing a different capability.

An intent that explicitly names a target component will activate that component; the filter doesn't play a role. But an intent that doesn't specify a target by name can activate a component only if it can pass through one of the component's filters.

For information on how Intent objects are tested against intent filters, see a separate document, Intents and Intent Filters.

Icons and Labels

A number of elements have icon and label attributes for a small icon and a text label that can be displayed to users. Some also have a description attribute for longer explanatory text that can also be shown on-screen. For example, the <permission>element has all three of these attributes, so that when the user is asked whether to grant the permission to an application that has requested it, an icon representing the permission, the name of the permission, and a description of what it entails can all be presented to the user.

In every case, the icon and label set in a containing element become the default icon and label settings for all of the container's subelements. Thus, the icon and label set in the <application> element are the default icon and label for each of the application's components. Similarly, the icon and label set for a component — for example, an <activity> element — are the default settings for each of the component's <intent-filter> elements. If an<application> element sets a label, but an activity and its intent filter do not, the application label is treated as the label for both the activity and the intent filter.

The icon and label set for an intent filter are used to represent a component whenever the component is presented to the user as fulfilling the function advertised by the filter. For example, a filter with "android.intent.action.MAIN" and "android.intent.category.LAUNCHER" settings advertises an activity as one that initiates an application — that is, as one that should be displayed in the application launcher. The icon and label set in the filter are therefore the ones displayed in the launcher.

Permissions

A permission is a restriction limiting access to a part of the code or to data on the device. The limitation is imposed to protect critical data and code that could be misused to distort or damage the user experience.

Each permission is identified by a unique label. Often the label indicates the action that's restricted. For example, here are some permissions defined by Android:

android.permission.CALL_EMERGENCY_NUMBERS
android.permission.READ_OWNER_DATA
android.permission.SET_WALLPAPER
android.permission.DEVICE_POWER

A feature can be protected by at most one permission.

If an application needs access to a feature protected by a permission, it must declare that it requires that permission with a <uses-permission> element in the manifest. Then, when the application is installed on the device, the installer determines whether or not to grant the requested permission by checking the authorities that signed the application's certificates and, in some cases, asking the user. If the permission is granted, the application is able to use the protected features. If not, its attempts to access those features will simply fail without any notification to the user.

An application can also protect its own components (activities, services, broadcast receivers, and content providers) with permissions. It can employ any of the permissions defined by Android (listed in android.Manifest.permission) or declared by other applications. Or it can define its own. A new permission is declared with the <permission> element. For example, an activity could be protected as follows:

<manifest . . . ><permissionandroid:name="com.example.project.DEBIT_ACCT" . . . /><uses-permissionandroid:name="com.example.project.DEBIT_ACCT"/>
    . . .
    <application . . .><activityandroid:name="com.example.project.FreneticActivity"android:permission="com.example.project.DEBIT_ACCT"
                  . . . >
            . . .
        </activity></application></manifest>

Note that, in this example, the DEBIT_ACCT permission is not only declared with the <permission> element, its use is also requested with the <uses-permission> element. Its use must be requested in order for other components of the application to launch the protected activity, even though the protection is imposed by the application itself.

If, in the same example, the permission attribute was set to a permission declared elsewhere (such as android.permission.CALL_EMERGENCY_NUMBERS, it would not have been necessary to declare it again with a <permission> element. However, it would still have been necessary to request its use with <uses-permission>.

The <permission-tree> element declares a namespace for a group of permissions that will be defined in code. And <permission-group>defines a label for a set of permissions (both those declared in the manifest with <permission> elements and those declared elsewhere). It affects only how the permissions are grouped when presented to the user. The <permission-group>element does not specify which permissions belong to the group; it just gives the group a name. A permission is placed in the group by assigning the group name to the<permission> element's permissionGroup attribute.

Libraries

Every application is linked against the default Android library, which includes the basic packages for building applications (with common classes such as Activity, Service, Intent, View, Button, Application, ContentProvider, and so on).

However, some packages reside in their own libraries. If your application uses code from any of these packages, it must explicitly asked to be linked against them. The manifest must contain a separate <uses-library> element to name each of the libraries. (The library name can be found in the documentation for the package.)