xref: /frameworks/base/docs/html-intl/intl/zh-cn/preview/features/runtime-permissions.jd

page.title=权限
page.tags=previewresources, androidm
page.keywords=permissions, runtime, preview
page.image={@docRoot}preview/features/images/permissions_check.png
@jd:body


<div id="qv-wrapper">
  <div id="qv">
    <h2>内容快览</h2>
    <ul>
      <li>如果您的应用主要面向 M 预览版 SDK，则会在运行时（而非安装时）提示用户授予权限。
</li>
      <li>用户可以随时从应用“设置”屏幕撤销权限。
</li>
      <li>每次运行时，应用均需检查自身是否具备所需的权限。
</li>
    </ul>

    <h2>本文内容</h2>
    <ol>
      <li><a href="#overview">概览</a></li>
      <li><a href="#coding">为运行时权限编码</a></li>
      <li><a href="#testing">测试运行时权限</a></li>
      <li><a href="#best-practices">最佳做法</a></li>
    </ol>

<!--
  <h2>Related Samples</h2>
  <ol>
    <li></li>
  </ol>
-->

<!--
  <h2>See also</h2>
  <ol>
    <li></li>
  </ol>
-->
  </div> <!-- qv -->
</div> <!-- qv-wrapper -->


<p>
  M 开发者预览版引入了一种新的应用权限模型，旨在简化用户安装和升级应用的过程。
如果在 M 预览版上运行的应用支持新权限模型，则用户无需在安装或升级应用时授予任何权限。相反，应用会根据需要请求权限，且系统将向用户显示一个请求权限的对话框。




</p>

<p>
  如果应用支持新权限模型，则仍可在运行旧版 Android 的设备上使用旧权限模型安装并运行此应用。


</p>

<h2 id="overview">
  概览
</h2>

<p>
  通过 M 开发者预览版，该平台引入了新的应用权限模型。
以下概述了此新模型的主要组件：
</p>

<ul>
  <li>
    <strong>声明权限：</strong>应用使用清单文件声明其所需的所有权限，就像在早期的 Android 平台中一样。

  </li>

  <li>
    <strong>权限组：</strong>权限根据相应的功能分为若干
<em>权限组</em>。例如，
<code>CONTACTS</code> 权限组包含读取和写入用户联系人和个人资料信息的权限。

  </li>

  <li>
    <p><strong>安装时授予的有限权限：</strong>当用户安装或更新应用时，系统将授予应用所请求的属于 {@link
    android.content.pm.PermissionInfo#PROTECTION_NORMAL PROTECTION_NORMAL} 的所有权限。


    例如，闹铃和 Internet 权限属于 {@link
    android.content.pm.PermissionInfo#PROTECTION_NORMAL PROTECTION_NORMAL}，因此系统将在安装应用时自动授予这些权限。

    </p>

    <p>此外，系统还可以授予应用签名和系统权限，如<a href="#system-apps">系统应用和签名权限</a>中所述。

系统不会在安装应用时提示用户授予任何权限。<em></em>
</p>
  </li>

  <li>
    <strong>用户在运行时授予权限：</strong>当应用请求权限时，系统将向用户显示一个对话框，然后调用应用的回调函数来通知它是否已授予权限。

如果用户授予某项权限，则应用将获得应用清单文件中声明的、该权限功能区域中的所有权限。


  </li>

</ul>

<p>
  对于需要权限的功能，此权限模型将改变应用的行为方式。
以下概述了您调整此模型时所应遵循的开发实践：

</p>

<ul>

  <li>
    <strong>始终检查权限：</strong>当应用必须执行任何需要权限的操作时，应先检查它是否已具备该权限。

如果没有，则请求授予该权限。

  </li>

  <li>
    <strong>妥善处理权限不足的情况：</strong>如果应用未被授予适当的权限，则应正常处理失败情况。

    例如，如果只有新增的功能需要该权限，则应用可以禁用该功能。
如果该权限对于应用正常运行至关重要，则应用可能会禁用其所有功能，并通知用户需要授予该权限。


  </li>

  <div class="figure" style="width:220px" id="fig-perms-screen">
    <img src="{@docRoot}preview/features/images/app-permissions-screen_2x.png" srcset="{@docRoot}preview/features/images/app-permissions-screen.png 1x, {@docRoot}preview/features/images/app-permissions-screen_2x.png 2x" alt="" width="220">
    <p class="img-caption">
      <strong>图 1.</strong>应用“设置”中的“权限”屏幕。
    </p>
  </div>

  <li>
    <strong>权限可撤销：</strong>用户可以随时撤销应用的权限。
即使用户禁用应用的权限，应用也不会收到通知。<em></em>
再次强调：您的应用应在执行任何受限操作之前验证是否具备所需的权限。

  </li>
</ul>

<p class="note">
  <strong>注：</strong>如果应用主要面向 M 开发者预览版，则必须使用新权限模型。
<em></em>
</p>

<p>
  截至 M 开发者预览版发布，并非所有 Google 应用均已完全实现新权限模型。
Google 会在 M 开发者预览版运行期间更新这些应用，以便严格遵守权限切换设置。


</p>

<p class="note">
  <strong>注：</strong>如果您的应用拥有自己的 API 接口，请先确保调用方具备访问该数据所需的必要权限，然后再代理权限。


</p>

<h3 id="system-apps">
  系统应用和签名权限
</h3>

<p>
  通常，当用户安装应用时，系统仅授予应用
 {@link android.content.pm.PermissionInfo#PROTECTION_NORMAL
  PROTECTION_NORMAL}。但在某些情况下，系统将授予应用更多权限：

</p>

<ul>
  <li>如果应用是系统映像的一部分，则系统会自动授予该应用清单文件中列出的所有权限。

  </li>

  <li>如果应用请求提供清单文件中属于 {@link
  android.content.pm.PermissionInfo#PROTECTION_SIGNATURE PROTECTION_SIGNATURE} 的权限，且该应用已使用与声明这些权限的应用相同的证书进行签名，则系统将在安装请求权限的应用时向其授予这些权限。



  </li>
</ul>

<p>
  在这两种情况下，用户仍可随时撤销权限，具体方法是：转到系统的<strong>设置</strong>屏幕，然后选择<strong>应用 &gt;</strong>

 <i>应用名称</i> <strong>&gt; 权限</strong>。应用应在运行时继续检查权限，并根据需要请求权限。


</p>

<h3 id="compatibility">
  前后兼容性
</h3>

<p>
  如果应用并非面向 M 开发者预览版，则即使是在 M 预览版设备上，该应用也会继续使用旧权限模型。
当用户安装应用时，系统将要求用户授予应用清单文件中列出的所有权限。


</p>

<p class="note">
  <strong>注：</strong>在运行 M 开发者预览版的设备上，用户可以从应用的“设置”屏幕禁用任何应用（包括旧版应用）的权限。

如果用户禁用某旧版应用的权限，则系统将以静默方式禁用相应的功能。
当应用尝试执行需要该权限的操作时，该操作不一定会导致出现异常。

相反，它可能会返回空数据集、报告错误或以其他方式表现出异常行为。
例如，如果您未经许可查询日历，则该方法会返回空数据集。

</p>

<p>
  如果您在未运行 M 预览版的设备上使用新权限模型安装应用，则系统将采用与其他任何应用相同的方式处理：系统会在安装应用时要求用户授予声明的所有权限。



</p>

<p class="note">
  <strong>注：</strong>对于预览版本，您必须将最低 SDK 版本设置为 M 预览版 SDK，才可使用预览版 SDK 进行编译。
这意味着在开发者预览版运行期间，您无法在旧版平台上测试此类应用。


</p>

<h3 id="perms-vs-intents">权限与意向的比较</h3>

<p>
  许多情况下，您可以使用以下两种方式之一来让您的应用执行某项任务。
您可以将应用设置为请求执行操作本身所需的权限。
或者，您可以将应用设置为通过传送意向，让其他应用来执行任务。

</p>

<p>
  例如，假设应用需要能够使用设备相机拍摄照片。
应用可以请求
<code>android.permission.CAMERA</code> 权限，以便允许其直接访问相机。
然后，应用将使用 Camera API 控制相机并拍摄照片。
利用此方法，您的应用能够完全控制摄影过程，并支持您将相机 UI 合并至应用中。


</p>

<p>
  但是，如果您无需此类控制，则可仅使用 {@link
  android.provider.MediaStore#ACTION_IMAGE_CAPTURE ACTION_IMAGE_CAPTURE} 意向来请求图像。
启动该意向时，系统会提示用户选择相机应用（如果没有默认相机应用），然后该应用将拍摄照片。

该相机应用会将照片返回给应用的 {@link
  android.app.Activity#onActivityResult onActivityResult()} 方法。
</p>

<p>
  同样，如果您需要打电话、访问用户的联系人或要执行其他操作，则可通过创建适当的意向来完成，或者您可以请求相应的权限并直接访问相应的对象。

每种方法各有优缺点。

</p>

<p>
  如果使用权限：
</p>

<ul>
  <li>应用可在您执行操作时完全控制用户体验。
但是，如此广泛的控制会增加任务的复杂性，因为您需要设计适当的 UI。

  </li>

  <li>当您首次执行操作时，系统会显示一次让用户授予权限的提示。
之后，应用即可执行操作，不再需要用户进行其他交互。
但是，如果用户不授予权限（或稍后撤销权限），则应用根本无法执行操作。


  </li>
</ul>

<p>
  如果使用意向：
</p>

<ul>
  <li>您无需为操作设计 UI。处理意向的应用将提供 UI。不过这意味着您无法控制用户体验。

用户可以与您从未见过的应用进行交互。

  </li>

  <li>如果用户没有适用于操作的默认应用，则系统会提示用户选择应用。如果用户未指定默认处理程序，则必须在每次执行此操作时额外处理一个对话框。



  </li>
</ul>

<h2 id="coding">为运行时权限编码</h2>

<p>
  如果应用主要面向新的 M 开发者预览版，则您必须使用新权限模型。
这意味着除了通过清单文件声明所需的权限以外，您还必须检查应用运行时是否已有相应的权限，如果没有，则需要请求权限。



</p>

<h3 id="enabling">
  启用新权限模型
</h3>

<p>
  要启用新的 M 开发者预览版权限模型，请将应用的
<code>targetSdkVersion</code> 属性设置为 <code>"MNC"</code>，并将
<code>compileSdkVersion</code> 设置为 <code>"android-MNC"</code>。这样可启用所有新的权限功能。

</p>

<p>
  对于预览版本，您必须将 <code>minSdkVersion</code> 设置为
<code>"MNC"</code>，才能使用预览版 SDK 进行编译。
</p>

<h3 id="m-only-perm">
  指定仅用于 M 预览版的权限
</h3>

<p>
  您可以使用应用清单文件中的新 <code>&lt;uses-permission-sdk-m&gt;</code> 元素指明仅在 M 开发者预览版中需要某权限。
如果您以这种方式声明权限，则每当在旧版设备上安装应用时，系统都不会提示用户或向应用授予权限。通过使用 <code>&lt;uses-permission-sdk-m&gt;</code>
 元素，您可以将新权限添加到更新后的应用版本，而不必强制用户在安装更新时授予权限。





</p>

<p>
  如果应用在已安装 M 开发者预览版的设备上运行，则
<code>&lt;uses-permission-sdk-m&gt;</code> 的行为与
<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code> 相同。
  系统不会在安装应用时提示用户授予任何权限，且应用将根据需要请求权限。

</p>

<h3 id="prompting">
  提示授予权限
</h3>

<p>
  如果应用使用新的 M 开发者预览版权限模型，则在运行 M 预览版的设备上首次启动应用时，系统不会要求用户授予所有权限。

相反，应用将根据需要请求权限。
当应用请求某权限时，系统会向用户显示一个对话框。

</p>

<p>
  如果应用在已安装 SDK 22 或更低版本的设备上运行，则应用将使用旧权限模型。
当用户安装应用时，系统将提示他们授予应用在清单文件中请求的所有权限，但那些带有 <code>&lt;uses-permission-sdk-m&gt;</code> 标记的权限除外。


</p>

<h4 id="check-platform">检查运行应用的平台</h4>

<p>
  只有运行 M 开发者预览版的设备支持此权限模型。
在调用其中任何方法之前，应用均应通过检查 {@link android.os.Build.VERSION#CODENAME
  Build.VERSION.CODENAME} 的值来验证运行应用的平台。

如果设备正在运行 M 开发者预览版，则
{@link android.os.Build.VERSION#CODENAME CODENAME} 为 <code>"MNC"</code>。
</p>

<h4 id="check-for-permission">检查应用是否具备所需的权限</h4>

<p>当用户尝试执行需要权限的操作时，应用将检查目前是否具备执行此操作所需的权限。
为此，应用将调用
<code>Context.checkSelfPermission(
<i>permission_name</i>)</code>。即便知道用户已授予该权限，应用也应执行此检查，因为用户可以随时撤销应用的权限。


例如，如果用户需要使用应用拍摄照片，则应用将调用
<code>Context.checkSelfPermission(Manifest.permission.CAMERA)</code>。
</p>

<p class="table-caption" id="permission-groups">
  <strong>表 1.</strong>权限和权限组。</p>
<table>
  <tr>
    <th scope="col">权限组</th>
    <th scope="col">权限</th>
  </tr>

  <tr>
    <td><code>android.permission-group.CALENDAR</code></td>
    <td>
      <ul>
        <li>
          <code>android.permission.READ_CALENDAR</code>
        </li>
      </ul>
      <ul>
        <li>
          <code>android.permission.WRITE_CALENDAR</code>
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td><code>android.permission-group.CAMERA</code></td>
    <td>
      <ul>
        <li>
          <code>android.permission.CAMERA</code>
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td><code>android.permission-group.CONTACTS</code></td>
    <td>
      <ul>
        <li>
          <code>android.permission.READ_CONTACTS</code>
        </li>
        <li>
          <code>android.permission.WRITE_CONTACTS</code>
        </li>
        <li>
          <code>android.permission.READ_PROFILE</code>
        </li>
        <li>
          <code>android.permission.WRITE_PROFILE</code>
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td><code>android.permission-group.LOCATION</code></td>
    <td>
      <ul>
        <li>
          <code>android.permission.ACCESS_FINE_LOCATION</code>
        </li>
        <li>
          <code>android.permission.ACCESS_COARSE_LOCATION</code>
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td><code>android.permission-group.MICROPHONE</code></td>
    <td>
      <ul>
        <li>
          <code>android.permission.RECORD_AUDIO</code>
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td><code>android.permission-group.PHONE</code></td>
    <td>
      <ul>
        <li>
          <code>android.permission.READ_PHONE_STATE</code>
        </li>
        <li>
          <code>android.permission.CALL_PHONE</code>
        </li>
        <li>
          <code>android.permission.READ_CALL_LOG</code>
        </li>
        <li>
          <code>android.permission.WRITE_CALL_LOG</code>
        </li>
        <li>
          <code>com.android.voicemail.permission.ADD_VOICEMAIL</code>
        </li>
        <li>
          <code>android.permission.USE_SIP</code>
        </li>
        <li>
          <code>android.permission.PROCESS_OUTGOING_CALLS</code>
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td><code>android.permission-group.SENSORS</code></td>
    <td>
      <ul>
        <li>
          <code>android.permission.BODY_SENSORS</code>
        </li>
      </ul>
      <ul>
        <li>
          <code>android.permission.USE_FINGERPRINT</code>
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td><code>android.permission-group.SMS</code></td>
    <td>
      <ul>
        <li>
          <code>android.permission.SEND_SMS</code>
        </li>
        <li>
          <code>android.permission.RECEIVE_SMS</code>
        </li>
        <li>
          <code>android.permission.READ_SMS</code>
        </li>
        <li>
          <code>android.permission.RECEIVE_WAP_PUSH</code>
        </li>
        <li>
          <code>android.permission.RECEIVE_MMS</code>
        </li>
        <li>
          <code>android.permission.READ_CELL_BROADCASTS</code>
        </li>
      </ul>
    </td>
  </tr>

</table>

<h4 id="request-permissions">根据需要请求权限</h4>

<p>如果应用尚无所需的权限，则应用将调用
<code>Activity.requestPermissions(String[], int)</code> 方法，请求提供一项或多项适当的权限。
应用将传递所需的一项或多项权限，以及整数“请求代码”。

  此方法异步运行：它会立即返回，并且在用户响应对话框之后，系统会使用结果调用应用的回调方法，将应用传递的相同“请求代码”传递到 <code>requestPermissions()</code>。


</p>

  <p>以下代码检查应用是否具备读取用户联系人所需的权限，并根据需要请求该权限：
</p>

<pre>
if (checkSelfPermission(Manifest.permission.READ_CONTACTS)
        != PackageManager.PERMISSION_GRANTED) {
    requestPermissions(new String[]{Manifest.permission.READ_CONTACTS},
            MY_PERMISSIONS_REQUEST_READ_CONTACTS);

    // MY_PERMISSIONS_REQUEST_READ_CONTACTS is an
    // app-defined int constant

    return;
}
</pre>

<h4 id="handle-response">处理权限请求响应</h4>

<p>
  当应用请求权限时，系统将向用户显示一个对话框。
当用户响应时，系统将调用应用的
<code>Activity.onRequestPermissionsResult(int, String[], int[])</code>
，向其传递用户响应。应用需要替代该方法。回调会将您传递的相同请求代码传递给
<code>requestPermissions()</code>。
例如，如果应用请求
<code>READ_CONTACTS</code> 访问权限，则可能采用以下回调方法：

</p>

<pre>
&#64;Override
public void onRequestPermissionsResult(int requestCode,
        String permissions[], int[] grantResults) {
    switch (requestCode) {
        case MY_PERMISSIONS_REQUEST_READ_CONTACTS: {
            if (grantResults[0] == PackageManager.PERMISSION_GRANTED) {

                // permission was granted, yay! do the
                // calendar task you need to do.

            } else {

                // permission denied, boo! Disable the
                // functionality that depends on this permission.
            }
            return;
        }

        // other 'switch' lines to check for other
        // permissions this app might request
    }
}
</pre>

  <p>如果用户授予权限，则系统会为应用授予应用清单文件为该功能区域列出的所有权限。
如果用户拒绝请求，则您应采取适当的操作。
例如，您可以禁用任何取决于此权限的菜单操作。

  </li>
</p>

<p>
  当系统要求用户授予权限时，用户可以选择指示系统不再要求提供该权限。
在这种情况下，当应用使用 <code>requestPermissions()</code> 请求该权限时，系统会立即拒绝此请求。

在这种情况下，如果用户已再次明确拒绝您的请求，则系统会以同样的方式调用您的 <code>onRequestPermissionsResult()</code>。

因此，您的应用不能假设用户采取了任何直接交互行为。

</p>

<h2 id="testing">测试运行时权限</h2>


<p>
  如果应用主要面向 M 开发者预览版，则您必须测试它是否正确处理权限。
您不能假设应用在运行时具备任何特定的权限。
应用首次启动时，它可能没有任何权限，且用户可以随时撤销或恢复权限。


</p>

<p>
  您应测试应用，确保它在所有权限情况下均可正常运行。
通过 M 预览版 SDK，我们提供了新的
<a href="{@docRoot}tools/help/adb.html">Android
  Debug Bridge (adb)</a> 命令，支持您使用需要尝试的任何权限设置测试应用。

</p>

<h3>
  新 adb 命令和选项
</h3>

<p>
  M 预览版 SDK 平台工具提供了多个新命令，支持您测试应用处理权限的方式。

</p>

<h4>
  使用权限安装
</h4>

<p>
  您可以使用 <a href="{@docRoot}tools/help/adb.html#move"><code>adb
  install</code></a> 命令的新 <code>-g</code> 选项，该选项将安装应用并授予其清单文件中列出的所有权限：

</p>

<pre class="no-pretty-print">
$ adb install -g &lt;path_to_apk&gt;
</pre>

<h4>
  授予和撤销权限
</h4>

<p>
  您可以使用新的 ADB <a href="{@docRoot}tools/help/adb.html#pm">软件包管理器 (pm)</a> 命令向已安装的应用授予权限和撤销其权限。此功能对于自动化测试非常有用。


</p>

<p>
  要授予权限，请使用软件包管理器的 <code>grant</code> 命令：
</p>

<pre class="no-pretty-print">
$ adb pm grant &lt;package_name&gt; &lt;permission_name&gt;
</pre>

<p>
  例如，要向录音​​授予 com.example.myapp 软件包权限，请使用以下命令：

</p>

<pre class="no-pretty-print">
$ adb pm grant com.example.myapp android.permission.RECORD_AUDIO
</pre>

<p>
  要撤销权限，请使用软件包管理器的 <code>revoke</code> 命令：
</p>

<pre class="no-pretty-print">
$ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
</pre>

<h2 id="best-practices">最佳做法</h2>

<p>
  新权限模型为用户带来更流畅的体验，让他们能够更轻松地安装应用，并得心应手地使用应用的各项功能。

为了充分利用该新模型，我们建议采用下列最佳做法。

</p>


<h3 id="bp-what-you-need">仅请求自己所需的权限</h3>

<p>
  每次您请求权限时，实际上是在强迫用户作出决定。
  如果用户拒绝请求，则会减少应用的功能。
  您应尽量减少提出这些请求的次数。
</p>

<p>
  例如，应用往往可以通过使用
<a href="{@docRoot}guide/components/intents-filters.html">意向</a>（而不是请求权限）获得所需的功能。
如果应用需要使用手机的相机拍摄照片，则可使用
 {@link
  android.provider.MediaStore#ACTION_IMAGE_CAPTURE
  MediaStore.ACTION_IMAGE_CAPTURE} 意向。当应用执行该意向时，系统会提示用户选择已安装的相机应用拍摄照片。


</p>

<h3 id="bp-dont-overwhelm">
  不要让用户感到无所适从
</h3>

<p>
  如果您让用户一次面对大量权限请求，用户可能会感到无所适从并因此退出应用。替代做法是，您应根据需要请求权限。


</p>

<p>
  某些情况下，您的应用可能绝对需要一项或多项权限。在这种情况下，合理的做法是，在应用启动之后立即请求所有权限。

例如，如果您运行摄影应用，则该应用需要访问设备的相机。
当用户首次启动该应用时，不会对请求使用相机所需的权限感到惊讶。

但是，如果同一应用还具备与用户联系人共享照片的功能，则您不应在首次启动时请求用户提供该权限，<em></em>

而是等到用户尝试使用“共享”功能之后，再请求该权限。

</p>

<p>
  如果应用提供了教程，则合理的做法是，在教程结束时请求提供应用的必要权限。

</p>

<h3 id="bp-explain">
  解释需要权限的原因
</h3>

<p>
  系统在您调用
<code>requestPermissions()</code> 时显示的权限对话框将说明应用所需的权限，但不会解释为何需要这些权限。
在某些情况下，用户可能会感到困惑。
  最好在调用 <code>requestPermissions()</code> 之前向用户解释应用需要权限的原因。

</p>

<p>
  例如，摄影应用可能需要使用位置服务，以便能够为照片添加地理标签。
通常，用户可能不了解照片能够包含位置信息，并且对摄影应用想要了解具体位置感到不解。

因此在这种情况下，应用最好在调用
<code>requestPermissions()</code> 之前告知此功能的相关信息。<em></em>

</p>

<p>
  其中一种办法是将这些请求纳入应用教程。这样，教程可以依次显示应用的每项功能，并在显示每项功能时解释需要哪些相应的权限。

例如，摄影应用的教程可以演示其“与您的联系人共享照片”功能，然后告知用户需要为应用授予权限以便其查看用户的联系人。


然后，应用可以调用 <code>requestPermissions()</code>，要求用户提供该访问权限。
当然，并非所有用户都会按照教程操作，因此您仍需在应用的正常操作期间检查和请求权限。


</p>