1page.title=应用清单文件 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7<h2>本文内容</h2> 8<ol> 9<li><a href="#filestruct">清单文件结构</a></li> 10<li><a href="#filec">文件约定</a> 11<li><a href="#filef">文件功能</a> 12 <ol> 13 <li><a href="#ifs"> Intent 过滤器</a></li> 14 <li><a href="#iconlabel">图标和标签</a></li> 15 <li><a href="#perms">权限</a></li> 16 <li><a href="#libs">库</a></li> 17 </ol></li> 18</ol> 19</div> 20</div> 21 22<p> 23 每个应用的根目录中都必须包含一个 24AndroidManifest.xml 文件（且文件名精确无误）。 <span itemprop="description">清单文件为 25Android 系统提供有关您的应用的基本信息，系统必须获得这些信息才能运行任意应用代码。 26 27</span> 此外，清单文件还可执行以下操作： 28</p> 29 30<ul> 31<li>为应用的 Java 32软件包命名。软件包名称充当应用的唯一标识符</li> 33 34<li>描述应用的各个组件，即：构成应用的 Activity、服务、广播接收器和内容提供程序。 35 36为实现每个组件的类命名并发布其功能（例如，它们可以处理的 37{@link android.content.Intent 38Intent} 消息）。根据这些声明，Android 39系统可以了解这组件具体是什么，以及在什么条件下可以启动它们</li> 40 41<li>确定将托管应用组件的进程</li> 42 43<li>声明应用必须具备哪些权限才能访问 44API 中受保护的部分并与其他应用交互</li> 45 46<li>还声明其他应用与该应用组件交互所需具备的权限 47</li> 48 49<li>列出 {@link android.app.Instrumentation} 50类，这些类可在应用运行期间提供分析和其他信息。这些声明只会在应用处在开发和测试阶段时出现在清单文件中；它们会在应用发布之前被删除 51 52</li> 53 54<li>声明应用所需的最低 Android API 55级别</li> 56 57<li>列出应用必须链接到的库</li> 58</ul> 59 60 61<h2 id="filestruct">清单文件结构</h2> 62 63<p> 64下图显示了清单文件的通用结构及其可包含的每个元素。 65每个元素及其所有属性全部记录在一个单独的文件中。 66要查看有关任何元素的详细信息，请点击该图中或其后按字母顺序排列的元素列表中相应的元素名称，或者点击任何其他地方提到的相应元素名称。 67 68 69 70</p> 71 72<pre> 73<?xml version="1.0" encoding="utf-8"?> 74 75<a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a> 76 77 <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission /></a> 78 <a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission /></a> 79 <a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree /></a> 80 <a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group /></a> 81 <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation /></a> 82 <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk /></a> 83 <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration /></a> <!-- ##api level 3## --> 84 <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature /></a> <!-- ##api level 4## --> 85 <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens /></a> <!-- ##api level 4## --> 86 <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html"><compatible-screens /></a> <!-- ##api level 9## --> 87 <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture /></a> <!-- ##api level 11## --> 88 89 <a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> 90 91 <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> 92 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> 93 <a href="{@docRoot}guide/topics/manifest/action-element.html"><action /></a> 94 <a href="{@docRoot}guide/topics/manifest/category-element.html"><category /></a> 95 <a href="{@docRoot}guide/topics/manifest/data-element.html"><data /></a> 96 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 97 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 98 <a href="{@docRoot}guide/topics/manifest/activity-element.html"></activity></a> 99 100 <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a> 101 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 102 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 103 <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"></activity-alias></a> 104 105 <a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a> 106 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 107 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data/></a> 108 <a href="{@docRoot}guide/topics/manifest/service-element.html"></service></a> 109 110 <a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a> 111 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 112 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 113 <a href="{@docRoot}guide/topics/manifest/receiver-element.html"></receiver></a> 114 115 <a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a> 116 <a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission /></a> 117 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 118 <a href="{@docRoot}guide/topics/manifest/path-permission-element.html"><path-permission /></a> 119 <a href="{@docRoot}guide/topics/manifest/provider-element.html"></provider></a> 120 121 <a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library /></a> 122 123 <a href="{@docRoot}guide/topics/manifest/application-element.html"></application></a> 124 125<a href="{@docRoot}guide/topics/manifest/manifest-element.html"></manifest></a> 126</pre> 127 128<p> 129可出现在清单文件中的所有元素按字母顺序罗列如下。 130这些是仅有的合法元素；您无法添加自己的元素或属性。 131 132</p> 133 134<p style="margin-left: 2em"> 135<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> 136<br/><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 137<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> 138<br/><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 139<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code> 140<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> 141<br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> 142<br/><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation></a></code> 143<br/><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 144<br/><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 145<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code> 146<br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 147<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 148<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> 149<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> 150<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> 151<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 152<br/><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> <!-- ##api level 4## --> 153<br/><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code> <!-- ##api level 3## --> 154<br/><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code> <!-- ##api level 4## --> 155<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> 156<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 157<br/><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code> 158</p> 159 160 161 162 163<h2 id="filec">文件约定</h2> 164 165<p> 166有些约定和规则普遍适用于清单文件中的所有元素和属性： 167 168</p> 169 170<dl> 171<dt><b>元素</b></dt> 172<dd>只有 173<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 和 174<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 175元素是必需的，它们都必须存在并且只能出现一次。其他大部分元素可以出现多次或者根本不出现，即便清单文件中必须至少存在其中某些元素才能完成任何有意义的操作也是如此。 176 177 178 179 180<p> 181如果一个元素包含某些内容，也就包含其他元素。所有值均通过属性进行设置，而不是通过元素内的字符数据设置。 182 183</p> 184 185<p> 186同一级别的元素通常不分先后顺序。例如，<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>、<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> 187和 188<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 189元素可以按任何顺序混合在一起。 190（<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> 191元素不适用此规则： 192它必须跟在别名所指的 193<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 194之后。） 195</p></dd> 196 197<dt><b>属性</b></dt> 198<dd>从某种意义上说，所有属性都是可选的。但是，有些属性必须指定给元素以实现其目的。 199请使用本文档作为参考。 200对于真正可选的属性，它将指定默认值或声明缺乏规范时将执行何种操作。 201 202 203<p>除了根 204<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 205元素的一些属性外，所有属性名称均以 {@code android:} 206前缀开头，例如，{@code android:alwaysRetainTaskState}。由于该前缀是通用的，因此在按名称引用属性时，本文档通常会将其忽略。 207 208</p></dd> 209 210<dt><b>声明类名</b></dt> 211<dd>许多元素对应于 212Java 213对象，其中包括应用本身的元素（<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 214元素）及其主要组件 215— 216Activity 217(<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>)、服务 218(<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>)、广播接收器 219(<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>) 220以及内容提供程序 221(<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>)。 222 223<p> 224如果按照您针对组件类（{@link android.app.Activity}、{@link android.app.Service}、{@link android.content.BroadcastReceiver} 225和 226{@link android.content.ContentProvider}）几乎一直采用的方式来定义子类，则该子类需通过 {@code name} 属性来声明。 227该名称必须包含完整的软件包名称。 228例如，{@link android.app.Service} 229子类可能会声明如下： 230</p> 231 232<pre><manifest . . . > 233 <application . . . > 234 <service android:name="com.example.project.SecretService" . . . > 235 . . . 236 </service> 237 . . . 238 </application> 239</manifest></pre> 240 241<p> 242但是，为了简便起见，如果字符串的第一个字符是句点，则字符串将追加到应用的软件包名称（正如 243<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 244元素的 245<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package</a></code> 246属性中所指定）。 247以下赋值与上述方法相同： 248</p> 249 250<pre><manifest package="com.example.project" . . . > 251 <application . . . > 252 <service android:name=".SecretService" . . . > 253 . . . 254 </service> 255 . . . 256 </application> 257</manifest></pre> 258 259<p> 260当启动组件时，Android 会创建已命名子类的实例。如果未指定子类，则会创建基类的实例。 261 262</p></dd> 263 264<dt><b>多个值</b></dt> 265<dd>如果可以指定多个值，则几乎总是在重复此元素，而不是列出单个元素内的多个值。 266例如，Intent 过滤器可以列出多个操作： 267 268 269<pre><intent-filter . . . > 270 <action android:name="android.intent.action.EDIT" /> 271 <action android:name="android.intent.action.INSERT" /> 272 <action android:name="android.intent.action.DELETE" /> 273 . . . 274</intent-filter></pre></dd> 275 276<dt><b>资源值</b></dt> 277<dd>某些属性的值可以显示给用户，例如，Activity 的标签和图标。 278这些属性的值应该本地化，因此需要通过资源或主题进行设置。 279资源值用以下格式表示： 280</p> 281 282<p style="margin-left: 2em">{@code @[<i>package</i>:]<i>type</i>:<i>name</i>}</p> 283 284<p> 285其中，如果资源与应用位于同一软件包中，则可忽略 <i>package</i> 名称； 286 <i>type</i> 是资源类型，如“字串符”或“图片”； 287 <i>name</i> 是标识特定资源的名称。例如： 288 289</p> 290 291<pre><activity android:icon="@drawable/smallPic" . . . ></pre> 292 293<p> 294主题中的值用类似的方法表示，但是以“{@code ?}”开头而不是“{@code @}”： 295 296</p> 297 298<p style="margin-left: 2em">{@code ?[<i>package</i>:]<i>type</i>:<i>name</i>} 299</p></dd> 300 301<dt><b>字串符值</b></dt> 302<dd>如果属性值为字串符，则必须使用双反斜杠（“{@code \\}”） 303转义字符。例如，使用“{@code \\n}”表示换行符或使用“{@code \\uxxxx}”表示 304Unicode 字符）。</dd> 305</dl> 306 307 308<h2 id="filef">文件功能</h2> 309 310<p> 311下文介绍如何在清单文件中利用某些 312Android 特性。 313</p> 314 315 316<h3 id="ifs"> Intent 过滤器</h3> 317 318<p> 319应用的核心组件（其 Activity、服务和广播接收器）由 320 <i>Intent </i>激活。Intent 是一系列用于描述所需操作的信息（{@link android.content.Intent} 321对象），其中包括要执行操作的数据、应执行操作的组件类别以及其他相关说明。 322 323Android 324会找到合适的组件来响应 325 Intent，根据需要启动组件的新实例，并将其传递到 326 Intent 对象。 327</p> 328 329<p> 330组件将通过“Intent 过滤器”公布其功能，即它们可响应的 Intent 类型。 331 <i></i> 由于 332Android 系统在启动某组件之前必须了解该组件可以处理哪些 Intent，因此 Intent 过滤器在清单文件中被指定为 333<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 334元素。 335一个组件可能有任意数量的过滤器，其中每个过滤器描述一种不同的功能。 336 337</p> 338 339<p> 340显式命名目标组件的 341 Intent 将激活该组件；过滤器不起作用。但是，不按名称指定目标的 342 Intent 343只有在能够通过组件的一个过滤器时才可激活该组件。 344</p> 345 346<p> 347有关如何根据 348 Intent 过滤器测试 349 Intent 对象的信息，请参阅单独的文档 350<a href="{@docRoot}guide/components/intents-filters.html"> Intent 和 Intent 过滤器</a>。 351</p> 352 353 354<h3 id="iconlabel">图标和标签</h3> 355 356<p> 357对于可以显示给用户的小图标和文本标签，大量元素具有 {@code icon} 和 {@code label} 358属性。此外，对于同样可以显示在屏幕上的较长说明文本，某些元素还具有 359{@code description} 360属性。例如，<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 361元素具有所有这三个属性。因此，当系统询问用户是否授权给请求获得权限的应用时，权限图标、权限名称以及所需信息的说明均可呈现给用户。 362 363 364 365 366</p> 367 368<p> 369无论何种情况下，在包含元素中设置的图标和标签都将成为所有容器子元素的默认 370{@code icon} 和 {@code label} 设置。因此，在 371<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 372元素中设置的图标和标签是每个应用组件的默认图标和标签。 373同样，为组件（例如，<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 374元素）设置的图标和标签是组件每个 375<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 376元素的默认设置。 377 378如果 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 元素设置标签，但是 Activity 及其 379 Intent 过滤器不执行此操作，则应用标签将被视为 Activity 和 380 Intent 过滤器的标签。 381 382 383</p> 384 385<p> 386在实现 Intent 过滤器公布的功能时，只要向用户呈现组件，系统便会使用为过滤器设置的图标和标签表示该组件。 387 388例如，具有“{@code android.intent.action.MAIN}”和“{@code android.intent.category.LAUNCHER}”设置的过滤器将 Activity 公布为可启动应用的功能，即，公布为应显示在应用启动器中的功能。 389 390 391 392因此，在过滤器中设置的图标和标签就是显示在启动器中的图标和标签。 393 394</p> 395 396 397<h3 id="perms">权限</h3> 398 399<p> 400 <i>权限</i> 是一种限制，用于限制对部分代码或设备上数据的访问。 401 施加限制是为了保护可能被误用以致破坏或损害用户体验的关键数据和代码。 402 403</p> 404 405<p> 406每种权限均由一个唯一的标签标识。标签通常指示受限制的操作。 407例如，以下是由 408Android 定义的一些权限： 409</p> 410 411<p style="margin-left: 2em">{@code android.permission.CALL_EMERGENCY_NUMBERS} 412<br/>{@code android.permission.READ_OWNER_DATA} 413<br/>{@code android.permission.SET_WALLPAPER} 414<br/>{@code android.permission.DEVICE_POWER}</p> 415 416<p> 417一个功能最多只能由一种权限保护。 418</p> 419 420<p> 421如果应用需要访问受权限保护的功能，则必须在清单文件中使用 422<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 423元素声明应用需要该权限。 424但是，将应用安装到设备上之后，安装程序会通过检查签署应用证书的颁发机构并（在某些情况下）询问用户，确定是否授予请求的权限。 425 426 427如果授予权限，则应用能够使用受保护的功能。 428 429否则，其访问这些功能的尝试将会失败，并且不会向用户发送任何通知。 430 431</p> 432 433<p> 434此外，应用也可以使用权限保护自己的组件（Activity、服务、广播接收器和内容提供程序）。 435它可以采用由 436Android 437定义（如 438{@link android.Manifest.permission android.Manifest.permission} 中所列）或由其他应用声明的任何权限。或者，它也可以定义自己的权限。新权限用 439<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 440元素来声明。 441例如，Activity 可受到如下保护： 442</p> 443 444<pre> 445<manifest . . . > 446 <permission android:name="com.example.project.DEBIT_ACCT" . . . /> 447 <uses-permission android:name="com.example.project.DEBIT_ACCT" /> 448 . . . 449 <application . . .> 450 <activity android:name="com.example.project.FreneticActivity" 451 android:permission="com.example.project.DEBIT_ACCT" 452 . . . > 453 . . . 454 </activity> 455 </application> 456</manifest> 457</pre> 458 459<p> 460请注意，在此示例中，{@code DEBIT_ACCT} 461权限不仅是通过 462<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 463元素来声明，而且其使用也是通过 464<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 465元素来请求。要让应用的其他组件也能够启动受保护的 Activity，就必须请求其使用权限，即便保护是由应用本身施加的亦如此。 466 467 468</p> 469 470<p> 471同样还是在此示例中，如果将 472{@code permission} 473属性设置为在其他位置（例如，{@code android.permission.CALL_EMERGENCY_NUMBERS}）声明的权限，则无需使用 474<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 475元素再次声明。 476但是，仍有必要通过 477<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 请求使用它。 478</p> 479 480<p> 481<code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> 482元素为一组将在代码中定义的权限声明命名空间。 483 484同时， 485<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 486为一组权限（包括在清单文件中使用 487<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 488元素声明的权限以及在其他位置声明的权限）定义标签。它只影响如何对提供给用户的权限进行分组。 489<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 490元素并不指定哪些权限属于该组，而只是为组提供名称。 491 492通过向 493<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 494元素的 495<code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup">permissionGroup</a></code> 496属性分配组名，将权限放入组中。 497 498</p> 499 500 501<h3 id="libs">库</h3> 502 503<p> 504每个应用均链接到默认的 Android 库，该库中包括构建应用（以及通用类，如 Activity、服务、 Intent 、视图、按钮、应用、ContentProvider 等）的基本软件包。 505 506 507 508</p> 509 510<p> 511但是，某些软件包驻留在自己的库中。如果应用使用来自其中任一软件包的代码，则必须明确要求其链接到这些软件包。 512 513清单文件必须包含单独的 514<code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> 515元素来命名其中每个库。（库名称可在软件包的文档中找到。） 516 517</p> 518