【翻译】(46)activity元素

【翻译】(46)activity元素

 

see

http://developer.android.com/guide/topics/manifest/activity-element.html

 

原文见

http://developer.android.com/guide/topics/manifest/activity-element.html

 

-------------------------------

 

<activity>

 

activity元素

 

-------------------------------

 

* syntax:

 

* 语法：

 

-------------------------------

 

<activity android:allowTaskReparenting=["true" | "false"]

          android:alwaysRetainTaskState=["true" | "false"]

          android:clearTaskOnLaunch=["true" | "false"]

          android:configChanges=["mcc", "mnc", "locale",

                                 "touchscreen", "keyboard", "keyboardHidden",

                                 "navigation", "screenLayout", "fontScale", "uiMode",

                                 "orientation", "screenSize", "smallestScreenSize"]

          android:enabled=["true" | "false"]

          android:excludeFromRecents=["true" | "false"]

          android:exported=["true" | "false"]

          android:finishOnTaskLaunch=["true" | "false"]

          android:hardwareAccelerated=["true" | "false"]

          android:icon="drawable resource"

          android:label="string resource"

          android:launchMode=["multiple" | "singleTop" |

                              "singleTask" | "singleInstance"]

          android:multiprocess=["true" | "false"]

          android:name="string"

          android:noHistory=["true" | "false"]  

          android:permission="string"

          android:process="string"

          android:screenOrientation=["unspecified" | "user" | "behind" |

                                     "landscape" | "portrait" |

                                     "reverseLandscape" | "reversePortrait" |

                                     "sensorLandscape" | "sensorPortrait" |

                                     "sensor" | "fullSensor" | "nosensor"]

          android:stateNotNeeded=["true" | "false"]

          android:taskAffinity="string"

          android:theme="resource or theme"

          android:uiOptions=["none" | "splitActionBarWhenNarrow"]

          android:windowSoftInputMode=["stateUnspecified",

                                       "stateUnchanged", "stateHidden",

                                       "stateAlwaysHidden", "stateVisible",

                                       "stateAlwaysVisible", "adjustUnspecified",

                                       "adjustResize", "adjustPan"] >   

    . . .

</activity>

 

-------------------------------

 

* contained in:

 

* 包含在：

 

<application>

 

* can contain:

 

* 可以包含：

 

<intent-filter> 

<meta-data>

 

* description:

 

* 描述：

 

Declares an activity (an Activity subclass) that implements part of the application's visual user interface. All activities must be represented by <activity> elements in the manifest file. Any that are not declared there will not be seen by the system and will never be run.

 

声明一个活动（一个Activity子类），它实现应用程序的可视化用户界面的部分。所有活动必须通过在清单文件中被<activity>元素请求。任意不在那里声明的活动将不会被系统看到并且将从不被运行。

 

* attributes:

 

* 属性：

 

* android:allowTaskReparenting

 

Whether or not the activity can move from the task that started it to the task it has an affinity for when that task is next brought to the front — "true" if it can move, and "false" if it must remain with the task where it started.

 

活动是否可以从启动它的任务中移动到和它拥有关系的任务中，当那个任务接下来被带到前方的时候——"true"如果它可以移动，而"false"如果它必须停留在它启动时所在的任务中。

 

If this attribute is not set, the value set by the corresponding allowTaskReparenting attribute of the <application> element applies to the activity. The default value is "false".

 

如果这个属性不被设置，那么该值被应用到该活动的<application>元素相应的allowTaskReparenting属性设置。默认值是"false"。

 

Normally when an activity is started, it's associated with the task of the activity that started it and it stays there for its entire lifetime. You can use this attribute to force it to be re-parented to the task it has an affinity for when its current task is no longer displayed. Typically, it's used to cause the activities of an application to move to the main task associated with that application.

 

通常当活动被启动时，它被关联到启动它的活动的任务而它在它的整个生命期中一直在那里。你可以使用这个属性强制它被重新从属至它拥有关系的任务，当它的当前任务不再被显示时。通常，它被用于导致一个应用程序的活动移动到关联那个应用程序的主任务。

 

For example, if an e-mail message contains a link to a web page, clicking the link brings up an activity that can display the page. That activity is defined by the browser application, but is launched as part of the e-mail task. If it's reparented to the browser task, it will be shown when the browser next comes to the front, and will be absent when the e-mail task again comes forward.

 

例如，如果一个电子邮件消息包含对一个网页的链接，点击链接会带起一个可以显示页面的活动。那个活动被浏览器应用程序定义，但被启动作为电子邮件任务的部分。如果它被重新从属至浏览器任务，那么当浏览器下一次来到前方时它将被显示，并且在电子邮件再一次向前回来的时候它将消失。

 

The affinity of an activity is defined by the taskAffinity attribute. The affinity of a task is determined by reading the affinity of its root activity. Therefore, by definition, a root activity is always in a task with the same affinity. Since activities with "singleTask" or "singleInstance" launch modes can only be at the root of a task, re-parenting is limited to the "standard" and "singleTop" modes. (See also the launchMode attribute.)

 

一个活动的关系是被taskAffinity属性定义的。任务的关系通过读取它的根活动的关系来决定的。因此，根据定义，根活动总是在带有相同关系的任务中。因为带有"singleTask"或"singleInstance"启动模式的活动只可能是在一个任务的根，所以重新从属被限制至"standard"和"singleTop"模式。（另见launchMode属性。）

 

* android:alwaysRetainTaskState

 

Whether or not the state of the task that the activity is in will always be maintained by the system — "true" if it will be, and "false" if the system is allowed to reset the task to its initial state in certain situations. The default value is "false". This attribute is meaningful only for the root activity of a task; it's ignored for all other activities.

 

该活动所在的任务的状态是否将总是被系统维护——"true"如果它将是，而"false"如果系统被允许在某些情况下重置任务到它的初始状态。默认值为"false"。这个属性仅对于任务的根活动来说有意义；对于其它所有活动来说它被忽略。

 

Normally, the system clears a task (removes all activities from the stack above the root activity) in certain situations when the user re-selects that task from the home screen. Typically, this is done if the user hasn't visited the task for a certain amount of time, such as 30 minutes.

 

通常，在某些情况下当用户重新选择来自主屏幕的那个任务时，系统清空一个任务（移除从堆栈中根活动以上的所有活动）。通常，会做这件事如果用户在一定数量的时间内还没有访问过任务，诸如30分钟。

 

However, when this attribute is "true", users will always return to the task in its last state, regardless of how they get there. This is useful, for example, in an application like the web browser where there is a lot of state (such as multiple open tabs) that users would not like to lose.

 

然而，当这个属性为"true"时，用户将总是返回到在它的最后状态中的任务，不管它们如何到达那里。这是有用的，例如，在一个像网页浏览器的应用程序中，存在许多用户不愿意失去的状态（诸如多个打开的标签页）。

 

* android:clearTaskOnLaunch

 

Whether or not all activities will be removed from the task, except for the root activity, whenever it is re-launched from the home screen — "true" if the task is always stripped down to its root activity, and "false" if not. The default value is "false". This attribute is meaningful only for activities that start a new task (the root activity); it's ignored for all other activities in the task.

 

所有活动是否将从任务中被移除，除了根活动，只要当它从主屏幕中被重新启动的时候——"true"如果该任务总是被剥下直至（注：待考）它的根活动，而"false"如果不是。默认值为"false"。这个属性仅对于启动新任务的活动有意义（根活动）；它对于任务中其它所有活动被忽略。

 

When the value is "true", every time users start the task again, they are brought to its root activity, regardless of what they were last doing in the task and regardless of whether they used BACK or HOME to last leave it. When the value is "false", the task may be cleared of activities in some situations (see the alwaysRetainTaskState attribute), but not always.

 

当该值为"true"时，每当用户再次启动任务，它们被带到它的根活动，不管它们最后在任务中做什么和不管它们是否使用BACK或HOME最后离开它。当该值为"false"时，任务可能在一些情况下被清空活动（见alwaysRetainTaskState属性），但不总是。

 

Suppose, for example, that someone launches activity P from the home screen, and from there goes to activity Q. The user next presses HOME, and then returns to activity P. Normally, the user would see activity Q, since that is what they were last doing in P's task. However, if P set this flag to "true", all of the activities on top of it (Q in this case) were removed when the user pressed HOME and the task went to the background. So the user sees only P when returning to the task.

 

例如，假设有人从主屏幕中启动活动P，并且从那里转到活动Q。接下来用户按HOME，然后返回到活动P。通常，用户看到活动Q，因为那是它们在P的任务中最后做的事情。然而，如果P设置这个标志为"true"，那么当用户按HOME时它的顶部的所有活动（这个情况下是Q）被移除，而任务转至后台。所以当返回到任务时用户只看到P。

 

If this attribute and allowTaskReparenting are both "true", any activities that can be re-parented are moved to the task they share an affinity with; the remaining activities are then dropped, as described above.

 

如果这个属性和allowTaskReparenting都是"true"，那么可以被重新从属的任意活动会被移动到它们共享关系的任务中；然后剩下的活动被卸下，正如上面描述的那样。

 

* android:configChanges

 

Lists configuration changes that the activity will handle itself. When a configuration change occurs at runtime, the activity is shut down and restarted by default, but declaring a configuration with this attribute will prevent the activity from being restarted. Instead, the activity remains running and its onConfigurationChanged() method is called.

 

列举活动将自己处理的配置改变。当配置改变发生在运行期时，默认下活动被关闭并重启，但用这个属性声明一个配置将阻止活动被重启。取而代之，活动保持运行而它的onConfigurationChanged()方法将被调用。

 

-------------------------------

 

Note: Using this attribute should be avoided and used only as a last-resort. Please read Handling Runtime Changes for more information about how to properly handle a restart due to a configuration change.

 

注意：应该避免使用这个属性和只作为一个最后采取的手段来使用。请阅读处理运行时改变以获取关于如何正确的处理配置改变导致的重启的更多信息。

 

-------------------------------

 

Any or all of the following strings are valid values for this attribute. Multiple values are separated by '|' — for example, "locale|navigation|orientation".

 

以下所有字符串的任意是这个属性的合法值。多个值用'|'分隔——例如，"locale|navigation|orientation"。

 

-------------------------------

 

* Value Description

 

* 值 描述

 

* "mcc" The IMSI mobile country code (MCC) has changed — a SIM has been detected and updated the MCC.

 

* "mcc" IMSI（注：International Mobile SubscriberIdentification Number，国际移动用户识别码）移动国家代码（MCC）已经改变——检测SIM卡并更新MCC。

 

* "mnc" The IMSI mobile network code (MNC) has changed — a SIM has been detected and updated the MNC.

 

* "mnc" IMSI移动网络代码（MNC）已经改变——检测SIM卡并更新MNC。

 

* "locale" The locale has changed — the user has selected a new language that text should be displayed in.

 

* "locale" 语言环境已经改变——用户选择一个新的语言，文本将用它来显示。

 

* "touchscreen" The touchscreen has changed. (This should never normally happen.)

 

* "touchscreen" 触摸屏已经改变。（正常情况下它从不应该发生。）

 

* "keyboard" The keyboard type has changed — for example, the user has plugged in an external keyboard.

 

* "keyboard" 键盘类型已经改变——例如，用户插入一个外部键盘。

 

* "keyboardHidden" The keyboard accessibility has changed — for example, the user has revealed the hardware keyboard.

 

* "keyboardHidden" 键盘可访问性已经改变——例如，用户展开硬件键盘。

 

* "navigation" The navigation type (trackball/dpad) has changed. (This should never normally happen.)

 

* "navigation" 导航类型（轨迹球/方向板）已经改变。（正常情况下这应该从不发生。）

 

* "screenLayout" The screen layout has changed — this might be caused by a different display being activated.

 

* "screenLayout" 屏幕布局已经改变——它可能由一个不同的显示器被激活导致的。

 

* "fontScale" The font scaling factor has changed — the user has selected a new global font size.

 

* "fontScale" 字体缩放因子已经改变——用户选择一个新的全局字体大小。

 

* "uiMode" The user interface mode has changed — this can be caused when the user places the device into a desk/car dock or when the the night mode changes. See UiModeManager. Introduced in API Level 8.

 

* "uiMode" 用户界面模式已经改变——当用户放置设备在一个桌面/汽车底座或当夜间模式改变时可能导致它。见UiModeManager，在API级别8中引入。

 

* "orientation" The screen orientation has changed — the user has rotated the device.

 

* "orientation" 屏幕方向已经改变——用户旋转设备。

 

-------------------------------

 

Note: If your application targets API level 13 or higher (as declared by the minSdkVersion and targetSdkVersion attributes), then you should also declare the "screenSize" configuration, because it also changes when a device switches between portrait and landscape orientations.

 

注意：如果你的应用程序的目标为API级别13或更高（正如minSdkVersion和targetSdkVersion属性描述的那样），那么你还应该声明"screenSize"配置，因为在设备从竖屏和宽屏之间切换的时候它也会改变。

 

-------------------------------

 

* "screenSize" The current available screen size has changed. This represents a change in the currently available size, relative to the current aspect ratio, so will change when the user switches between landscape and portrait. However, if your application targets API level 12 or lower, then your activity always handles this configuration change itself (this configuration change does not restart your activity, even when running on an Android 3.2 or higher device).

 

* "screenSize" 当前可用屏幕大小已经改变。它代表当前可用大小的改变，相对于当前切面比例，在用户从宽屏和竖屏之间切换的时候它将改变。然而，如果你的应用程序的目标为API级别12或更低，那么你的活动总是自己处理这个配置改变（这个配置改变不重启你的活动，甚至当运行在一个Android 3.2或更高的设备上时）。

 

Added in API level 13.

 

在API级别13中新增。

 

* "smallestScreenSize" The physical screen size has changed. This represents a change in size regardless of orientation, so will only change when the actual physical screen size has changed such as switching to an external display. A change to this configuration corresponds to a change in the smallestWidth configuration. However, if your application targets API level 12 or lower, then your activity always handles this configuration change itself (this configuration change does not restart your activity, even when running on an Android 3.2 or higher device).

 

* "smallestScreenSize" 物理屏幕大小已经改变。它代表大小的改变，不管方向是什么，仅在实际的物理屏幕大小改变时它才改变，诸如切换到一个外部显示器时。这个配置的改变对应于smallestWidth配置中的改变。然而，如果你的应用程序的目标为API级别12或更低，那么你的活动总是自己处理这个配置改变（这个配置改变不重启你的活动，甚至当运行在一个Android 3.2或更高的设备上时）。

 

Added in API level 13.

 

在API级别13中新增。

 

-------------------------------

 

All of these configuration changes can impact the resource values seen by the application. Therefore, when onConfigurationChanged() is called, it will generally be necessary to again retrieve all resources (including view layouts, drawables, and so on) to correctly handle the change.

 

所有这些配置改变可以影响应用程序看到的资源值。因此，当onConfigurationChanged()被调用时，通常有必要再次取出所有资源（包括视图布局，可绘画对象，等等）以正确地处理改变。

 

* android:enabled

 

Whether or not the activity can be instantiated by the system — "true" if it can be, and "false" if not. The default value is "true".

 

活动是否可以被系统实例化——"true"如果它可以，而"false"如果不可以。默认值为"true"。

 

The <application> element has its own enabled attribute that applies to all application components, including activities. The <application> and <activity> attributes must both be "true" (as they both are by default) for the system to be able to instantiate the activity. If either is "false", it cannot be instantiated.

 

<application>元素拥有它自己的enabled属性，它应用到所有应用程序组件，包括活动。<application>和<activity>的属性必须都是"true"（正如它们默认都是）以让系统可以实例化活动。如果其中之一为"false"，那么它不允许被实例化。

 

* android:excludeFromRecents

 

Whether or not the activity should be excluded from the list of recently launched activities that can be displayed to users — "true" if it should be excluded, and "false" if it should be included. The default value is "false".

 

活动是否应该从可以显示给用户的最近启动活动的列表中排除——"true"如果它应该被排除，而"false"如果它应该被包含。默认值为"false"。

 

* android:exported

 

Whether or not the activity can be launched by components of other applications — "true" if it can be, and "false" if not. If "false", the activity can be launched only by components of the same application or applications with the same user ID.

 

活动是否可以被其它应用程序的组件启动——"true"如果它可以，而"false"如果不可以。如果"false"，那么该活动仅可以被相同应用程序或带有相同用户ID的应用程序的组件启动。

 

The default value depends on whether the activity contains intent filters. The absence of any filters means that the activity can be invoked only by specifying its exact class name. This implies that the activity is intended only for application-internal use (since others would not know the class name). So in this case, the default value is "false". On the other hand, the presence of at least one filter implies that the activity is intended for external use, so the default value is "true".

 

默认值依赖于活动是否包含意图过滤器。没有任何过滤器意味着活动只可以通过指定它精确的类名来调用。这暗示着活动只倾向于应用程序内部使用（因为其它应用程序不知道类名）。所以在这种情况下，默认值为"false"。另一方面，存在至少一个过滤器暗示活动倾向于外部使用，所以默认值为"true"。

 

This attribute is not the only way to limit an activity's exposure to other applications. You can also use a permission to limit the external entities that can invoke the activity (see the permission attribute).

 

此属性不是限制活动对其它应用程序的暴露的唯一方式。你还可以使用权限来限制可以调用该活动的外部实体（见permission属性）。

 

* android:finishOnTaskLaunch

 

Whether or not an existing instance of the activity should be shut down (finished) whenever the user again launches its task (chooses the task on the home screen) — "true" if it should be shut down, and "false" if not. The default value is "false".

 

一个现存活动实体是否应该被关闭（完成），每当用户再次启动它的任务（在主屏幕上选择任务）——"true"如果它应该被关闭，而"false"如果不应该。默认值为"false"。

 

If this attribute and allowTaskReparenting are both "true", this attribute trumps the other. The affinity of the activity is ignored. The activity is not re-parented, but destroyed.

 

如果此属性和allowTaskReparenting都是"true"，那么这个属性优先于（注：待考）其它。活动的关系被忽略。活动不会被重新从属，而是被销毁。

 

* android:hardwareAccelerated

 

Whether or not hardware-accelerated rendering should be enabled for this Activity — "true" if it should be enabled, and "false" if not. The default value is "false".

 

硬件加速的渲染对于此Activity来说是否被使能——"true"如果它应该被使能，而"false"如果不是。默认值为"false"。

 

Starting from Android 3.0, a hardware-accelerated OpenGL renderer is available to applications, to improve performance for many common 2D graphics operations. When the hardware-accelerated renderer is enabled, most operations in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated. This results in smoother animations, smoother scrolling, and improved responsiveness overall, even for applications that do not explicitly make use the framework's OpenGL libraries.

 

从Android 3.0开始，一个硬件加速的OpenGL渲染器对于应用程序可用，以提高许多普通二维图形操作的性能。当硬件加速的渲染器被使能时，Canvas，Paint，Xfermode，ColorFilter，Shader，以及Camera的大多数操作被加速。这导致更平滑的动画，更平滑的滑动，以及整体提高的响应，甚至对于不是显式使用框架的OpenGL库的应用程序。

 

Note that not all of the OpenGL 2D operations are accelerated. If you enable the hardware-accelerated renderer, test your application to ensure that it can make use of the renderer without errors.

 

注意不是所有OpenGL二维操作被加速。如果你使能硬件加速渲染器，那么请测试你的应用程序以确保它可以没有错误地使用渲染器。

 

* android:icon

 

An icon representing the activity. The icon is displayed to users when a representation of the activity is required on-screen. For example, icons for activities that initiate tasks are displayed in the launcher window. The icon is often accompanied by a label (see the android:label attribute).

 

一个代表活动的图标。图标被显示给用户，当屏幕上需要代表活动的表现时。例如，初始化任务的活动的图标被显示在启动器窗口中。图标通常伴随有一个标签（见android:label属性）。

 

This attribute must be set as a reference to a drawable resource containing the image definition. If it is not set, the icon specified for the application as a whole is used instead (see the <application> element's icon attribute).

 

这个属性必须被设置为包含图片定义的可绘画对象资源的引用。如果它不被设置，那么改为使用整体地为应用程序指定的图标（见<application>元素的icon属性）。

 

The activity's icon — whether set here or by the <application> element — is also the default icon for all the activity's intent filters (see the <intent-filter> element's icon attribute).

 

活动的图标——在这里或者被<application>元素设置的——也是所有活动的意图过滤器的默认图标（见<intent-filter>元素的icon属性）。

 

* android:label

 

A user-readable label for the activity. The label is displayed on-screen when the activity must be represented to the user. It's often displayed along with the activity icon.

 

用于活动的用户可读的标签。标签被显示在屏幕上，当活动必须呈现给用户的时候。它经常伴随活动图标一起被显示。

 

If this attribute is not set, the label set for the application as a whole is used instead (see the <application> element's label attribute).

 

如果这个属性不被设置，那么改为使用整体地为应用程序设置的标签（见<application>元素的label属性）。

 

The activity's label — whether set here or by the <application> element — is also the default label for all the activity's intent filters (see the <intent-filter> element's label attribute).

 

活动的标签——在这里或被<application>元素设置的——也是所有活动的意图过滤器的默认标签（见<intent-filter>元素的label属性）。

 

The label should be set as a reference to a string resource, so that it can be localized like other strings in the user interface. However, as a convenience while you're developing the application, it can also be set as a raw string.

 

标签应该被设置作为一个字符串资源的引用，致使它可以像用户界面中的其它字符串被本地化。然而，方便起见，当你正在开发应用程序时，它也可以被设置为一个原始字符串。

 

* android:launchMode

 

An instruction on how the activity should be launched. There are four modes that work in conjunction with activity flags (FLAG_ACTIVITY_* constants) in Intent objects to determine what should happen when the activity is called upon to handle an intent. They are:

 

一个关于活动应该如何被启动的指令。有四种模式，在Intent对象中结合活动的标志（FLAG_ACTIVITY_*常量）来工作以决定当活动被调用以处理一个意图时，它应该做什么。它们是：

 

"standard" 

"singleTop" 

"singleTask" 

"singleInstance"

 

The default mode is "standard".

 

默认模式是"standard"。

 

As shown in the table below, the modes fall into two main groups, with "standard" and "singleTop" activities on one side, and "singleTask" and "singleInstance" activities on the other. An activity with the "standard" or "singleTop" launch mode can be instantiated multiple times. The instances can belong to any task and can be located anywhere in the activity stack. Typically, they're launched into the task that called startActivity() (unless the Intent object contains a FLAG_ACTIVITY_NEW_TASK instruction, in which case a different task is chosen — see the taskAffinity attribute).

 

正如下表中所示。模式分为两个主要分组，带"standard"和"singleTop"的活动在一边，而"singleTask"和"singleInstance"活动在另一边。一个带"standard"或"singleTop"启动模式的活动可以被实例化多次。实例可以属于任意任务，并且可以在活动堆栈中的任意地方被旋转。通常，它们被启动进入调用了startActivity()的任务（除非Intent对象包含一个FLAG_ACTIVITY_NEW_TASK指令，在那种情况下选择一个不同的任务——见taskAffinity属性）。

 

In contrast, "singleTask" and "singleInstance" activities can only begin a task. They are always at the root of the activity stack. Moreover, the device can hold only one instance of the activity at a time — only one such task.

 

相比而言，"singleTask"和"singleInstance"活动可以只开始一个任务。它们总是在活动堆栈的顶部。此外，设备可以在同一时刻只持有一个活动实例——只有一个这样的任务。

 

The "standard" and "singleTop" modes differ from each other in just one respect: Every time there's a new intent for a "standard" activity, a new instance of the class is created to respond to that intent. Each instance handles a single intent. Similarly, a new instance of a "singleTop" activity may also be created to handle a new intent. However, if the target task already has an existing instance of the activity at the top of its stack, that instance will receive the new intent (in an onNewIntent() call); a new instance is not created. In other circumstances — for example, if an existing instance of the "singleTop" activity is in the target task, but not at the top of the stack, or if it's at the top of a stack, but not in the target task — a new instance would be created and pushed on the stack.

 

"standard"和"singleTop"模式在只有一个方面不同于对方：每当有用于“标准”活动的一个新意图时，类的新实例被创建以响应那个意图。每个实例处理一个单一意图。类似地，"singleTop"活动的新实例还可以被创建以处理新的意图。然而，如果目标任务已经拥有活动的现存实例在它的堆栈的顶部，那么那个实例将接收新的意图（在一次onNewIntent()调用中）；一个新的实例将不被创建。在其它环境中——例如，如果"singleTop"活动的一个现存实例在目标任务中，但不是在堆栈的顶部，或者如果它在堆栈的顶部，但不是在目标任务中——那么一个新的实例将被创建并压入堆栈。

 

The "singleTask" and "singleInstance" modes also differ from each other in only one respect: A "singleTask" activity allows other activities to be part of its task. It's always at the root of its task, but other activities (necessarily "standard" and "singleTop" activities) can be launched into that task. A "singleInstance" activity, on the other hand, permits no other activities to be part of its task. It's the only activity in the task. If it starts another activity, that activity is assigned to a different task — as if FLAG_ACTIVITY_NEW_TASK was in the intent.

 

"singleTask"和"singleInstance"模式也只是在一个方面上不同于对方：一个"singleTask"活动允许其它活动成为它的任务的部分。它总是它的任务的根，但其它活动（必须是"standard"和"singleTop"活动）可以被启动进入那个任务。另一方面，一个"singleInstance"活动不允许其它活动成为它的任务的部分。任务中只有一个活动。如果它启动另一个活动，那么那个活动被赋予到一个不同的任务——好像FLAG_ACTIVITY_NEW_TASK是在意图中那样。

 

-------------------------------

 

* Use Cases Launch Mode Multiple Instances? Comments

 

* 用例 启动模式 是否多实例？ 注释

 

* Normal launches for most activities

 

* 用于大多数活动的正常启动模式

 

* "standard" Yes Default. The system always creates a new instance of the activity in the target task and routes the intent to it.

 

* "standard" 是 默认值。系统总是在目标任务中创建一个新的活动实例并且路由意图到它。

 

* "singleTop" Conditionally If an instance of the activity already exists at the top of the target task, the system routes the intent to that instance through a call to its onNewIntent() method, rather than creating a new instance of the activity.

 

* "singleTop" 有条件地 如果一个活动实例已经存在于目标任务的顶部，那么系统通过对它的onNewIntent()方法的调用，路由意图到那个实例，而非创建一个新的活动实例。

 

* Specialized launches

 

* 专门化启动

 

(not recommended for general use)

 

（对于普通用途不建议）

 

* "singleTask" No The system creates the activity at the root of a new task and routes the intent to it. However, if an instance of the activity already exists, the system routes the intent to existing instance through a call to its onNewIntent() method, rather than creating a new one.

 

* "singleTask" 否 系统在一个新的任务的根上创建活动并且路由意图到它。然而，如果一个活动实例已经存在，那么系统通过对它的onNewIntent()方法的调用来路由意图到现存实例，而非创建一个新的。

 

* "singleInstance" No Same as "singleTask", except that the system doesn't launch any other activities into the task holding the instance. The activity is always the single and only member of its task.

 

* "singleInstance" 否 同"singleTask"，不同的是系统不启动其它任意活动进入持有实例的任务。活动总是单一的并且是它的任务的唯一成员。

 

-------------------------------

 

As shown in the table above, standard is the default mode and is appropriate for most types of activities. SingleTop is also a common and useful launch mode for many types of activities. The other modes — singleTask and singleInstance — are not appropriate for most applications, since they result in an interaction model that is likely to be unfamiliar to users and is very different from most other applications.

 

正如上表所示，standard是默认模式并且对于大多数活动类型来说是何时的。SingleTop也是一个通用和有用的启动模式，对于许多活动类型来说。其它模式——singleTask和singleInstance——不适合大多数应用程序，因为它们导致一个交互模型，它很可能对于用户来说是不熟悉的并且和其它大多数应用程序非常不同。

 

Regardless of the launch mode that you choose, make sure to test the usability of the activity during launch and when navigating back to it from other activities and tasks using the BACK key.

 

不管你选择哪个启动模式，请确保测试活动的在启动期间以及当使用BACK键从其它活动和任务导航后退到它时的可用性。

 

For more information on launch modes and their interaction with Intent flags, see the Tasks and Back Stack document.

 

想获取关于启动模式和它们用Intent标志交互的更多信息，请参见任务和后退堆栈文档。

 

* android:multiprocess

 

Whether an instance of the activity can be launched into the process of the component that started it — "true" if it can be, and "false" if not. The default value is "false".

 

活动的一个实例是否可以被启动进入启动它的组件的进程中——"true"如果它可以，而"false"如果不能。默认值为"false"。

 

Normally, a new instance of an activity is launched into the process of the application that defined it, so all instances of the activity run in the same process. However, if this flag is set to "true", instances of the activity can run in multiple processes, allowing the system to create instances wherever they are used (provided permissions allow it), something that is almost never necessary or desirable.

 

正常情况下，一个活动的一个新的实例被启动进入定义它的应用程序的进程中，所以活动的所有实例运行在同一个进程中。然而，如果这个标志设置为"true"，那么活动的实例可以运行在多个进程中，允许系统创建实例，不管它们在哪里被使用（假设权限允许它），这是（注：待考）一些几乎从不需要或可取的事情。

 

* android:name

 

The name of the class that implements the activity, a subclass of Activity. The attribute value should be a fully qualified class name (such as, "com.example.project.ExtracurricularActivity"). However, as a shorthand, if the first character of the name is a period (for example, ".ExtracurricularActivity"), it is appended to the package name specified in the <manifest> element.

 

实现活动的类名。一个Activity子类。属性值应该是完全修饰类名（诸如，"com.example.project.ExtracurricularActivity"）。然而，作为简写，如果名称的第一个字符是一个点（例如，".ExtracurricularActivity"），那么它被尾加到在<manifest>元素中指定的包名后面。

 

Once you publish your application, you should not change this name (unless you've set android:exported="false").

 

一旦你发布你的应用程序，你不应该改变这个名称（除非你已经设置android:exported="false"）。

 

There is no default. The name must be specified.

 

没有默认值。名称必须被指定。

 

* android:noHistory

 

Whether or not the activity should be removed from the activity stack and finished (its finish() method called) when the user navigates away from it and it's no longer visible on screen — "true" if it should be finished, and "false" if not. The default value is "false".

 

活动是否应该从活动堆栈中被移除和完成（它的finish()方法被调用），当用户导航离开它以及它不再在屏幕上可见时——"true"如果它应该被完成，而"false"如果不应该。默认值为"false"。

 

A value of "true" means that the activity will not leave a historical trace. It will not remain in the activity stack for the task, so the user will not be able to return to it.

 

值为"true"意味着活动将不留下一个历史追溯。它将不保留在用于任务的活动堆栈，所以用户将不能返回到它。

 

This attribute was introduced in API Level 3.

 

此属性在API级别3中引入。

 

* android:permission

 

The name of a permission that clients must have to launch the activity or otherwise get it to respond to an intent. If a caller of startActivity() or startActivityForResult() has not been granted the specified permission, its intent will not be delivered to the activity.

 

权限的名称，客户端必须拥有该权限以启动活动，或者就是获取它来响应一个意图。如果startActivity()或startActivityForResult()的调用方不被授予指定的权限，那么它的意图将不被传递给活动。

 

If this attribute is not set, the permission set by the <application> element's permission attribute applies to the activity. If neither attribute is set, the activity is not protected by a permission.

 

如果这个属性不被设置，那么被<application>元素的permission属性设置的权限应用到该活动。如果两个属性都没有被设置，那么活动将不被权限保护。

 

For more information on permissions, see the Permissions section in the introduction and another document, Security and Permissions.

 

想获取关于权限的更多信息，请参见介绍中的权限章节以及另一篇文档，安全与权限。

 

* android:process

 

The name of the process in which the activity should run. Normally, all components of an application run in the default process created for the application. It has the same name as the application package. The <application> element's process attribute can set a different default for all components. But each component can override the default, allowing you to spread your application across multiple processes.

 

进程的名称，活动应该运行于该进程。通常情况下，应用程序的所有组件运行在为应用程序创建的默认进程中。它拥有与应用程序包相同的名称。<application>元素的process属性可以为所有组件设置一个不同的默认值。但每个组件可以覆盖默认值，允许你跨多个进程延伸你的应用程序。

 

If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is created when it's needed and the activity runs in that process. If the process name begins with a lowercase character, the activity will run in a global process of that name, provided that it has permission to do so. This allows components in different applications to share a process, reducing resource usage.

 

如果赋予这个属性的名称以冒号（':'）开头，那么一个新进程，对于应用程序来说是私有的，被创建，当需要它并且活动运行在那个进程时。如果进程名称以小写字母开头，那么活动将运行在那个名称的全局进程中，假如它有权限这样做。这允许不同应用程序中的组件共享一个进程，降低资源使用率。

 

* android:screenOrientation

 

The orientation of the activity's display on the device.

 

设备上活动的显示方向。

 

The value can be any one of the following strings:

 

该值可以是以下字符串中的任意一个：

 

-------------------------------

 

* "unspecified" The default value. The system chooses the orientation. The policy it uses, and therefore the choices made in specific contexts, may differ from device to device.

 

* "unspecified" 默认值。系统选择方向。它使用的策略，以及因此在指定上下文中作出的选择，可能因设备而不同。

 

* "user" The user's current preferred orientation.

 

* "user" 用户的当前喜好方向。

 

* "behind" The same orientation as the activity that's immediately beneath it in the activity stack.

 

* "behind" 和活动堆栈中正好在下方的活动相同的方向。

 

* "landscape" Landscape orientation (the display is wider than it is tall).

 

* "landscape" 宽屏方向（显示器比它高的时候宽）

 

* "portrait" Portrait orientation (the display is taller than it is wide).

 

* "portrait" 竖屏方向（显示器比它宽的时候高）

 

* "reverseLandscape" Landscape orientation in the opposite direction from normal landscape. Added in API level 9.

 

* "reverseLandscape" 正常宽屏的相反方向的宽屏方向。在API级别9中新增。

 

* "reversePortrait" Portrait orientation in the opposite direction from normal portrait. Added in API level 9.

 

* "reversePortrait" 正常竖屏的相反方向的竖屏方向。在API级别9中新增。

 

* "sensorLandscape" Landscape orientation, but can be either normal or reverse landscape based on the device sensor. Added in API level 9.

 

* "sensorLandscape" 宽屏方向，但可能是正常的或反宽屏，基于设备感应器。在API级别9中新增。

 

* "sensorPortrait" Portrait orientation, but can be either normal or reverse portrait based on the device sensor. Added in API level 9.

 

* "sensorPortrait" 竖屏方向，但可能是正常的或反竖屏，基于设备感应器。在API级别9中新增。

 

* "sensor" The orientation is determined by the device orientation sensor. The orientation of the display depends on how the user is holding the device; it changes when the user rotates the device. Some devices, though, will not rotate to all four possible orientations, by default. To allow all four orientations, use "fullSensor".

 

* "sensor" 通过设备方向感应器决定方向。显示器的方向依赖于用户正在如何拿着设备；当用户旋转设备时它改变。但是，默认下一些设备将不旋转到所有四个可能的方向。为了允许所有四个方向，请使用"fullSensor"。

 

* "fullSensor" The orientation is determined by the device orientation sensor for any of the 4 orientations. This is similar to "sensor" except this allows any of the 4 possible screen orientations, regardless of what the device will normally do (for example, some devices won't normally use reverse portrait or reverse landscape, but this enables those). Added in API level 9.

 

* "fullSensor" 通过用于四个方向中任意一个的设备方向感应器来决定方向，这类似于"sensor"，不同的是它允许四个可能的屏幕方向中的任意一个，不管设备正常情况下将做什么（例如，一些设备正常情况下将不会使用反竖屏或反宽屏，但它使能它们）。在API级别9中新增。

 

* "nosensor" The orientation is determined without reference to a physical orientation sensor. The sensor is ignored, so the display will not rotate based on how the user moves the device. Except for this distinction, the system chooses the orientation using the same policy as for the "unspecified" setting.

 

* "nosensor" 决定方向，不参考一个物理方向感应器。感应器被忽略，所以显示器将不会基于用户如何移动设备而旋转。除了这个区别外，系统使用和"unspecified"设置相同的策略来选择方向。

 

-------------------------------

 

-------------------------------

 

Note: When you declare one of the landscape or portrait values, it is considered a hard requirement for the orientation in which the activity runs. As such, the value you declare enables filtering by services such as Android Market so your application is available only to devices that support the orientation required by your activities. For example, if you declare either "landscape", "reverseLandscape", or "sensorLandscape", then your application will be available only to devices that support landscape orientation. However, you should also explicitly declare that your application requires either portrait or landscape orientation with the <uses-feature> element. For example, <uses-feature android:name="android.hardware.screen.portrait"/>. This is purely a filtering behavior provided by Android Market (and other services that support it) and the platform itself does not control whether your app can be installed when a device supports only certain orientations.

 

注意：当你声明landscape或portrait值之一时，它被认为是对于活动运行方向的硬性需求。因此，你声明的值使能服务的过滤诸如Android市场，使你的应用程序的可用仅对于支持你的活动必需的方向。例如，如果你声明"landscape"，"reverseLandscape"，或"sensorLandscape"，那么你的应用程序的可用将仅对于支持宽屏方向的设备。然而，你还应该用<uses-feature>显式地声明你的应用程序需要竖屏或宽屏方向。例如，<uses-feature android:name="android.hardware.screen.portrait"/>。这纯粹是由Android市场提供的一种过滤行为（以及其它支持它的服务）而平台自身不控制你的应用是否可以被安装，当设备仅支持某个方向时。

 

-------------------------------

 

* android:stateNotNeeded

 

Whether or not the activity can be killed and successfully restarted without having saved its state — "true" if it can be restarted without reference to its previous state, and "false" if its previous state is required. The default value is "false".

 

活动是否可以被杀死和成功地重启而不保存它的状态——"true"如果它可以被重启而不引用它的前一个状态，而"false"如果它的前一个状态是必需的。默认值为"false"。

 

Normally, before an activity is temporarily shut down to save resources, its onSaveInstanceState() method is called. This method stores the current state of the activity in a Bundle object, which is then passed to onCreate() when the activity is restarted. If this attribute is set to "true", onSaveInstanceState() may not be called and onCreate() will be passed null instead of the Bundle — just as it was when the activity started for the first time.

 

通常，在一个活动被暂时关闭以保存资源前，它的onSaveInstanceState()被调用。这个方法保存活动的当前状态在一个Bundle对象中，然后当活动被重启时它被传递给onCreate()。如果这个属性被设置为"true"，那么onSaveInstanceState()可能不被调用而onCreate()将被传递null而非Bundle对象——正如活动第一次启动时那样。

 

A "true" setting ensures that the activity can be restarted in the absence of retained state. For example, the activity that displays the home screen uses this setting to make sure that it does not get removed if it crashes for some reason.

 

一个"true"设置确保活动可以在缺少保持的状态时被重启。例如，显示主屏幕的活动使用这个设置以确保它不会被删除，如果它因为某些原因崩溃了。

 

* android:taskAffinity

 

The task that the activity has an affinity for. Activities with the same affinity conceptually belong to the same task (to the same "application" from the user's perspective). The affinity of a task is determined by the affinity of its root activity.

 

活动拥有关系的任务。带有相同关系的活动概念上属于同一个任务（属于从用户视角看是相同的“应用程序”）。任务的关系由它的根活动的关系决定。

 

The affinity determines two things — the task that the activity is re-parented to (see the allowTaskReparenting attribute) and the task that will house the activity when it is launched with the FLAG_ACTIVITY_NEW_TASK flag.

 

关系决定两件事——活动被重新从属的任务（见allowTaskReparenting属性）以及当活动是用FLAG_ACTIVITY_NEW_TASK标志来启动时将持有该活动的任务。

 

By default, all activities in an application have the same affinity. You can set this attribute to group them differently, and even place activities defined in different applications within the same task. To specify that the activity does not have an affinity for any task, set it to an empty string.

 

默认，一个应用程序的所有活动拥有相同的关系。你可以设置这个属性以不同地分组它们，设置把定义在不同应用程序中的活动放置在同一个任务中。要想指定活动没有任何任务的关系，请设置它为一个空字符串。

 

If this attribute is not set, the activity inherits the affinity set for the application (see the <application> element's taskAffinity attribute). The name of the default affinity for an application is the package name set by the <manifest> element.

 

如果这个属性不被设置，活动继承为应用程序设置的关系（见<application>元素的taskAffinity属性）。一个应用程序的默认关系的名称是<manifest>元素设置的包名）。

 

* android:theme

 

A reference to a style resource defining an overall theme for the activity. This automatically sets the activity's context to use this theme (see setTheme(), and may also cause "starting" animations prior to the activity being launched (to better match what the activity actually looks like).

 

指向为活动定义整个样式的样式资源的引用。它自动地设置活动的上下文以使用这个主题（见setTheme()）（注：这里可能少了右括号），以及在活动被启动前还可能导致“正在启动”动画（以更好地匹配活动实际看起来像的样子）。

 

If this attribute is not set, the activity inherits the theme set for the application as a whole — from the <application> element's theme attribute. If that attribute is also not set, the default system theme is used. For more information, see the Styles and Themes developer guide.

 

如果此属性不被设置，那么活动继承应用程序整体地设置的主题——来自<application>元素的theme属性。如果那个属性也没有被设置，那么使用默认的系统主题。想获取更多信息，请参见样式和主题开发者指引。

 

* android:uiOptions

 

Extra options for an activity's UI.

 

用于活动的用户界面的额外选项。

 

Must be one of the following values.

 

必须是以下值之一。

 

-------------------------------

 

* Value Description

 

* 值 描述

 

* "none" No extra UI options. This is the default.

 

* "none" 没有额外用户界面选项。它是默认的。

 

* "splitActionBarWhenNarrow" Add a bar at the bottom of the screen to display action items in the ActionBar, when constrained for horizontal space (such as when in portrait mode on a handset). Instead of a small number of action items appearing in the action bar at the top of the screen, the action bar is split into the top navigation section and the bottom bar for action items. This ensures a reasonable amount of space is made available not only for the action items, but also for navigation and title elements at the top. Menu items are not split across the two bars; they always appear together.

 

* "splitActionBarWhenNarrow" 在屏幕底部添加一个栏以显示ActionBar中的动作条目，当它们因为水平空间而被约束（诸如当处于手机上的竖屏模式时）。不是在屏幕的顶部的动作栏中显示小数量的动作条目，而是为了动作条目而把动作栏分隔成顶部导航部分和底栏。这确保让合理数量的空间可用，不仅仅对于动作条目，还对于顶部的导航和标题元素。菜单条目不会跨越两个栏而分割；它们总是出现在一起。

 

-------------------------------

 

For more information about the action bar, see the Action Bar developer guide.

 

关于动作栏的更多信息，参见动作栏开发者指引。

 

This attribute was added in API level 14.

 

此属性在API级别14中新增。

 

* android:windowSoftInputMode

 

How the main window of the activity interacts with the window containing the on-screen soft keyboard. The setting for this attribute affects two things:

 

活动的主窗口如何与包含屏幕上软键盘的窗口交互。这个属性的设置影响两个东西：

 

* The state of the soft keyboard — whether it is hidden or visible — when the activity becomes the focus of user attention.

 

* 软键盘的状态——它是隐藏还是可见——当活动变得拥有用户注意的焦点时。

 

* The adjustment made to the activity's main window — whether it is resized smaller to make room for the soft keyboard or whether its contents pan to make the current focus visible when part of the window is covered by the soft keyboard.

 

* 对于活动主窗口的调整模式——它是否被变得更小以制造空间给软键盘，或它的内容是否调整（注：待考）以让当前焦点可见，当窗口的部分被软键盘覆盖时。

 

The setting must be one of the values listed in the following table, or a combination of one "state..." value plus one "adjust..." value. Setting multiple values in either group — multiple "state..." values, for example — has undefined results. Individual values are separated by a vertical bar (|). For example:

 

设置必须是以下表格中列举的值之一，或者是一个"state..."值加上一个"adjust..."值的组合。设置其中一个组中的多个值——例如多个"state..."值——有未定义的结果。单独的值被一个竖线（|）分隔。例如：

 

-------------------------------

 

<activity android:windowSoftInputMode="stateVisible|adjustResize" . . . >

 

-------------------------------

 

Values set here (other than "stateUnspecified" and "adjustUnspecified") override values set in the theme.

 

在这里设置的值（不是"stateUnspecified"和"adjustUnspecified"）覆盖主题中设置的值。

 

-------------------------------

 

* Value Description

 

* 值 描述

 

* "stateUnspecified" The state of the soft keyboard (whether it is hidden or visible) is not specified. The system will choose an appropriate state or rely on the setting in the theme.

 

* "stateUnspecified" 软键盘的状态（它是隐藏或可见的）不被指定。系统将选择一个合适的状态或依赖于主题中的设置。

 

This is the default setting for the behavior of the soft keyboard.

 

这是用于软键盘的行为的默认设置。

 

* "stateUnchanged" The soft keyboard is kept in whatever state it was last in, whether visible or hidden, when the activity comes to the fore.

 

* "stateUnchanged" 软键盘被保持，不管它上次处于什么状态，是可见还是隐藏，当活动来到前面时。

 

* "stateHidden" The soft keyboard is hidden when the user chooses the activity — that is, when the user affirmatively navigates forward to the activity, rather than backs into it because of leaving another activity.

 

* "stateHidden" 软键盘被隐藏，当用户选择活动时——即当用户肯定地向后导航到该活动时，而非因为离开另一个活动而后退进入它。

 

* "stateAlwaysHidden" The soft keyboard is always hidden when the activity's main window has input focus.

 

* "stateAlwaysHidden" 软键盘总是被隐藏，当活动的主窗口拥有输入焦点。

 

* "stateVisible" The soft keyboard is visible when that's normally appropriate (when the user is navigating forward to the activity's main window).

 

* "stateVisible" 软键盘是可见的，当正常情况下那是合适的（当用户正在导航后退到活动的主窗口时）。

 

* "stateAlwaysVisible" The soft keyboard is made visible when the user chooses the activity — that is, when the user affirmatively navigates forward to the activity, rather than backs into it because of leaving another activity.

 

* "stateAlwaysVisible" 让软键盘可见，当用户选择活动时——即当用户肯定地导航后退到活动，而非因为离开另一个活动而后退进入它。

 

* "adjustUnspecified" It is unspecified whether the activity's main window resizes to make room for the soft keyboard, or whether the contents of the window pan to make the currentfocus visible on-screen. The system will automatically select one of these modes depending on whether the content of the window has any layout views that can scroll their contents. If there is such a view, the window will be resized, on the assumption that scrolling can make all of the window's contents visible within a smaller area.

 

* "adjustUnspecified" 活动的主窗口是否改变大小以制造空间给软键盘，或者窗口的内容是否调整（注：待考）以让屏幕上当前焦点（注：此处貌似笔误，应该是current focus）可见，是未指定的。系统将自动地选择这些模式之一，依赖于该窗口的内容是否拥有任意布局视图，它们可以滚动它们的内容。如果有这样一个视图，那么窗口将被改变大小，假设滚动可以致使窗口的所有内容在一个较小区域内可见。

 

This is the default setting for the behavior of the main window.

 

这是对于主窗口行为的默认设置。

 

* "adjustResize" The activity's main window is always resized to make room for the soft keyboard on screen.

 

* "adjustResize" 活动的主窗口总是被调整大小以制造空间给屏幕上的软键盘。

 

* "adjustPan" The activity's main window is not resized to make room for the soft keyboard. Rather, the contents of the window are automatically panned so that the current focus is never obscured by the keyboard and users can always see what they are typing. This is generally less desirable than resizing, because the user may need to close the soft keyboard to get at and interact with obscured parts of the window.

 

* "adjustPan" 活动的主窗口不会被改变大小而为软键盘制造空间。相反，窗口的内容被自动调整（注：待考，这里pan的意思应该是指电影的镜头）以使当前焦点从不被键盘隐藏，而用户可以总是看到他们正在键入的东西。比起改变大小，这通常较不理想，因为用户可能需要关闭软键盘以到达和与被挡住的窗口部分交互。

 

-------------------------------

 

This attribute was introduced in API Level 3.

 

此属性在API级别3中引入。

 

* introduced in:

 

* 引入：

 

API Level 1 for all attributes except for noHistory and windowSoftInputMode, which were added in API Level 3.

 

API级别1，对于所有属性除了noHistory和windowSoftInputMode，它们在API级别3中被添加。

 

* see also:

 

* 另见：

 

<application> 

<activity-alias>

 

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/

）