Android 配置文件<activity>元素

Posted 2020-06-30 麦田里的守望者-Jiang

本文翻译自：<activity>，如果有什么不正确的地方请指正。

语法：

<span style="font-size:14px;"><span style="font-size:14px;"><activity android:allowEmbedded=["true" | "false"]
          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:parentActivityName="string" 
          android:permission="string"
          android:process="string"
          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></span></span>

被包含在：

<application>

可以包含：

<intent-filter>

<meta-data>

描述：

    声明实现了应用程序可视化用户界面一部分的一个activity（activity子类），在清单文件中的必须以<activity>元素表示。任何未声明的，将不会被系统看到而且永远不会被运行。

属性：

    android:allowEmbedded

      表明这个activity可以作为其它activity嵌入的子activity被启动，特别地在一些子activity存活在一个容器的案例中，如一个显示器被另一个activity所拥有。例如：被用于Wear自定义notification的activity必须声明了这个，Wear才能在上下文流中展示这个驻留在其它进程中的activity。

      该属性默认的值是false

    android:allowTaskReparenting

      该属性表示activity是否可以从它启动的任务栈移动到它具有亲和力（affinity）的任务栈，且这个任务栈是下一个被置为前台的任务栈。"true"表示可以移动，“false”表示必须停留在它启动的任务栈中。

      如果这个属性没有被设置，那么activity的这个属性值为false。

      通常地，当activity被启动了，它会关联到启动它的那个 activity 所在的任务栈中，而且在它的整个生命周期过程中都会停留在那个任务栈中。当它的当前任务栈不在被显示的时候，你可以使用这个属性将它重新定位到它具有亲和力（affinity）的任务栈中。一般来说，它会造成该应用程序的所有activity移动到另一个应用程序的主要任务栈中。

      activity的亲和性（affinity）是通过属性 taskAffinity 定义的，任务栈的亲和性（affinity）取决于通过读取到的根activity的亲和性（affinity）。因此，通过定义，根activity总是在任务栈中具有相同亲和性（affinity）。因为有"singleInstance"和"singleTask"启动模式的 activity 只能在任务栈的根部，那么重新定位就不能用于"singleTop"和"standard"启动模式的activity。

    android:alwaysRetainTaskState

      该属性表示activity所存在的任务栈的状态是否总是被系统所保持，‘‘true"表示是，"false"表示在某些情况下，系统允许将任务栈重置为它的初始状态。属性默认值是"false"，这个属性仅对任务栈的根activity有用，对于其它的activity将被忽略。

      通常，在某些情况，当用户从主屏幕重新选择任务栈时，系统会清除掉这个任务栈。一般地，如果用户在很长时间（比如30分钟）没有访问这个任务栈，它就会被清除。

      然而，当该属性设置为"true"时，用户返回到这个任务栈总是为它的最后一个状态，不管他是怎么到达这个任务栈的。这是非常有用的，例如在应用程序中用户喜欢浏览网页，并且想保留打开的每一个网页的状态。

    android:clearTaskOnLaunch

      该属性表示是否无论何时从主屏幕启动应用程序，都从任务栈中移除除根activity以外的其它activity。默认值是"false"，这个属性仅仅对activity启动一个新的任务栈有意义，对启动任务中的其它activity没有作用。

      当这个属性是"true"的时候，每次用户再次启动这个任务栈，都会显示任务栈的根activity，不管它们在任务栈中最后一次在做什么，或者是否是按返回按钮离开的。当是"false"的时候，在某些情况下任务栈会清除掉activity，但不是总是这样。

      如果这个属性和alwaysRetainTaskState都是"true"，任何可被重新定位的activity都会移动到它们同享一个亲和力"affinity"的任务栈中。其它的activity除外。

    android:configChanges

      配置改变之后，activity它会自己处理。当在运行的时候配置改变了，activity会关闭然后默认重启，但是声明了configChanges属性，将会阻止activity被重启，反而,activity会依然运行，它的onConfigurationChanged()方法会被回调。

      注意：应该避免使用该属性，要使用也是最后的手段。请仔细阅读 关于如何合适的处理（Handing Runtime Changes ）由于配置改变引起的activity重启。

      任何一个下面的字符串都是这个属性的有效值，多个值通过 "|" 分开，例如："locale|navigation|orientation"。

      

      

      

     
      所有这些配置的更改都会影响应用程序所看到的资源值。因此，当 onConfigurationChanged() 方法被回调时，通常它将需要再次恢复所有资源（包括视图的布局，图片等等）来正确地处理变化。

    android:enabled

      该属性表示activity是否可以被系统初始化。"true" 表示是，"false"表示不是，默认值是"true"。

      <application>元素有它自己的可适用于所有应用程序组件（包括activity）的 enabled 属性，为了使系统能够实例化activity，<application>和<activity>元素的 enabled 属性必须设置为"true"（默认值也是"true"），如果其中一个为"false"，则它不能够实例化。

    android:excludeFromRecents

      该属性表示这个activity所启动的任务栈是否应该被排除在最近使用的应用程序列表中。也就是说，当这个activity是一个新任务栈的根actvity，这个属性决定这个任务栈不会出现在最近应用程序的列表中。"true"表示这个任务栈会被排除在外，"false"表示会被包含到列表中。

   android:exported

     该属性表示这个activity是否可以被其它应用程序的组件启动，"true"可以，"false"不可以。如果是"false"，则这个activity只能被同一个应用程序的组件或者具有相同 user ID 的组件启动。

     该属性的默认值取决于activity是否包含 intent filters。缺少filters意味着activity只能通过指定它确切的类名称来启动，这暗示着该activity只能在应用程序内容使用，因此在这种情况下，默认值是"false‘。另一方面，至少有一个filters暗示着这个activity可以被其它应用程序启动，因此默认值是"true"。

     这个属性不是唯一限制activity暴露在其它应用程序面前的方式。你也可以使用 权限（permission ）来限制外部可以启动这个activity的对象。

    android:finishOnTaskLaunch

      这个属性表示当用户再次启动activity所在的任务栈时（从主屏幕选择任务栈）这个已经存在的activity实例是否应该被关闭（finish），"true"应该被关闭，"false"不应该，默认值是"false"。

      如果这个属性和 alwaysRetainTaskState 都是"true"，那么这个属性优先于其它的属性。并且这个activity的亲和性（affinity）将会被忽略，不能被重新定位到其它的任务栈。

    android:hardwareAccelerated

      这个属性表示activity是否可以被硬件加速渲染，"true"是，"false"不是，默认值是"false"。

      从Android 3.0开始，为了增加常见2D图形操作的性能，新增适合于应用程序的硬件加速OpenGL渲染。当硬件加速渲染是可用的时候，大多数在Canvas, Paint, Xfermode, ColorFilter, Shader, Camera上的操作都会加速。这个结果在平滑的动画，平滑的滚动中，甚至在没有明确地使用框架OpenGL库的应用程序中都会提高整体响应。由于增加资源是硬件加速，你的应用程序会消耗更多的内存。

      注意：并不是所有的OpenGL 2D 操作都是能够加速的。如果你使硬件加速渲染是可用的，请测试你的应用程序以确保渲染不会出错。

    android:icon

      icon代表着activity。图标展示给用户是activity显示在屏幕上的表示。例如，启动任务栈的activity图标在窗口中显示。icon通常伴随着一个label。

      设置这个属性必须关联到一个drawable资源。如果没有设置，会用application的icon代替。

      activity的icon，无论是在这里设置，还是通过<application>元素设置，都是activity的 intent filters的默认icon。

   android:label

      对于activity的可读用户标签。当activity必须向用户表示时，该标签将显示在屏幕上。通常伴随着icon一起显示。

      如果这个属性不设置，会用application的label代替。

      activity的label，无论是在这里设置，还是通过<application>元素设置，都是activity的 intent filters的默认label。

      该label应该被关联到一个string资源，以便它可以像用户界面中的其它字符串进行本地化。然而，当你开发应用程序时，它也可以被设置为一个字符串。

   android:launchMode

      该属性表示activity应该如何被启动的一个指令。这里有四种模式联系着 intent 对象中的 activity flag(Intent.FLAG_ACTIVITY_)，来决定当 activity 被调用的时候应该怎样处理这个 intent。它们是：

     "standard" 

      "singleTop" 

      "singleTask" 

      "singleInstance"

      默认模式是"strandard"。

      正如下面表中展示的一样，模式分为两种群体，一种是"standard" 和 "singleTop"，一种是"singleTask" 和 "singleInstance"。"standard" 或者 "singleTop" 启动模式可以被实例化多次，这种实例可以属于任何 task 也可以位于任何activity stack。通常，通过调用 startActivity()方法启动任务栈（如果这个 Intent 对象 含有 Intent.FLAG_ACTIVITY_NEW_TASK 指令，在这种情况下将启动一个新的 task）。

      相比之下， "singleTask" 和 "singleInstance" 启动模式只能启动一个 task，它们总是在 activity stack 的根部。此外，设备在一个时间只能拥有这个 activity 的一个实例。

     "standard"  和 "singleTop" 模式是不相同的。对于一个 "standard‘ activity 有一个新的 intent，就有一个 实例被创建来响应这个 intent。每个 实例 处理一个 intent。相似地，一个新的 "singleTop" activity 实例也可能被创建处理一个 intent。然而，如果目标 task 已经有一个存在的实例在栈的顶部，这个实例将会接受这个新的 intent（onNewIntent()会被调用）,而不会创建一个新的实例。在其它情况下，例如：如果已经存在一个"singleTop" activity的实例在目标 task中，但不在 stack 的顶部，或者它在 stack 的顶部但不在目标 task 中，这时一个新的实例将会被创建压入 stack 中。

      相似地，如果你浏览到当前 stack 上的activity，该行为取决于 parent activity 的启动模式。如果 parent activity 有启动模式 singleTop （或者 intent 中含有 Intent_FLAG_ACTIVITY_CLEAR_TOP），这个 parent 会被带到 stack 的顶部，而且它的状态是可保存的。导航 intent 被 parent activity的 onNewIntent()方法接受。如果 parent activity 有启动模式 standard （而且上一个 intent 不包含Intent_FLAG_ACTIVITY_CLEAR_TOP ），那么当前 activity 和 它的 parent activity 都将从 stack 中弹出，而且一个 新的 parent activity 实例将被创建来接受这个导航 intent。

      "singleTask" 和 "singleInstance" 也是不相同的，"singleTask" activity 允许其它activity 可以成为它的 task 的一部分。它总是在这个 task 的根部，但是其它 activity（必须是 "standard" 或者 "singleTop" activity）才可以进入这个 task。"singleInstance" activity，另一方面，不允许其它 activity 成为这个 task 的一部分。它是这个 task 仅有的一个 activity。如果它启动另一个 activity，这个activity 将被分配到其它的 task（与一个 Intent.FLAG_ACTIVITY_NEW_TASK 的 intent一样）。

      

      正如上面表中所示，"standard" 是标准的模式，而且适合于大多是类型e的activity。"singleTop"也是一种常见的对大多数activity有用的模式。其它的两种模式 "singleTask" 和 "singleInstance" 对于大多数应用程序不适合，因为它们会引起一种可能对用户不熟悉且非常不同于其它应用程序的相互影响模型。

      无论你选择哪种启动模式，请确保测试 activity 在启动启动期间，以及在导航返回和按返回键返回其它 activity 和 task 时候的适用性。

      关于更多的启动模式以及它们相关联的 Intent flags ，请查看Task and Back Stack 文档。

    android:multiprocess

      该属性表示 activity 的实例能否启动到那个启动它的组件的进程中。"true" 表示可以，"false" 表示不可以，默认值是 "false"。

      通常，activity的实例被启动到 定义的应用程序所在的进程中，因此所有的 activity 实例都运行在一个进程中。然而，如果这个表示设置为 "true"，activity 的实例可以运行在多个进程中，允许系统在使用时创建实例，这种情况几乎没有必要。

   android:name

      实现了activity类的名字。这个属性值应该完全限定类名（例如："com.example.project.ExtracurricularActivity"。然而，如果名字的第一个字符是"."（例如：".ExtracurricularActivity"），它会被追加在<manifest>元素中定义的包名后。

      一旦你发布了你的应用程序，你就不能改变这个名字（如果没有设置 android:exported = "false"）。

      这个没有默认值，你必须要指定它。

    android:noHistory

      该属性表示当用户导航离开activity且它不再屏幕上显示时，是否该从 activity stack 中移除且关闭（它的finish()方法被调用）。"true" 表示是，"false" 表示不是，默认值是"false"。

      值为"true" 意味着 activity 不会留下历史痕迹。它也不会停留在 activity stack 的 task中 ，用户也不能返回到它。

      这个属性是API 3 时引入的。

    android:parentActivityName

      这个类名是 activity 逻辑上的 parent 。这里的名字必须要与<activity>元素的 android:name 属性联系在一起。

      系统读取这个属性来决定当使用action bar 上的返回按钮时哪个 activity 应该被启动。系统也可以使用这个信息来与TaskStackBuilder 一起合成一个 activity 的返回栈。

      为了支持 API 4-16，也可以声明一个有指定了值为"android.support.PARENT_ACTIVITY"的<meta-data>元素的 parent activity。例如：

<span style="font-size:14px;"><activity
    android: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-data
        android:name="android.support.PARENT_ACTIVITY"
        android:value="com.example.app.MainActivity" />
</activity></span>

      有关声明 parent activity 支持向上导航的更多信息，请阅读Providing Up Navigation。

      这个属性是在 API 16 时引入的。

    android:process

      进程的名字就是 activity 运行的进程。通常，你不需要使用这个属性，应用程序的所有组件都运行在应用程序创建的默认进程名字中。但是如果需要，你可以通过这个属性重写进程的名字，允许你在多个进程中扩展应用程序组件。

      如果分配给这个属性的名字以冒号":"开头，当它被需要时且 activity 运行在这个进程中，一个新的对应用程序是私有的进程将被创建。如果进程的名字以小写字母开始，则 activity 会在该名称的一个全局进程中运行，但要提供它具有的权限。这允许不同应用程序的组件共享一个进程，减少资源的使用。

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

    android:permission

      客户端必须启动 activity 或者以其它方式来响应一个 intent 的权限，如果调用的 startActivity() 或者 startActivityForResult() 没有被授予指定的权限，它的 intent 不会被传递到这个 activity。

      如果这个属性没有被设置，<application>元素的 permission 属性适用于这个 activity。如果<application>的 permission 属性也没有设置，这个activity不被权限保护。

      有关 permission 的更多信息，请查看 Permissions。

    android:screenOrientation

      activity 的方向将显示在屏幕上。

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

      

      

      注意：当你声明一个 portrait 或者 landscape 值，它将被认为对 activity的运行方向是一个很难的请求。同样，你声明的值可以通过服务过滤，如Google Play，这样你的应用程序只提供支持你的 activity 所需的方向的设备。例如：如果你声明了"landscape","reverseLandscape"或者"sensorLandscape"，然后你的应用程序只支持 landscape 方向的设备。然而，你应该用<uses-feature>元素明确地声明你的应用程序要求的方向（portrait or landscape，例如： <uses-feature android:name="android.hardware.screen.portrait"/>。这纯碎是 Google Play 提供的过滤行为，平台本身不控制当设备只支持某些方向时你的应用程序是否可以安装。

    android:stateNotNeeded

      activity是否在不保存它的状态下可以被杀死并成功地重新启动，"true" 表示在不保存它以前的状态下可以重启，"false"表示需要它以前的状态。默认值是"false"。

      通常，为了节省资源，在activity暂时被强制关闭之前，它的 onSaveInstanceState() 方法会被调用。这个方法将当前activity的状态存放到一个Bundle对象中，当activity重启时会将这个对象传到 onCreate() 方法中。如果这个属性设置为"true‘，onSaveInstanceState()方法不会被调用，onCreat()方法会传递一个null值而不是一个Bundle对象（与activity第一次启动一样）。

      "true"能够确保在没有保留状态的情况下，activity也可以重启。例如：显示在主屏幕的activity可以使用这个值来确保它在某些情况下崩溃也不会被移除。

    android:taskAffinity

      该属性表示activity具有亲和力的task，具有相同亲和力的activity在概念上属于相同的task（从用户的角度来看就是同一个应用程序），activity的亲和力取决于它的根activity的亲和力。

      亲和性决定了两件事：activity重新定位到的task（查看allowTaskReparenting），存储当通过FLAG_ACTIVITY_NEW_TASK标志启动的activity的task。

      默认情况下，应用程序中的所有activity具有相同的亲和力，你可以通过设置这个属性来将它们分为不同的组，甚至将不用应用程序中的定义的activity放在同一个task中。为了指定activity不具有任何task的亲和力，将其设置为空字符串就行了。

      如果这个属性没有设置，activity会继承应用程序设置的亲和力，应用程序的默认亲和力的名称是由<manifest>元素设置的包名。

    android:theme

      引用的style资源为activity定义了整个主题，这也自动地设置了activity的上下文中使用的主题。

      如果这个属性没有设置，activity会继承 application 设置的主题。如果应用程序也没有设置主题，将使用系统设置的主题。对于更多的信息，请查看Style and Theme 开发指南。

    android:uiOptions

      activity UI 额外的选项。

      必须是下面的值之一。

      

      关于action bar 更多的信息，请查看Action Bar 开发指南。

      这个属性是API 14 时添加的。

    android:windowSoftInputMode

      activity 的主窗口怎样与包含屏幕上软键盘的窗口进行交互，这个属性的设置影响两点：

      软件盘的状态（影藏或者显示），当activity 成为用户关注的焦点。

      调整了activity的主窗口，无论是为软件盘提供空间而调整它的大小到更小，还是当窗口的部分被软件盘遮挡时让它的部分内容平移以使当前焦点是可见的。

      设置必须是下面列表中的值之一，或者是一个"state...‘值加上一个"adjust..."值。可以设置多个值，其中值之间用"|"分开。例如：

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

      在这设置的值（除“stateUnspecified”和“adjustUnspecified”以外）会重写主题中的值。

      

      

      这个属性是API 3时引入的。

      

介绍：

    所有的属性除"noHistory" 和"windowSoftInputMode"外都是在API 1时引入的，它们是在API 3时引入的。

见：

    <application>

    <activity-alias>