【翻译】(44)AndroidManifest.xml文件
【翻译】(44)AndroidManifest.xml文件
?
see
http://developer.android.com/guide/topics/manifest/manifest-intro.html
?
原文见
http://developer.android.com/guide/topics/manifest/manifest-intro.html
?
-------------------------------
?
The AndroidManifest.xml File
?
AndroidManifest.xml文件
?
-------------------------------
?
In this document
?
本文目录
?
* Structure of the Manifest File 清单文件的结构
* File Conventions 文件约定
* File Features 文件特性
* Intent Filters 意图过滤器
* Icons and Labels 图标和标签
* Permissions 权限
* Libraries 库
?
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:
?
每个应用程序必须在它的根目录中拥有一个AndroidManifest.xml文件（带有正好的那个名称）。清单呈现关于应用程序的本质信息给Android系统，系统必须在它可以运行应用程序的任意代码之前拥有这些信息。在其它事情中，清单做以下内容：
?
* It names the Java package for the application. The package name serves as a unique identifier for the application.
?
* 它为应用程序命名Java包。包名担当应用程序的唯一标识符。
?
* 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.
?
* 它描述应用程序的组件——活动，服务，广播接收器，以及内容提供者，应用程序由它们组成。它命名实现组件的每一个的类以及发布它们的功能（例如，它们可以处理哪种Intent消息）。这些声明让Android系统知道组件是什么以及在什么条件下它们可以被启动。
?
* 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.
?
* 它声明应用程序必须拥有哪些权限以访问API的被保护部分以及与其它应用程序交互。
?
* 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.
?
* 它列举在应用程序正在运行时提供性能剖析的Instrumentation类和其它信息。这些声明出现在清单中，仅当应用程序正在被开发和测试；在应用程序被发布之前它们被移除。
?
* It declares the minimum level of the Android API that the application requires.
?
* 它声明应用程序必需的Android API的最小级别。
?
* 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.
?
只有<manifest>和<application>元素是必需的，它们每一个必须出现并且只可以发生一次。其它大部分可以发生多次或完全不发生——虽然它们中至少有一些可以因为清单要实现某些有意义的事情而必须出现。
?
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.)
?
在相同层次的元素通常不被排序。例如，<activity>，<provider>，和<service>元素可以被交错成任意序列。（一个<activity-alias>元素是这个规则的例外：它必须跟在被它别名的<activity>后面。）
?
* 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.
?
除了根<manifest>元素的一些属性外，所有属性名以一个android:前缀开头——例如，android:alwaysRetainTaskState。因为前缀是全体的，所以当通过名称引用属性时文档通常会忽略它。
?
* 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>).
?
许多元素对应于Java对象，包括表示应用程序自身的元素（<application>元素）和它的主要组件——活动（<activity>），服务（<service>），广播接收器（<receiver>），以及内容提供者（<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:
?
如果你定义一个组件类（Activity，Service，BroadcastReceiver，和ContentProvider）的子类，正如你几乎总是会做的那样，那么子类通过name属性来声明。name必须包含完整的包指定。例如，一个Service的子类可能被声明如下：
?
-------------------------------
?
<manifest . . . >
? ? <application . . . >
? ? ? ? <service android: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:
?
然而，作为简写，如果字符的第一个字符是一个点，那么字符串被尾加到应用程序的包名（正如<manifest>元素的package属性指定的那样）后面。以下赋值和上面的相同：
?
-------------------------------
?
<manifest package="com.example.project" . . . >
? ? <application . . . >
? ? ? ? <service android: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.
?
当启动一个组件时，Android创建具名子类的一个实例。如果不指定一个子类，它创建基类的一个实例。
?
* 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 . . . >
? ? <action android:name="android.intent.action.EDIT" />
? ? <action android:name="android.intent.action.INSERT" />
? ? <action android: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:
?
这里包名可以被忽略，如果资源是在应用程序的相同包中，类型是资源的类型——诸如"string"或"drawable"——而名称是标识指定资源的名称。例如：
?
-------------------------------
?
<activity android: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.
?
在属性值为字符串的地方，必须使用双反斜杠（'\\'）来转义字符——例如，'\\n'用作回车或'\\uxxxx'用作一个Unicode字符（注：统一码）。
?
-------------------------------
?
File Features
?
文件特性
?
The following sections describe how some Android features are reflected in the manifest file.
?
以下章节描述一些Android特性如何被反映在清单文件中。
?
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.
?
应用程序的核心组件（它的活动，服务，和广播接收器）通过意图来激活。一个意图是一簇描述期待动作的信息（一个Intent对象）——包含被付诸动作的数据，应该执行该动作的组件的分类，以及其它相关的指令。Android定位一个合适的组件以响应意图，启动组件的一个新实例如果需要它的话，以及把那个Intent对象传给它。
?
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.
?
组件通过意图过滤器宣传它们的功能——它们可以响应的意图的类型。因为Android系统必须知道一个组件在它启动组件前可以处理哪些意图，所以意图过滤器被指定在清单中作为<intent-filter>元素。一个组件可能有任意数量的过滤器，每一个描述不同的功能。
?
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.
?
想获取关于Intent对象如何和意图过滤器测试的信息，请参见单独的文档，意图和意图过滤器。
?
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.
?
一些元素拥有icon和label属性用于一个小图标和文本标签，它们可以被显示给用户。一些还拥有一个description属性用于还可以被显示在屏幕上的较长的解释性文本。例如，<permission>元素有这全部三个属性，以致于当用户被询问是否授予权限给一个曾经请求它的应用程序时，代表权限的图标，权限的名称，以及它意味的东西的描述可以全部被呈现给用户。
?
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.
?
在每种情况下，设置在一个包含元素里的图标和标签成为所有容器的子元素的默认图标和标签。因此，设置在<application>元素中的图标和标签是应用程序组件中每一个的默认图标和标签。类似地，为一个组件设置的图标和标签——例如，一个<activity>元素——是该组件的<intent-filter>元素的每一个的默认设置。如果一个<application>元素设置一个标签，但一个活动和它的意图过滤器没有设置，那么应用程序的标签被视为那个活动和意图过滤器的标签。
?
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.
?
设置到一个意图过滤器的图标和标签被用来代表一个组件，每当该组件向用户呈现为满足过滤器所宣传的功能时（注：待考）。例如，一个带"android.intent.action.MAIN"和"android.intent.category.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定义的权限：
?
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.
?
如果一个应用程序需要访问一个权限保护的特性，那么它必须在清单中用一个<uses-permission>元素声明它必需那个权限。然后，当应用程序被安装在设备上时，安装器通过检查签有应用程序证书的权威，以及在一些情况下询问用户，来决定是否授权请求的权限。如果权限被授权，那么应用程序有能力使用被包含的特性。如果没有，那么它访问那些特性的尝试将简单地失败而不会出现对用户的任何通知。
?
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:
?
一个应用程序还可以用权限保护它自己的组件（活动，服务，广播接收器，以及内容提供者）。它可以借用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>
?
-------------------------------
?
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.
?
注意，在这个示例中，DEBIT_ACCT权限不只是用<permission>元素来声明，还用<uses-permission>请求使用它。它的使用必须被请求，以便应用程序的其他组件启动被保护的活动，即便保护是应用程序自身施加的。
?
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>.
?
如果，在相同的示例中，权限属性被设置成一个被声明在其它地方的权限（诸如android.permission.CALL_EMERGENCY_NUMBERS，没必要再次用一个<permission>元素来声明它。然而，它仍然有必要用<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.
?
<permission-tree>元素为一组将被定义在代码中的权限声明一个名字空间。而<permission-group>定义用于一个权限集合的标签（那些在清单中用<permission>元素声明的以及那些在其它地方声明的权限）。它只影响权限在呈现给用户的时候如何被分组。<permission-group>元素并不指定哪个权限属于该组；它只是赋予组一个名称。通过把组的名称赋给<permission>元素的permissionGroup属性，把一个权限放进组中。
?
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).
?
每个应用程序被链接到默认的Android库，它包含构建应用程序的基本包（带有通用类诸如Activity，Service，Intent，View，Button，Application，ContentProvider，等等
?
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.)
?
然而，一些包寄居在它们自己的库中。如果你的应用程序使用来自任意这些包的代码，那么它必须显式地要求链接到它们。清单必须包含一个分离的<uses-library>元素以命名这些库中的每一个。（库的名称可以在包的文档中找到。）
?
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
?
除特别说明外，本文在Apache 2.0下许可。细节和限制请参考内容许可证。
?
Android 4.0 r1 - 27 Jan 2012 1:49
?
-------------------------------
?
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
?
（此页部分内容基于Android开源项目，以及使用根据创作公共2.5来源许可证描述的条款进行修改）
?
（本人翻译质量欠佳，请以官方最新内容为准，或者参考其它翻译版本：
* ソフトウェア技術ドキュメントを勝手に翻訳
http://www.techdoctranslator.com/android
* Ley's Blog
http://leybreeze.com/blog/
* 农民伯伯
http://www.cnblogs.com/over140/
* Android中文翻译组
http://androidbox.sinaapp.com/
）
