<活动>

语法:
<activity android:allowEmbedded=["true" | "false"]
          android:allowTaskReparenting=["true" | "false"]
          android:alwaysRetainTaskState=["true" | "false"]
          android:autoRemoveFromRecents=["true" | "false"]
          android:banner="drawable resource"
          android:clearTaskOnLaunch=["true" | "false"]
          android:colorMode=[ "hdr" | "wideColorGamut"]
          android:configChanges=["mcc", "mnc", "locale",
                                 "touchscreen", "keyboard", "keyboardHidden",
                                 "navigation", "screenLayout", "fontScale",
                                 "uiMode", "orientation", "density",
                                 "screenSize", "smallestScreenSize"]
          android:directBootAware=["true" | "false"]
          android:documentLaunchMode=["intoExisting" | "always" |
                                  "none" | "never"]
          android:enabled=["true" | "false"]
          android:enabledOnBackInvokedCallback=["true" | "false"]
          android:excludeFromRecents=["true" | "false"]
          android:exported=["true" | "false"]
          android:finishOnTaskLaunch=["true" | "false"]
          android:hardwareAccelerated=["true" | "false"]
          android:icon="drawable resource"
          android:immersive=["true" | "false"]
          android:label="string resource"
          android:launchMode=["standard" | "singleTop" |
                              "singleTask" | "singleInstance" | "singleInstancePerTask"]
          android:lockTaskMode=["normal" | "never" |
                              "if_whitelisted" | "always"]
          android:maxRecents="integer"
          android:maxAspectRatio="float"
          android:multiprocess=["true" | "false"]
          android:name="string"
          android:noHistory=["true" | "false"]  
          android:parentActivityName="string" 
          android:persistableMode=["persistRootOnly" | 
                                   "persistAcrossReboots" | "persistNever"]
          android:permission="string"
          android:process="string"
          android:relinquishTaskIdentity=["true" | "false"]
          android:resizeableActivity=["true" | "false"]
          android:screenOrientation=["unspecified" | "behind" |
                                     "landscape" | "portrait" |
                                     "reverseLandscape" | "reversePortrait" |
                                     "sensorLandscape" | "sensorPortrait" |
                                     "userLandscape" | "userPortrait" |
                                     "sensor" | "fullSensor" | "nosensor" |
                                     "user" | "fullUser" | "locked"]
          android:showForAllUsers=["true" | "false"]
          android:stateNotNeeded=["true" | "false"]
          android:supportsPictureInPicture=["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>
包含于:
<application>
可包含:
<intent-filter>
<meta-data>
<layout>
说明:
声明实现应用部分可视化界面的 Activity(一个 Activity 子类)。所有 activity 都必须在清单文件中用 <activity> 元素表示。系统不会识别任何未通过上述方式声明的 activity。
属性:
android:allowEmbedded
表示该 activity 可作为其他 activity 的嵌入式子项启动,尤其是在子项位于容器中时,例如归另一 activity 所有的 Display。例如,用于 Wear 自定义通知的 activity 必须声明此属性,以便 Wear 在其位于另一进程内的上下文流中显示 activity。

此属性的默认值为 false

android:allowTaskReparenting
当下一次将启动 activity 的任务转至前台时,activity 是否能从该任务转移至与其有相似性的任务。"true" 表示可以转移,"false" 表示仍须留在启动它的任务处。

如果未设置该属性,则对 activity 应用由 <application> 元素的相应 allowTaskReparenting 属性所设置的值。默认值为 "false"

正常情况下,activity 启动时会与启动它的任务关联,并在其整个生命周期中一直留在该任务处。当不再显示现有任务时,您可以使用该属性强制 activity 将其父项更改为与其有相似性的任务。该属性通常用于将应用的 activity 转移至与该应用关联的主任务。

例如,如果电子邮件消息包含网页链接,则点击该链接会调出可显示该网页的 activity。该 activity 由浏览器应用定义,但作为电子邮件任务的一部分启动。如果将该 activity 的父项更改为浏览器任务,则它会在浏览器下一次转至前台时显示,在电子邮件任务再次转至前台时消失。

activity 的相似性由 taskAffinity 属性定义。通过读取任务根 activity 的相似性即可确定任务的相似性。因此,按照定义,根 activity 始终位于具有同一相似性的任务中。由于具有 "singleTask""singleInstance" 启动模式的 activity 只能位于任务的根上,因此更改父项仅限于 "standard""singleTop" 模式。(另请参阅 launchMode 属性。)

android:alwaysRetainTaskState
系统是否始终保持 activity 所在任务的状态。"true" 表示是,"false" 表示允许系统在特定情况下将任务重置到其初始状态。默认值为 "false"。该属性只对任务的根 activity 有意义。所有其他 activity 均忽略该属性。

正常情况下,当用户从主屏幕重新选择某个任务时,系统会在特定情况下清除该任务,从根 activity 上的堆栈中移除所有 activity。通常,如果用户在一段时间(如 30 分钟)内未访问任务,系统会执行此操作。

不过,如果该属性的值是 "true",则无论用户如何返回任务,该任务始终会显示最后一次的状态。该属性非常适用于网络浏览器这类应用,因为其中存在大量用户不愿丢失的状态,如多个打开的标签页。

android:autoRemoveFromRecents
由具有该属性的 activity 启动的任务是否保留在“最近使用的应用”屏幕中,直到任务中的最后一个 activity 完成为止。若为 true,则自动从“最近使用的应用”屏幕中移除任务。它会替换调用方使用的 FLAG_ACTIVITY_RETAIN_IN_RECENTS。它必须是布尔值 "true""false"
android:banner
一种可绘制资源,可为其关联项提供扩展图形横幅。可与 <activity> 标记联用,为特定 activity 提供默认横幅;也可与 <application> 标记联用,为所有应用 activity 提供横幅。

系统在 Android TV 主屏幕中使用横幅来代表应用。由于横幅只显示在主屏幕中,因此它只能由具有可处理 CATEGORY_LEANBACK_LAUNCHER intent 的 activity 的应用指定。

此属性应设为对包含图片的可绘制资源(例如 "@drawable/banner")的引用。没有默认横幅。

如需了解详情,请参阅“TV 应用入门”中的提供主屏幕横幅

android:clearTaskOnLaunch
是否每当从主屏幕重新启动任务时都从中移除根 activity 之外的所有 activity。"true" 表示始终将任务清除到只剩其根 activity;"false" 表示不做清除。默认值为 "false"。该属性只对启动新任务的 activity(根 activity)有意义。任务中的所有其他 activity 均可忽略该属性。

若值为“"true"”,则每次当用户再次启动任务时,无论用户最后在任务中正在执行哪个 activity,也无论用户是使用“返回”还是“主屏幕”按钮离开,系统都会将用户转至任务的根 activity。当值为 "false" 时,可在某些情况下清除任务中的 activity,但也有例外。如需了解详情,请参考 alwaysRetainTaskState 属性。

假设用户从主屏幕启动 activity P,然后从该处转到 activity Q。接着,该用户点按“主屏幕”,然后返回到 activity P。正常情况下,用户将看到 activity Q,因为这是其最后在 P 的任务中所执行的 activity。不过,如果 P 将此标志设置为 "true",当用户从主屏幕启动 activity P 时,系统会移除 P 上方的所有 activity(在本例中为 Q)。因此用户在返回任务时只会看到 P。

如果该属性和 allowTaskReparenting 的值均为 "true",则如上所述,任何可更改父项的 activity 都将转移至与其有相似性的任务。其余 activity 随即会被移除。

如果未设置 FLAG_ACTIVITY_RESET_TASK_IF_NEEDED,系统将忽略此属性。

android:colorMode

指定 activity 的颜色模式。如果指定,则可以是 hdrwideColorGamut

如果为 hdr,则请求以高动态范围显示 activity(如果设备支持)。

如果为 wideColorGamut,则请求在兼容设备上以广色域模式显示 activity。在广色域模式下,窗口可以在 SRGB 色域之外进行渲染,从而显示更鲜艳的色彩。如果设备不支持广色域渲染,则此属性无效。如需了解在广色域模式下进行渲染的详细信息,请参阅使用广色域内容增强图形

android:configChanges
列出 activity 将自行处理的配置变更。在运行时发生配置变更时,默认情况下会关闭 activity 并将其重启,但使用该属性声明配置将阻止 activity 重启。相反,activity 会保持运行状态,并且系统会调用其 onConfigurationChanged() 方法。

注意:请仅在特殊情况下使用此属性,以提高应用性能和响应速度。如需了解详情,请参阅处理配置更改

下列字符串是该属性的有效值。若有多个值,则使用 | 进行分隔,例如 "locale|navigation|orientation"

说明
"density" 显示密度的更改,例如当用户指定不同的显示比例或其他屏幕当前处于活跃状态时。

在 API 级别 24 中引入。

"fontScale" 字体缩放比例的更改,例如当用户选择新的全局字体大小时。
"keyboard" 键盘类型的更改,例如当用户插入外接键盘时。
"keyboardHidden" 键盘无障碍功能的更改,例如当用户显示硬件键盘时。
"layoutDirection" 布局方向的更改,例如从由左到右 (LTR) 改为由右到左 (RTL)。

在 API 级别 17 中引入。

"locale" 语言区域的更改,例如当用户选择显示文本所用的新语言时。
"mcc" 当系统检测到用于更新 MCC 的 SIM 卡时,IMSI 移动设备国家/地区代码 (MCC) 发生的更改。
"mnc" 当系统检测到用于更新 MNC 的 SIM 卡时,IMSI 移动网络代码 (MNC) 发生的更改。
"navigation" 导航类型(轨迹球或方向键)的 TA 更改。通常不会出现这种情况。
"orientation"

屏幕方向的更改,例如用户旋转设备时。

注意:如果应用面向 Android 3.2(API 级别 13)或更高版本的系统,则还应声明 "screenLayout""screenSize" 配置,因为当设备在纵向模式与横向模式之间切换时,屏幕布局和屏幕大小可能会发生变化。

"screenLayout" 屏幕布局的更改,例如在其他屏幕变为活动状态时。
"screenSize" 当前可用屏幕尺寸的更改。

该值表示目前可用尺寸相对于当前宽高比的变更,当用户在横向模式与纵向模式之间切换时,它便会发生变更。

在 API 级别 13 中引入。

"smallestScreenSize" 实体屏幕尺寸的更改。

该值表示与方向无关的尺寸变更,因此它只有在实际物理屏幕尺寸发生变更(如切换到外部显示器)时才会变化。对此配置所作变更对应 smallestWidth 配置的更改。

在 API 级别 13 中引入。

"touchscreen" 触摸屏的更改。通常不会出现这种情况。
"uiMode" 界面模式的更改,例如当用户将设备放到桌面或车载基座上时,或者夜间模式发生变化时。如需了解有关不同界面模式的更多信息,请参阅 UiModeManager

在 API 级别 8 中引入。

所有这些配置变更都可能影响应用所看到的资源值。因此,调用 onConfigurationChanged() 时,通常必须再次检索所有资源(包括视图布局和可绘制对象),才能正确处理更改。

注意:如要处理所有多窗口模式相关的配置变更,请使用 "screenLayout""smallestScreenSize"。Android 7.0(API 级别 24)或更高版本的系统支持多窗口模式。

android:directBootAware

activity 是否可感知直接启动 - 也就是说,它是否可以在用户解锁设备之前运行。

注意:在直接启动期间,应用中的 activity 仅可访问存储在设备保护存储区的数据。

默认值为 "false"

android:documentLaunchMode
指定每次启动任务时,如何向其添加新的 activity 实例。该属性允许用户让多个来自同一应用的文档出现在“最近使用的应用”屏幕中。

该属性具有四个值,在用户使用应用打开文档时分别会产生以下效果:

说明
"intoExisting" 系统会搜索基本 intent 的 ComponentName 和数据 URI 与启动 intent 的这些内容相匹配的任务。如果发现此类任务,系统会将其清除,并在根 activity 收到对 onNewIntent(android.content.Intent) 的调用时自行重启。如果未发现此类任务,系统会创建新任务。
"always" activity 为文档创建新任务,即便文档已经打开。这与同时设置 FLAG_ACTIVITY_NEW_DOCUMENTFLAG_ACTIVITY_MULTIPLE_TASK 标志的效果相同。
"none" 该 activity 不会为 activity 创建新任务。这是默认值,它只会在已设置 FLAG_ACTIVITY_NEW_TASK 时创建新任务。 “最近使用的应用”屏幕会以默认方式处理 activity:它会显示应用的单个任务,该任务是从用户上次调用的任何 activity 恢复的。
"never" 即使 intent 包含 FLAG_ACTIVITY_NEW_DOCUMENT,该 activity 也不会启动到新文档中。设置此值会替换 FLAG_ACTIVITY_NEW_DOCUMENTFLAG_ACTIVITY_MULTIPLE_TASK 标志的行为(如果在 activity 中设置其中一个标志),并且“最近使用的应用”屏幕将为应用显示单个任务,该任务将从用户上次调用的任意 activity 开始继续执行。

注意:如果值不是 "none""never",则使用 launchMode="standard" 定义 activity。如果未指定此属性,系统会使用 documentLaunchMode="none"

android:enabled
系统是否可实例化 activity。"true" 表示可以,"false" 表示不可以。默认值为 "true"

<application> 元素具有自己的 enabled 属性,该属性适用于所有应用组件,包括 activity。只有在 <application><activity> 属性都为 "true"(因为它们都默认使用该值)时,系统才能将 activity 实例化。如果其中任一属性为 "false",则无法实例化。

android:enableOnBackInvokedCallback
此标志可让您在 activity 级别选择启用预测性系统动画。此行为有助于更轻松地管理将大型多 activity 应用迁移到预测性返回手势的过程。

设置 android:enableOnBackInvokedCallback=false 会在 activity 级别或应用级别关闭预测性返回动画(具体取决于您在哪个级别设置了标记),并指示系统忽略对 OnBackInvokedCallback 平台 API 的调用。

android:excludeFromRecents
是否从“最近使用的应用”屏幕中排除此 activity 启动的任务。换言之,当该 activity 是新任务的根 activity 时,此属性确定最近使用的应用列表中是否应出现该任务。如果应将任务从列表中排除,则设置 "true"如果应将任务包含在列表中,则设置 "false"默认值为 "false"

android:exported
activity 是否可由其他应用的组件启动:

  • 如果设为 "true",那么 activity 可由任何应用访问,并且可通过其确切类名称启动。
  • 如果设为 "false",则 activity 只能由同一应用的组件、使用同一用户 ID 的不同应用或具有特权的系统组件启动。没有 intent 过滤器时,这是默认值。

如果应用中的 activity 包含 intent 过滤器,请将此元素设置为 "true",以允许其他应用启动该 activity。例如,假设 activity 是应用的主要 activity,并且包含 categoryandroid.intent.category.LAUNCHER

如果此元素设为 "false",并且应用尝试启动该 activity,系统会抛出 ActivityNotFoundException

此属性并非是限制 activity 向其他应用公开的唯一方式。权限还可用于限制可调用 activity 的外部实体。请参考 permission 属性。

android:finishOnTaskLaunch
当用户通过在主屏幕上选择任务来重新启动其任务时,是否关闭根 activity 之外的现有 activity 实例。"true" 表示关闭,"false" 表示不关闭。默认值为 "false"

如果此属性和 allowTaskReparenting 的值均为 "true",则优先使用此属性。系统会忽略 activity 的相似性。系统不会更改 activity 的父项,而是将其销毁。

如果未设置 FLAG_ACTIVITY_RESET_TASK_IF_NEEDED,系统将忽略此属性。

android:hardwareAccelerated
是否应为此 activity 启用硬件加速渲染。"true" 表示应启用,"false" 表示不应启用。默认值为 "false"

在 Android 3.0 及更高版本中,应用可使用硬件加速的 OpenGL 渲染程序来提高许多常见 2D 图形操作的性能。启用硬件加速的渲染程序后,Canvas、Paint、Xfermode、ColorFilter、Shader 和 Camera 中的大多数操作都会加速。

这样可使动画和滚动更流畅并且可提高整体响应能力,即使对于没有明确使用框架的 OpenGL 库的应用也是如此。启用硬件加速需要更多资源,因此应用会占用更多内存。

并非所有 OpenGL 2D 操作都会加速。如果您启用硬件加速的渲染程序,请测试应用能否毫无错误地使用该渲染程序。

android:icon
表示 activity 的图标。当需要在屏幕上呈现 activity 时,系统会向用户显示该图标。例如,启动器窗口中会显示启动任务的 activity 所用图标。该图标通常附带标签;如需了解标签,请参考 android:label 属性。

此属性应设置为对包含图片定义的可绘制资源的引用。如果未设置此属性,则改用为整个应用指定的图标。如需了解详情,请参考 <application> 元素的 icon 属性。

activity 的图标(无论是在此处设置还是由 <application> 元素设置)同时也是 activity 所有 intent 过滤器的默认图标。如需了解详情,请参考 <intent-filter> 元素的 icon 属性。

android:immersive
为当前 activity 进行沉浸模式设置。如果设为 "true",则 ActivityInfo.flags 成员会始终设置其 FLAG_IMMERSIVE 位;即便在运行时使用 setImmersive() 方法更改沉浸模式,也会如此。
android:label
一种可由用户读取的 activity 标签。该标签会在系统向用户呈现 activity 时显示在屏幕上。此标签通常与 activity 图标一并显示。如果未设置此属性,则改用整个应用的标签集。请参考 <application> 元素的 label 属性。

activity 的标签(无论是在此处设置还是由 <application> 元素设置)同时也是 activity 所有 intent 过滤器的默认标签。如需了解详情,请参考 <intent-filter> 元素的 label 属性。

此标签应设置为对字符串资源的引用,以便可以像界面中的其他字符串一样进行本地化。不过,为了方便您开发应用,也可以将其设为原始字符串。

android:launchMode
有关 activity 如何启动的说明。共有五种模式可与 Intent 对象中的 activity 标志(FLAG_ACTIVITY_* 常量)协同工作,以确定在调用 activity 处理 intent 时应执行的操作:

"standard"
"singleTop"
"singleTask"
"singleInstance"
"singleInstancePerTask"

默认模式为 "standard"

如下表所示,这些模式可分为两大类:"standard""singleTop" activity 是一类,"singleTask""singleInstance""singleInstancePerTask" activity 是另一类。启动模式为 "standard""singleTop" 的 activity 可以多次实例化。

实例可归属任何任务,并且可位于 activity 任务中的任何位置。通常,它们会启动到名为 startActivity() 的任务中,除非 Intent 对象包含 FLAG_ACTIVITY_NEW_TASK 指令,在这种情况下会选择其他任务。如需了解详情,请参考 taskAffinity 属性。

相比之下,"singleTask""singleInstance""singleInstancePerTask" activity 的行为有所不同。"singleInstancePerTask" 始终位于 activity 任务的根位置。此外,设备一次只能保留一个 "singleInstance" activity 实例,而 "singleInstancePerTask activity 在 FLAG_ACTIVITY_MULTIPLE_TASKFLAG_ACTIVITY_NEW_DOCUMENT 已设置的情况下,在不同的任务中可以多次实例化。

启动模式为 "singleTask" 的 activity 结合了 "singleInstance""singleInstancePerTask" 的行为:activity 可以多次实例化,并且可以位于具有相同 taskAffinity 的任务中的任意位置。但是,设备只能保留一个用于在 activity 任务的根位置查找 "singleTask" activity 的任务。

"standard""singleTop" 模式在某一方面有所不同:每当 "standard" activity 有新的 intent 时,系统都会创建类的新实例来响应该 intent。 每个实例处理单个 intent。同样地,您也可以创建新的 "singleTop" activity 实例来处理新的 intent。

不过,如果目标任务的 activity 堆栈顶部已有一个 activity 实例,则该实例会通过调用 onNewIntent() 接收新的 intent。系统不会创建新实例。否则,如果 "singleTop" activity 的一个现有实例在目标任务中,但不在堆栈顶部,或者它位于堆栈顶部,但不在目标任务中,则系统将创建一个新实例并将其推送到堆栈中。

同样地,如果用户向上导航到当前堆栈上的某个 activity,则该行为由父 activity 的启动模式决定。如果父 activity 有启动模式 singleTop(或者 up intent 包含 FLAG_ACTIVITY_CLEAR_TOP),则系统会将该父项置于堆栈顶部,并保留其状态。

导航 intent 由父 activity 的 onNewIntent() 方法接收。如果父 activity 有启动模式 standard(并且 up intent 不包含 FLAG_ACTIVITY_CLEAR_TOP),则系统会将当前 activity 及其父项同时送出堆栈,并创建新的父 activity 实例来接收导航 intent。

"singleInstance" 模式与 "singleTask""singleInstancePerTask" 也只有一点不同:启动模式为 "singleTask""singleInstancePerTask" 的 activity 允许其他 activity (必须是 "standard""singleTop" activity)是其任务的一部分。

另一方面,"singleInstance" activity 不允许其他 activity 成为其任务的一部分。它必须是任务中唯一的 activity。如果它启动另一个 activity,则系统会将该 activity 分配给其他任务,就如同 intent 中包含 FLAG_ACTIVITY_NEW_TASK 一样。

用例 启动模式 多个实例? 评论
大多数 activity 的正常启动 "standard" 默认。系统始终会在目标任务中创建新的 activity 实例,并向其传送 intent。
"singleTop" 视情况而定 如果目标任务的顶部已存在 activity 实例,则系统会通过调用该实例的 onNewIntent() 方法向其传送 intent,而非创建新的 activity 实例。
专用启动
(不建议用作常规用途)
"singleTask" 视情况而定 系统会在新任务的根位置创建 activity,或将该 activity 放置在具有相同 affinity 的现有任务上。如果任务的根位置已存在 activity 实例,则系统会通过调用现有实例的 onNewIntent() 方法(而非创建新的 activity 实例),向其传送 intent。
"singleInstance" "singleTask" 相似,唯一不同的是系统不会将任何其他 activity 启动到包含该实例的任务中。该 activity 始终是其任务中的唯一 activity。
"singleInstancePerTask" 视情况而定 此 activity 只能作为任务的根 activity、作为创建该任务的第一个 activity 运行,因此在任务中该 activity 只有一个实例。但是 activity 可以在不同的任务中多次实例化。

如上表所示,"standard" 是默认模式,适用于大多数类型的 activity。对众多类型的 activity 而言,"singleTop" 也是常见且有用的启动模式。其他模式("singleTask""singleInstance""singleInstancePerTask")不适用于大多数应用。它们所形成的交互模式可能让用户感到陌生,并且与大多数其他应用差别较大。

无论您选择哪种启动模式,在 activity 启动期间以及使用返回按钮从其他 activity 和任务返回该 activity 时,请务必对其进行易用性测试。

如需详细了解启动模式及其与 Intent 标志的交互,请参阅任务和返回堆栈

android:lockTaskMode
确定当设备在锁定任务模式下运行时,系统如何显示此 activity。

Android 可以类似于 Kiosk 的沉浸式方式(称为锁定任务模式)运行任务。当系统在锁定任务模式下运行时,设备用户通常无法查看通知、访问非许可名单内应用或返回主屏幕,除非主页应用已列入许可名单。

只有经设备政策控制器 (DPC) 列入许可名单后,应用才能在系统处于锁定任务模式时运行。但是,系统和特权应用无需列入许可名单便可在锁定任务模式下运行。

此属性的值可为以下任一 R.attr.lockTaskMode 字符串值:

说明
"normal" 默认值。这是默认值。任务不会启动到锁定任务模式中,但您可通过调用 startLockTask() 将其置于此模式中。
"never"

任务不会启动到 lockTask 模式中,且设备用户无法在“最近使用的应用”屏幕中固定这些任务。

注意:此模式仅可用于系统应用和特权应用。系统会将带有此值的非特权应用视为 normal

"if_whitelisted" 如果 DPC 使用 DevicePolicyManager.setLockTaskPackages() 授权此软件包,则此模式等同于 always,区别在于如果此 activity 是最后一个锁定任务,则其需要调用 stopLockTask() 才能达成目的。如果 DPC 不对此软件包授权,则此模式等同于 normal
"always"

位于此 activity 根位置的任务始终会启动到锁定任务模式中。如果系统在此任务启动时已处于锁定模式中,则新任务将在当前任务上方启动。在锁定模式下启动的任务可通过调用 finish() 退出此模式。

注意:此模式仅可用于系统应用和特权应用。系统会将带有此值的非特权应用视为 normal

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

android:maxRecents
“最近使用的应用”屏幕中位于此 activity 根位置处的最大任务数。达到该条目数时,系统会从“最近使用的应用”屏幕中移除近期最少使用的实例。有效值为 1 到 50 之间的整数,在内存较小的设备上可为 1 到 25 之间的整数。零无效。默认值为 16。
android:maxAspectRatio

activity 支持的最大宽高比。如果应用在具有较大宽高比的设备上运行,则系统会自动为其添加黑边,不会使用屏幕的某些部分,以便应用可按其指定的最大宽高比运行。

最大宽高比表示为设备长边除以短边的商(小数形式)。例如,如果最大宽高比为 7:3,则此属性的值应设为 2.33。

在非穿戴式设备上,此属性的值需设为大于或等于 1.33。在穿戴式设备上,该值必须大于或等于 1.0。否则,系统将忽略此设定值。

注意:如果 activity 已将 resizeableActivity 设置为 true,则系统会忽略此属性,因为这意味着此 activity 支持任何尺寸。

如需详细了解此属性,请参阅声明最大宽高比

android:multiprocess
确定 activity 实例是否可以启动到启动该实例的组件进程中。"true" 表示可以,"false" 表示不可以。默认值为 "false"

正常情况下,新的 activity 实例会启动到定义该实例的应用进程内,因此所有 activity 实例都在同一进程内运行。不过,如果将该标志设置为 "true",则 activity 实例便可在多个进程内运行,以便系统在任何使用实例的地方创建实例(前提是权限允许这样做),但这几乎毫无必要。

android:name
实现 activity 的类的名称,是 Activity 的子类。属性值通常是完全限定的类名称,例如 "com.example.project.ExtracurricularActivity"。不过,作为一种简写形式,如果名称的第一个字符是句点(例如 ".ExtracurricularActivity"),则会附加到 build.gradle 文件中指定的命名空间

发布应用后,除非您已设置 android:exported="false",否则请勿更改此名称。没有默认值。必须指定此名称。

android:noHistory
当用户离开 activity 且屏幕上不再显示该 activity 时,是否应从 activity 堆栈中将其移除并通过调用 finish() 方法来完成 activity。"true" 表示完成,"false" 表示不完成。默认值为 "false"

"true" 一值表示 activity 不会留下历史跟踪记录。它不会留在任务的 activity 堆栈内,因此用户将无法返回该 activity。在此情况下,如果您通过启动另一个 activity 来获取该 activity 的结果,系统永远不会调用 onActivityResult()

该属性是 API 级别 3 中的新增属性。

android:parentActivityName
activity 逻辑父项的类名称。此处的名称必须与为相应 <activity> 元素的 android:name 属性所指定的类名称一致。

系统会读取该属性,以确定当用户点按操作栏中的“向上”按钮时应该启动哪一个 activity。系统还可利用这些信息,通过 TaskStackBuilder 合成 activity 的返回堆栈。

如要支持 API 级别 4 至 16,您还可使用为 "android.support.PARENT_ACTIVITY" 指定值的 <meta-data> 元素来声明父 activity:

<activity
    android:name="com.example.app.ChildActivity"
    android:label="@string/title_child_activity"
    android:parentActivityName="com.example.app.MainActivity" >
    <!-- Parent activity meta-data to support API level 4+ -->
    <meta-data
        android:name="android.support.PARENT_ACTIVITY"
        android:value="com.example.app.MainActivity" />
</activity>

如需了解通过声明父 activity 来支持向上导航的详细信息,请阅读提供向上导航

该属性是 API 级别 16 中的新增属性。

android:persistableMode

定义当设备重启时,如何在所处的任务中保留 activity 实例。

如果任务的根 activity 将此属性的值设置为 persistRootOnly,则仅保留根 activity。否则,系统会检查任务返回堆栈中较高位置的 activity,并在其中保留任何将此属性的值设为 persistAcrossReboots 的 activity。

如果使用此属性,您必须将其值设置为以下某个值:

说明
persistRootOnly 默认值。系统重启时会保留 activity 任务,但仅使用根 activity 的启动 intent。

如果应用的启动 intent 加载应用的根 activity,则此 activity 不会接收 PersistableBundle 对象。因此,在设备重启时,请勿使用 onSaveInstanceState() 保留应用根 Activity 的状态。

注意:只有在应用的根 activity 上设置此属性值后,该值才会影响应用的行为。

persistAcrossReboots

系统将保留此 activity 的状态,以及每个高于返回堆栈且已将自身的 persistableMode 属性设置为 persistAcrossReboots 的 activity 的状态。如果 Activity 未将 persistableMode 属性设置为 persistAcrossReboots,或者使用 Intent.FLAG_ACTIVITY_NEW_DOCUMENT 标志启动,则系统不会保留此 Activity 及高于返回堆栈的所有 Activity。

当 intent 加载应用中将 persistableMode 属性设置为 persistAcrossReboots 的 activity 时,此 activity 将在其 onCreate() 方法中接收 PersistableBundle 对象。因此,您可使用 onSaveInstanceState() 在跨设备重新启动时保留 activity 的状态,只要其 persistableMode 属性设置为 persistAcrossReboots

注意:即使在应用根 activity 之外的 activity 上设置此属性值,该值也会影响应用的行为。

persistNever

系统不会保留 activity 的状态。

注意:只有在应用的根 activity 上设置此属性值后,该值才会影响应用的行为。

该属性是 API 级别 21 中的新增属性。

android:permission
启动 activity 或以其他方式使 activity 响应 intent 时,客户端必须具备的权限的名称。如果系统尚未向 startActivity()startActivityForResult() 的调用方授予指定权限,则其 intent 将不会传递给 activity。

如果未设置该属性,则对 activity 应用由 <application> 元素的 permission 属性所设置的权限。如果二者均未设置,则 activity 不受权限保护。

如需详细了解权限,请参阅应用清单概览的权限部分以及安全提示

android:process
应在其中运行 activity 的进程的名称。正常情况下,应用的所有组件均以为应用创建的默认进程名称运行,您无需使用该属性。但如有必要,您可以使用该属性替换默认进程名称,以便将应用组件散布到多个进程中。

如果为此属性分配的名称以英文冒号 (:) 开头,则系统会在需要时创建应用专用的新进程,并且 activity 会在该进程中运行。

如果进程名称以小写字符开头,则 activity 将在采用该名称的全局进程中运行,前提是它具有相应权限。这样,不同应用中的组件就可以共享进程,从而减少资源使用量。

<application> 元素的 process 属性可为所有组件设置一个不同的默认进程名称。

android:relinquishTaskIdentity
activity 是否会将其任务标识符交给任务堆栈中在其之上的 activity。如果任务的根 activity 将该属性设置为 "true",则该任务会用其下一个 activity 的 intent 替换基本 Intent

如果下一个 activity 也将该属性设置为 "true",则该 activity 会将基本 Intent 让给其在同一任务中启动的其他 activity。系统会继续为每个 activity 执行此过程,直至遇到某个 activity 将该属性设置为 "false" 为止。默认值为 "false"

如果将此属性设置为 "true",则 activity 还可使用 ActivityManager.TaskDescription 更改“最近使用的应用”屏幕中的标签、颜色和图标。

android:resizeableActivity

指定应用是否支持多窗口模式。您可以在 <activity><application> 元素中设置此属性。

如果您将此属性设为 "true",则用户可以在分屏模式和自由窗口模式下启动 activity。如果您将此属性设为 "false",则无法针对多窗口环境测试或优化应用。在应用了兼容模式的情况下,系统可能仍会将 activity 置于多窗口模式中。

将此属性设置为 "false" 不能保证屏幕(例如画中画)中不会显示多窗口模式下的其他应用。因此,设置此标志并不意味着您的应用具有专属资源访问权限。

如果您的应用以 API 级别 24 或更高级别为目标平台,且您未指定此属性的值,则其值默认设为 "true"

如果您的应用以 API 级别 31 或更高级别为目标平台,则此属性在小屏设备和大屏设备上的运作方式会有所不同:

  • 大屏 (sw >= 600dp) 设备:所有应用都支持多窗口模式。该属性指示应用是否可以调整大小,而不是应用是否支持多窗口模式。如果 resizeableActivity="false",应用会在必要时进入兼容模式,以与显示屏尺寸相符。
  • 小屏 (sw < 600dp) 设备:如果 resizeableActivity="true",activity 的最小宽度和最小高度都在多窗口模式要求范围内,则应用支持多窗口模式。如果 resizeableActivity="false",则无论 activity 的最小宽度和高度是多少,应用都不支持多窗口模式。

注意:设备制造商可以替换 API 级别 31 的行为。

该属性是 API 级别 24 中的新增属性。

注意:任务的根 activity 值会应用于任务中启动的所有其他 activity。也就是说,如果任务的根 activity 可调整大小,系统会视为任务中的所有其他 activity 均可调整大小。如果根 activity 不可调整大小,则任务中的其他 activity 也不可调整大小。

android:screenOrientation

activity 在设备显示屏上的屏幕方向。

在 Android 7.0(API 级别 24)及更高版本中,如果 activity 处于多窗口模式,系统会忽略针对此属性的运行时更改。

Android 12(API 级别 31)及更高版本中,设备制造商可以对个别设备屏幕(例如,可折叠设备的平板电脑大小的屏幕)进行配置,以便忽略指定的屏幕方向,强制已指定为仅竖屏模式的应用在横屏模式下垂直(但采用信箱模式)展示内容,以确保应用既保持纵向宽高比,又能使应用保持合理方向,以提升易用性。

其值可以是下列任一字符串:

"unspecified" 默认值。由系统选择方向。在不同设备上,系统使用的政策以及基于政策在特定上下文中所做的选择可能会有所差异。
"behind" 与 activity 堆栈中紧接其后的 activity 的方向相同。
"landscape" 屏幕方向为横向(显示的宽度大于高度)。
"portrait" 屏幕方向为纵向(显示的高度大于宽度)。
"reverseLandscape" 屏幕方向是与正常横向方向相反的横向。 在 API 级别 9 中引入。
"reversePortrait" 屏幕方向是与正常纵向方向相反的纵向。 在 API 级别 9 中引入。
"sensorLandscape" 屏幕方向为横向,但可根据设备传感器调整为正常或反向的横向。即使用户锁定基于传感器的旋转,系统仍可使用传感器。 在 API 级别 9 中引入。
"sensorPortrait" 屏幕方向为纵向,但可根据设备传感器调整为正常或反向的纵向。即使用户锁定基于传感器的旋转,系统仍可使用传感器。不过,能否上下倒转取决于设备配置。 在 API 级别 9 中引入。
"userLandscape" 屏幕方向为横向,但可根据设备传感器和用户首选项调整为正常或反向的横向。 在 API 级别 18 中引入。
"userPortrait" 屏幕方向为纵向,但可根据设备传感器和用户首选项调整为正常或反向的纵向。不过,能否上下倒转取决于设备配置。 在 API 级别 18 中引入。
"sensor" 设备方向传感器决定屏幕方向。显示方向取决于用户如何手持设备。它会在用户旋转设备时发生变化。但在默认情况下,一些设备不会旋转为所有四种可能的方向。如要使用所有四个方向,请使用 "fullSensor"。即使用户锁定基于传感器的旋转,系统仍可使用传感器。
"fullSensor" 设备方向传感器确定四个方向中的任一方向。 这与 "sensor" 类似,不同之处在于无论设备在正常情况下使用哪种方向,该值均支持所有四种可能的屏幕方向。例如,一些设备正常情况下不使用反向纵向或反向横向,但其支持这些方向。在 API 级别 9 中引入。
"nosensor" 确定屏幕方向时不考虑物理方向传感器。系统会忽略传感器,因此显示内容不会随用户手持设备的方向而旋转。
"user" 用户当前的首选方向。
"fullUser" 如果用户锁定基于传感器的旋转,则其行为与 user 相同,否则其行为与 fullSensor 相同,并且支持所有四种可能的屏幕方向。 在 API 级别 18 中引入。
"locked" 将方向锁定在其当前的任意旋转方向。在 API 级别 18 中引入。

注意:如果您声明其中一个横向或纵向值,则系统会将其视为对 activity 运行方向的硬性要求。 因此,您声明的值支持通过 Google Play 等服务进行过滤,这样只有支持 activity 规定方向的设备才能使用您的应用。例如,如果您声明 "landscape""reverseLandscape""sensorLandscape",则您的应用只能供支持横向方向的设备使用。

此外,您还应通过 <uses-feature> 元素(例如 <uses-feature android:name="android.hardware.screen.portrait"/>)明确声明,您的应用要求采用纵向还是横向方向。这是 Google Play(以及其他支持过滤的服务)提供的一种过滤行为,平台本身并不能控制是否可在仅支持某种方向的设备上安装您的应用。

android:showForAllUsers

当设备的当前用户不是启动 activity 的用户时,是否要显示 activity。您可将此属性设置为字面量值(例如 "true""false"),或包含布尔值的资源或主题属性。

该属性是 API 级别 23 中的新增属性。

android:stateNotNeeded
能否在不保存 activity 状态的情况下将其终止并成功重新启动。"true" 表示可在不考虑其之前状态的情况下重新启动,"false" 表示需要之前状态。默认值为 "false"

正常情况下,为保存资源而暂时关闭 activity 前,系统会调用其 onSaveInstanceState() 方法。该方法会将 activity 的当前状态存储在一个 Bundle 对象中,然后在 activity 重启时将其传递给 onCreate()。如果将该属性设置为 "true",则系统可能不会调用 onSaveInstanceState(),并且会向 onCreate() 传递 null(而非 Bundle)。这与 activity 首次启动时的情况完全相同。

"true" 设置意味着 activity 能够在未保留状态时重启。例如,显示主屏幕的 activity 可以使用该设置,确保系统不会在该 activity 因某种原因而崩溃时将其移除。

android:supportsPictureInPicture

指定 activity 是否支持画中画屏幕。

android:taskAffinity
与 activity 有着相似性的任务。从概念上讲,具有同一相似性的 activity 归属同一任务;从用户的角度来看,则是归属同一“应用”。任务的相似性由其根 activity 的相似性确定。

相似性确定两点内容:activity 更改父项后的任务(请参考 allowTaskReparenting 属性),以及通过 FLAG_ACTIVITY_NEW_TASK 标志启动 activity 时,用于容纳该 activity 的任务。

默认情况下,应用中的所有 activity 都具有同一亲和性。您可以设置该属性,以不同方式将其分组,甚至可以在同一任务内放置不同应用中定义的 activity。如要指定 activity 与任何任务均无相似性,请将其设置为空字符串。

如果未设置该属性,则 activity 会继承为应用设置的相似性。请参考 <application> 元素的 taskAffinity 属性。应用默认相似性的名称是在 build.gradle 文件中设置的命名空间

android:theme
对定义 activity 总体主题的样式资源的引用。此属性会自动将 activity 的场景设置为使用该 theme,并且还可引发 activity 启动前的“启动”动画,以更加符合 activity 的实际外观。

如果未设置该属性,则 activity 会继承通过 <application> 元素的 theme 属性为应用整体设置的主题。如果同样未设置该属性,则使用默认系统主题。如需了解详情,请参阅样式和主题

android:uiOptions
有关 activity 界面的额外选项。必须是以下某个值。

说明
"none"没有额外的界面选项。这是默认值。
"splitActionBarWhenNarrow"当水平空间受限时(比如手机处于竖屏模式时),在屏幕底部添加一个栏,以显示应用栏(也称为操作栏)中的操作项。系统将应用栏分成顶部导航区和底部操作项栏,而非在屏幕顶部的应用栏中显示少量操作项。这意味着操作项以及顶部的导航和标题元素均能获得适量空间。系统不会将菜单项拆分到两个栏中。它们始终一起出现。

如需详细了解应用栏,请参阅添加应用栏

此属性是在 API 级别 14 中添加的。

android:windowSoftInputMode
Activity 的主窗口与包含屏幕软键盘的窗口之间的交互方式。该属性的设置会影响两点内容:
  • 当 activity 成为用户注意的焦点时,软键盘的状态是隐藏还是可见。
  • 是否将 activity 主窗口的尺寸调小,为软键盘腾出空间;或当软键盘遮盖部分窗口时,是否平移其内容以使当前焦点可见。

该设置必须是下表所列的其中一项值,或一个 "state..." 值加上一个 "adjust..." 值的组合。在任一组中设置多个值(例如,多个 "state..." 值)均会产生未定义的结果。 各个值之间用竖线 (|) 分隔,如以下示例所示:

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

此处设置的值("stateUnspecified""adjustUnspecified" 除外)会替换主题中设置的值。

说明
"stateUnspecified" 不指定软键盘的状态是隐藏还是可见。系统会选择合适的状态,或依赖主题中的设置。

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

"stateUnchanged" 当 activity 转至前台时保留软键盘最后所处的任何状态,无论是可见还是隐藏。
"stateHidden" 当用户选择 activity 时(换言之,当用户确实是向前导航到 activity,而不是因离开另一 activity 而返回时)隐藏软键盘。
"stateAlwaysHidden" 当 activity 的主窗口有输入焦点时始终隐藏软键盘。
"stateVisible" 当用户选择 activity 时(换言之,当用户确实是向前导航到 activity,而不是因离开另一 activity 而返回时)显示软键盘。
"stateAlwaysVisible" 当窗口获得输入焦点时,会显示软键盘。
"adjustUnspecified" 不指定 activity 的主窗口是否通过调整尺寸为软键盘腾出空间,或者是否通过平移窗口内容以在屏幕上显示当前焦点。 根据窗口的内容是否存在任何可滚动其内容的布局视图,系统会自动选择其中一种模式。如果存在这种视图,系统会调整窗口尺寸,前提是可通过滚动操作在较小区域内看到窗口的所有内容。

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

"adjustResize" 始终调整 activity 主窗口的尺寸,以为屏幕上的软键盘腾出空间。
"adjustPan" 不通过调整 activity 主窗口的尺寸为软键盘腾出空间。相反,窗口的内容会自动平移,使键盘永远无法遮盖当前焦点,以便用户始终能看到自己输入的内容。这通常不如调整窗口尺寸可取,因为用户可能需关闭软键盘才能进入被遮盖的窗口部分,并与之进行交互。

该属性是 API 级别 3 中的新增属性。

引入于:
API 级别 1,为 noHistorywindowSoftInputMode(API 级别 3 中的新增属性)之外的所有属性引入。
另请参阅:
<application>
<activity-alias>