学步园

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文件（名称是固定的）在根目录下。这个清单描述了安卓系统程序的基本信息，系统运行必须获得这些信息才能运行此程序。除了这些，这个清单还包含如下信息：

---

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 />
            <path-permission />
        </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.

下面列出的所有元素都可以出现在清单文件中。这些元素名称是确定的，你不能在清单中添加自己的元素或者属性。

---

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

所有元素在文档清单中普遍适用的一些约定和规则：

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> 后面。）

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.因为这个前缀是确定的，文档在引用属性时一般都忽略了它。

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属性声明。这个名称必须包含完成的包路径。比如，一个服务子类声明如下：

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

当启动一个组建时，安卓创建一个子类的实例，如果子类没有指定，它将创建一个基类的实例。／／这个不太明白什么意思。

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>

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:

如果资源与程序在同一个包中，可以忽略包名。type指明资源类型－－比如“string”或者“drawable”－－name是特定资源的标识。例如：

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

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

主题的引用表示方法类似，不过是以“?”而不是“@”开始：

?[package:]type:name

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编码字符。

---

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

下面各段声明了那些安卓特性被体现在清单文件中。

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激活的。Intent是一堆被捆绑在一起的信息（一个Intent对象）及将要发生的事情－－包括预备的数据，准备执行的动作的类别，和其他相关信息。安卓定位一个合适的组建来回应这个Intent，如果需要会启动一个新的组建实例，并将Intent对象传递给实例。

／／这一个翻译的不好，大家看着原文对照YY下吧。＝。＝！

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.

组件宣告它们的能力－－那些种类的Intent它们可以响应－－通过意图过滤器。在一个组件启动前，安卓系统必须了解那些意图可以被它处理。意图过滤器通过清单文件中的 <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.

一个明确指定了目标组件的Intent可以激活组件，意图过滤器这种情况下不起作用。一个Intent也可以激活没有通过名称明确指定的组件，但是这个Intent要符合组件的意图过滤器。

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

更多的使用意图过滤器测试意图的信息请参考单独的文档， Intents and Intent Filters。

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.

一些元素都有图标和标签属性，可以向用户显示一个小图标和一个文本标签。也有一个元素有一个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> 元素－－默认设置由意图过滤器指定。如果一个<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"设置的过滤器启动一个程序－－在启动时将显示过滤器中设置的图标和标签。

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.

如果程序需要访问一个被权限保护的功能，它必须在清单文件中使用一个<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.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 asandroid.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>.

假如在同样的例子中，这个权限属性被设置为其他地方声明的权限（例如asandroid.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 定义的。

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

当然，一些包驻留杂它们自己的库中，如果你的程序使用了这些库的代码，它必须明确的要求连接它们。清单文件必须包含<uses-library>元素去声明每一个库。（库的名称可以在包中的文档中找到。）