【Android深入解析】Manifest配置檔案解析（上）（英文版）
<action>
語法規則:
<action android:name="string"/>
描述 :
Adds an action to an intentfilter. An elementmust
contain one or more <action>elements. If itdoesn't contain any, no Intent objects will get through the filter. See Intents
and Intent Filtersfordetails on intent filters and the role of action specifications within a filter.
屬性:
android:name
The name of theaction. Some standard actions are defined in the class asACTION_string constants.To assign one of these actions to this attribute, prepend "android.intent.action." to the string thatfollows ACTION_. For example, for ACTION_MAIN, use "android.intent.action.MAIN" and for ACTION_WEB_SEARCH
For actions youdefine, it's best to use the package name as a prefix to ensure uniqueness. Forexample, a TRANSMOGRIFY actionmight be specified as follows:
<action android:name="com.example.project.TRANSMOGRIFY"/>
INTRODUCED IN:
API Level 1
SEE ALSO:
<activity>
- SYNTAX:
-
<activityandroid:allowEmbedded=["true" | "false"] android:allowTaskReparenting=["true" | "false"] android:alwaysRetainTaskState=["true" | "false"] android:autoRemoveFromRecents=["true" | "false"] android:banner="drawable resource"android:clearTaskOnLaunch=["true" | "false"] android:configChanges=["mcc", "mnc", "locale", "touchscreen", "keyboard", "keyboardHidden", "navigation", "screenLayout", "fontScale", "uiMode", "orientation", "screenSize", "smallestScreenSize"] android:documentLaunchMode=["intoExisting" | "always" | "none" | "never"] 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:maxRecents="integer"android:multiprocess=["true" | "false"] android:name="string"android:noHistory=["true" | "false"] android:parentActivityName="string"android:permission="string"android:process="string"android:relinquishTaskIdentity=["true" | "false"] android:screenOrientation=["unspecified" | "behind" | "landscape" | "portrait" | "reverseLandscape" | "reversePortrait" | "sensorLandscape" | "sensorPortrait" | "userLandscape" | "userPortrait" | "sensor" | "fullSensor" | "nosensor" | "user" | "fullUser" | "locked"] 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>
DESCRIPTION: Declares an activity (an 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.
ATTRIBUTES:
android:allowEmbedded
Indicate that the activity can be launched as the embedded child of another activity. Particularly in the case where the child lives in a container such as a Display owned by another activity. For example, activities that are used for Wear custom notifications
must declare this so Wear can display the activity in it's context stream, which resides in another process.
The default value of this attribute is false.
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.
If this attribute is not set, the value set by the corresponding attribute
of the element applies to the activity. The default
value is "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 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 attribute.)
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.
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.
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.
android:autoRemoveFromRecents
Whether or not tasks launched by activities with this attribute remains in the overview screen until
the last activity in the task is completed. If true, the task is automatically removed from the overview screen. This overrides the caller's use of .
It must be a boolean value, either "true" or "false".
android:banner
A drawable resource providing an extended graphical banner for its associated item. Use
with the<activity> tag to supply a default banner for a specific activity, or with the <application> tag
to supply a banner for all application activities.
The system uses the banner to represent an app in the Android TV home screen. Since the banner is displayed only in the home screen, it should only be specified by applications with an activity that handles the intent.
This attribute must be set as a reference to a drawable resource containing the image (for example"@drawable/banner"). There is no default banner.
See Banners in the UI Patterns for TV design guide, and Provide a home screen banner in Get Started with TV Apps for more information.
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.
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
the Back orHome button to leave it. When the value is "false", the task may be cleared of activities in some situations (see the attribute),
but not always.
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 Homeand the task went to the background.
So the user sees only P when returning to the task.
If this attribute and 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.
android:configChangesLists 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 method
is called.
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".
| Value | Description |
|---|---|
"mcc" |
The IMSI mobile country code (MCC) has changed — a SIM has been detected and updated the MCC. |
"mnc" |
The IMSI mobile network code (MNC) has changed — a SIM has been detected and updated the MNC. |
"locale" |
The locale has changed — the user has selected a new language that text should be displayed in. |
"touchscreen" |
The touchscreen has changed. (This should never normally happen.) |
"keyboard" |
The keyboard type has changed — for example, the user has plugged in an external keyboard. |
"keyboardHidden" |
The keyboard accessibility has changed — for example, the user has revealed the hardware keyboard. |
"navigation" |
The navigation type (trackball/dpad) has changed. (This should never normally happen.) |
"screenLayout" |
The screen layout has changed — this might be caused by a different display being activated. |
"fontScale" |
The font scaling factor has changed — the user has selected a new global font size. |
"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 night mode changes. See . Added in API level 8. |
"orientation" |
The screen orientation has changed — the user has rotated the device.
Note: If your application targets API level 13 or higher (as declared by the |
"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).
Added in API level 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).
Added in API level 13. |
"layoutDirection" |
The layout direction has changed. For example, changing from left-to-right (LTR) to right-to-left (RTL). Added in API level 17. |
All of these configuration changes can impact the resource values seen by the application. Therefore, when is called, it will generally be necessary to again retrieve all resources (including view layouts, drawables, and so on) to correctly handle the change.
android:documentLaunchMode
Specifies how a new instance of an activity should be added to a task each time it is launched. This attribute permits the user to have multiple documents from the same application appear in theoverview
screen.
This attribute has four values which produce the following effects when the user opens a document with the application:
| Value | Description |
|---|---|
"intoExisting" |
The activity reuses the existing task for the document. Using this value is the same as setting the flag, withoutsetting the flag, as described in Using the Intent flag to add a task . |
"always" |
The activity creates a new task for the document, even if the document is already opened. This is the same as setting both the and flags. |
"none" |
The activity does not create a new task for the activity. This is the default value, which creates a new task only when is set. The overview screen treats the activity as it would by default: it displays a single task for the app, which resumes from whatever activity the user last invoked. |
"never" |
This activity is not launched into a new document even if the Intent contains . Setting this overrides the behavior of the and flags, if either of these are set in the activity, and the overview screen displays a single task for the app, which resumes from whatever activity the user last invoked. |
Note: For values other than "none" and "never" the activity must be defined withlaunchMode="standard". If this attribute is not specified, documentLaunchMode="none" is
used.
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".
The element
has its own attribute that applies to all application
components, including activities. The 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.
android:excludeFromRecents
Whether or not the task initiated by this activity should be excluded from the list of recently used applications, the overview
screen. That is, when this activity is the root activity of a new task, this attribute determines whether the task should not appear in the list of recent apps. Set "true" if the task should be excluded from the list; set
"false" if it should be included. The default value is "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.
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".
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 attribute).
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".
If this attribute and are
both "true", this attribute trumps the other. The affinity of the activity is ignored. The activity is not re-parented, but destroyed.
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".
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. Because of the increased resources required to enable hardware acceleration, your app will consume more RAM.
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.
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).
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 element's icon attribute).
The activity's icon — whether set here or by the element
— is also the default icon for all the activity's intent filters (see the element's icon attribute).
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 element's label attribute).
The activity's label — whether set here or by the element
— is also the default label for all the activity's intent filters (see the element's label attribute).
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 objects
to determine what should happen when the activity is called upon to handle an intent. They are:
"standard"
"singleTop"
"singleTask"
"singleInstance"
The default mode is "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 (unless
the Intent object contains a instruction,
in which case a different task is chosen — see the taskAffinity attribute).
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.
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 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.
Similarly, if you navigate up to an
activity on the current stack, the behavior is determined by the parent activity's launch mode. If the parent activity has launch mode singleTop (or the up intent contains ),
the parent is brought to the top of the stack, and its state is preserved. The navigation intent is received by the parent activity's method.
If the parent activity has launch mode standard (and the up intent does not contain),
the current activity and its parent are both popped off the stack, and a new instance of the parent activity is created to receive the navigation intent.
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.
| 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. |
"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 method, rather than creating a new instance of the activity. | |
|
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 method, rather than creating a new one. |
"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. |
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.
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 button.
For more information on launch modes and their interaction with Intent flags, see the Tasks and Back Stack document.
android:maxRecents
The maximum number of tasks rooted at this activity in the overview screen. When this number of entries
is reached, the system removes the least-recently used instance from the overview screen. Valid values are 1 through 50 (25 on low memory devices); zero is invalid. This must be an integer value, such as 50. The default value is 16.
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".
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.
android:name
The name of the class that implements the activity, a subclass of .
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 element.
Once you publish your application, you should not change this name (unless you've set).
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 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".
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. In this case, is
never called if you start another activity for a result from this activity.
This attribute was introduced in API Level 3.
android:parentActivityName
The class name of the logical parent of the activity. The name here must match the class name given to the corresponding <activity> element's android:name attribute.
The system reads this attribute to determine which activity should be started when the user presses the Up button in the action bar. The system can also use this information to synthesize a back stack of activities with .
To support API levels 4 - 16, you can also declare the parent activity with a <meta-data> element that specifies a value for "android.support.PARENT_ACTIVITY". For example:
<activityandroid:name="com.example.app.ChildActivity"android:label="@string/title_child_activity"android:parentActivityName="com.example.myfirstapp.MainActivity"><!-- Parent activity meta-data to support API level 4+ --><meta-dataandroid:name="android.support.PARENT_ACTIVITY"android:value="com.example.app.MainActivity"/>