initial commit

2 files changed, 219 insertions, 0 deletions

diff --git a/files/zh-cn/web/api/permissions_api/index.html b/files/zh-cn/web/api/permissions_api/index.html
new file mode 100644
index 0000000000..5c14434f15
--- /dev/null
+++ b/files/zh-cn/web/api/permissions_api/index.html
@@ -0,0 +1,94 @@
+---
+title: Permissions API
+slug: Web/API/Permissions_API
+tags:
+  - API
+  - Introduction
+  - NeedsTranslation
+  - Overview
+  - Permissions
+  - Permissions API
+  - TopicStub
+  - Web
+  - access
+translation_of: Web/API/Permissions_API
+---
+<p>{{DefaultAPISidebar("Permissions API")}}</p>
+
+<div class="summary">
+<p><span class="seoSummary">The <strong>Permissions API</strong> provides a consistent programmatic way to query the status of API permissions attributed to the current context. For example, the Permissions API can be used to determine if permission to access a particular API has been granted or denied.</span></p>
+</div>
+
+<h2 id="Concepts_and_usage">Concepts and usage</h2>
+
+<p>Historically different APIs handle their own permissions inconsistently — for example the <a href="/en-US/docs/Web/API/Notifications_API">Notifications API</a> allows for explicit checking of permission status and requesting permission, whereas the <a href="/en-US/docs/Web/API/Geolocation">Geolocation API</a> doesn't (which causes problems if the user denied the initial permission request). The Permissions API provides the tools to allow developers to implement a better user experience as far as permissions are concerned.</p>
+
+<p>The <code>permissions</code> property has been made available on the {{domxref("Navigator")}} object, both in the standard browsing context and the worker context ({{domxref("WorkerNavigator")}} — so permission checks are available inside workers), and returns a {{domxref("Permissions")}} object that provides access to the Permissions API functionality.</p>
+
+<p>Once you have this object you can then perform permission-related tasks, for example querying a permission using the {{domxref("Permissions.query()")}} method to return a promise that resolves with the {{domxref("PermissionStatus")}} for a specific API.</p>
+
+<p>Not all APIs' permission statuses can be queried using the Permissions API. Notable APIs that are Permissions-aware include:</p>
+
+<ul>
+ <li><a href="/en-US/docs/Web/API/Clipboard_API">Clipboard API</a></li>
+ <li><a href="/en-US/docs/Web/API/Notifications_API">Notifications API</a></li>
+ <li><a href="/en-US/docs/Web/API/Push_API">Push API</a></li>
+ <li>Web MIDI API</li>
+</ul>
+
+<p>More APIs will gain Permissions API support over time.</p>
+
+<h2 id="Examples">Examples</h2>
+
+<p>We have made a simple example available called Location Finder. You can <a href="https://chrisdavidmills.github.io/location-finder-permissions-api/">run the example live</a>, or <a href="https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages">view the source code on Github</a>.</p>
+
+<p>Read more about how it works in our article <a href="/en-US/docs/Web/API/Permissions_API/Using_the_Permissions_API">Using the Permissions API</a>.</p>
+
+<h2 id="Interfaces">Interfaces</h2>
+
+<dl>
+ <dt>{{domxref("Navigator.permissions")}} and {{domxref("WorkerNavigator.permissions")}} {{readonlyinline}}</dt>
+ <dd>Provides access to the {{domxref("Permissions")}} object from the main context and worker context respectively.</dd>
+ <dt>{{domxref("Permissions")}}</dt>
+ <dd>Provides the core Permission API functionality, such as methods for querying and revoking permissions.</dd>
+ <dt>{{domxref("PermissionStatus")}}</dt>
+ <dd>Provides access to the current status of a permission, and an event handler to respond to changes in permission status.</dd>
+</dl>
+
+<h2 id="Specification">Specification</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Specification</th>
+   <th scope="col">Status</th>
+   <th scope="col">Comment</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('Permissions API')}}</td>
+   <td>{{Spec2('Permissions API')}}</td>
+   <td>Initial definition.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div>
+<h3 id="Permissions_interface">Permissions interface</h3>
+
+<div>
+
+
+<p>{{Compat("api.Permissions")}}</p>
+</div>
+</div>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+ <li><a href="/en-US/docs/Web/API/Permissions_API/Using_the_Permissions_API">Using the Permissions API</a></li>
+ <li><a href="https://blog.addpipe.com/using-permissions-api-to-detect-getusermedia-responses/">Using the Permissions API to Detect How Often Users Allow or Deny Camera Access</a></li>
+ <li>{{DOMxRef("Notification.permission")}}</li>
+ <li><a href="/en-US/docs/Web/Privacy">Privacy, permissions, and information security</a></li>
+</ul>
diff --git a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.html b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.html
new file mode 100644
index 0000000000..e437742dbc
--- /dev/null
+++ b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.html
@@ -0,0 +1,125 @@
+---
+title: Using the Permissions API
+slug: Web/API/Permissions_API/Using_the_Permissions_API
+tags:
+  - API
+  - Geolocation
+  - 实现性的
+  - 指南
+  - 权限
+translation_of: Web/API/Permissions_API/Using_the_Permissions_API
+---
+<p>{{DefaultAPISidebar("Permissions API")}}{{SeeCompatTable}}</p>
+
+<p class="summary">本文提供了使用 W3C Permission API 的基本说明，它提供了一种程序上的方式来查询当前上下文的 API 权限授权状态。</p>
+
+<h2 id="申请权限面临的困境...">申请权限面临的困境...</h2>
+
+<p>惨淡的事实是，权限在 Web 开发中是令人厌恶却不得不面对的问题，对于开发者而言，处理它毫无乐趣。</p>
+
+<p>由于历史原因，不同的 API 使用各自不同的方式来处理自己的权限──例如，Notification API 允许显式地检查权限状态和申请权限，然而，Geolocation API 却不能（如果用户拒绝了首次权限请求，就会造成我们下面将要看到的问题）。</p>
+
+<p><a href="/en-US/docs/Web/API/Permissions_API">Permissions API</a> 提供了一系列工具来让开发者在权限方面实现更好的用户体验。例如，它提供了特定的 API 来查询某个权限被授予了还是被拒绝了，以及可以使用 API 来申请特定的权限。</p>
+
+<p>目前来说，该 API 的实现还在早期阶段，所以浏览器支持也是参差不齐：</p>
+
+<ul>
+ <li>只在 Chrome 44 以上版本及 Firefox 43 以上版本实现了。</li>
+ <li>当下仅支持 {{domxref("Permissions.query()")}} 方法，它用来查询权限。</li>
+ <li>Chrome 中目前可以被 Permission API 识别的权限仅有 <a href="/en-US/docs/Web/API/Geolocation">Geolocation</a> 和 Notification, 对于 Firefox 来说，还支持 <a href="/en-US/docs/Web/API/Push_API">Push</a> and WebMIDI.</li>
+</ul>
+
+<p>更多特性将逐步实现。</p>
+
+<h2 id="一个简单的例子">一个简单的例子</h2>
+
+<p>在本文中，我们有一个简单的 demo 叫作 Location Finder. 它使用 Geolocation 获取用户的当前位置，并标注在 Google 地图上：</p>
+
+<p><img alt="Screenshot showing a map of Greenfield, UK." src="https://mdn.mozillademos.org/files/11501/location-finder-with-permissions-api.png" style="display: block; height: 428px; margin: 0px auto; width: 700px;"></p>
+
+<p>You can <a href="https://chrisdavidmills.github.io/location-finder-permissions-api/">在线运行</a>， 或 <a href="https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages">在 Github 查看源码</a>。 大部分代码都很简单且常见──所以接下来我们会重点关注和 Permission API 有关的代码，如果你想学习其他部分，请自行阅读。</p>
+
+<h3 id="访问_Permissions_API">访问 Permissions API</h3>
+
+<p>浏览器现已包含 {{domxref("Navigator.permissions")}} 属性使开发者可以访问全局的 {{domxref("Permissions")}} 对象。这个对象最终将包含用来查询、申请和重置权限的方法，尽管，目前只有 {{domxref("Permissions.query()")}}; 我们接下来会讨论它。</p>
+
+<h3 id="查询权限状态">查询权限状态</h3>
+
+<p>在我们的例子中，权限功能使用一个函数来处理— <code>handlePermission()</code>. 它开始于使用 {{domxref("Permissions.query()")}} 查询权限状态。根据 Promise resolve 后返回的 {{domxref("PermissionStatus")}} 对象的 {{domxref("PermissionStatus.state", "state")}} 属性，做出不同的处理：</p>
+
+<dl>
+ <dt><code>"granted"</code></dt>
+ <dd>"Enable Geolocation" 按钮被隐藏掉了，因为 Geolocation 已经被允许了，不需要这个按钮了。</dd>
+ <dt><code>"prompt"</code></dt>
+ <dd>隐藏 "Enable Geolocation" 按钮，因为用户会被（浏览器）引导授权 Geolocation 权限，所以它不需要了。接下来 {{domxref("Geolocation.getCurrentPosition()")}} 函数会运行，它会引导用户授权；如果用户授权了，它会继续执行 <code>revealPosition()</code> 函数（会显示地图）；如果用户拒绝了， <code>positionDenied()</code> 函数会被执行（这会让 "Enable Geolocation" 按钮显示出来）。</dd>
+ <dt><code>"denied"</code></dt>
+ <dd>"Enable Geolocation" 按钮会被显示（这段代码也需要放在这里，以防在页面首次加载时，这个源的权限状态就已经被设置为拒绝了）。</dd>
+</dl>
+
+<pre class="brush: js notranslate">function handlePermission() {
+  navigator.permissions.query({name:'geolocation'}).then(function(result) {
+    if (result.state == 'granted') {
+      report(result.state);
+      geoBtn.style.display = 'none';
+    } else if (result.state == 'prompt') {
+      report(result.state);
+      geoBtn.style.display = 'none';
+      navigator.geolocation.getCurrentPosition(revealPosition,positionDenied,geoSettings);
+    } else if (result.state == 'denied') {
+      report(result.state);
+      geoBtn.style.display = 'inline';
+    }
+    result.onchange = function() {
+      report(result.state);
+    }
+  });
+}
+
+function report(state) {
+  console.log('Permission ' + state);
+}
+
+handlePermission();</pre>
+
+<h3 id="权限描述符">权限描述符</h3>
+
+<p>{{domxref("Permissions.query()")}} 方法接受一个 <code>PermissionDescriptor</code> 字典作为参数 — 它包含你感兴趣的 API 的名称。一些 API 有继承自默认的 <code>PermissionDescriptor</code>  的更加复杂的 <code>PermissionDescriptor</code>s 以包含更多额外的信息。例如，<code>PushPermissionDescriptor</code> 也包含一个比尔值指定 <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe#Parameters">userVisibleOnly</a></code> 是 <code>true</code> 还是 <code>false</code>.</p>
+
+<h3 id="重置权限">重置权限</h3>
+
+<p>从 Firefox 47 开始，你可以使用 {{domxref("Permissions.revoke()")}}  方法重置现有权限。它的调用方式和 {{domxref("Permissions.query()")}} 方法几乎一模一样，区别是，当 promise 成功 resolve 时，它会让一个现有的权限恢复默认状态（通常是 <code>prompt</code>）。让我们看看 demo 中的代码：</p>
+
+<pre class="brush: js notranslate">var revokeBtn = document.querySelector('.revoke');
+
+  ...
+
+revokeBtn.onclick = function() {
+  revokePermission();
+}
+
+  ...
+
+function revokePermission() {
+  navigator.permissions.revoke({name:'geolocation'}).then(function(result) {
+    report(result.state);
+  });
+}</pre>
+
+<div class="note">
+<p>自 Firefox 51 开始 <code>revoke()</code> 函数被默认关闭了，因为它的设计带来了 <a href="https://www.w3.org/2011/webappsec/">Web Applications Security Working Group</a> 中提到的问题。可以通过将设置项  <code>dom.permissions.revoke.enable</code> 置为 <code>true</code> 来重新开启它。</p>
+</div>
+
+<h3 id="响应权限状态变化">响应权限状态变化</h3>
+
+<p>你会注意到，在上面的代码中，在 {{domxref("PermissionStatus")}} 对象上有一个 <code>onchange</code> 事件回调 — 这让我们可以对感兴趣的 API 的状态变化做出响应。目前，我们只是上报了状态的变化。</p>
+
+<h2 id="总结和展望未来">总结和展望未来</h2>
+
+<p>目前，较之我们已有的，这个 API 并没有提供太多额外内容。如果在浏览器询问时，我们选择了从不分享我们的位置，那么不使用浏览器菜单选项的话，我们将无法返回权限的初始状态（询问）：</p>
+
+<ul>
+ <li><strong>Firefox</strong>: <em>工具 &gt; 页面信息 &gt; 权限 &gt; 访问你的位置</em>。选择“总是询问”。</li>
+ <li><strong>Chrome</strong>: <em>汉堡菜单 &gt; 设置 &gt; 显示高级设置。在隐私部分，点击“内容设置”。在出现的对话框中，找到 “位置” 部分，选择“当网站试图访问时询问”...最后，点击“管理特例”</em>，移除你对特定网站的授权。</li>
+</ul>
+
+<p>但是，未来浏览器会提供 <code>request()</code> 方法，他让我们可以在任何时候以编程的方式来请求权限。这非常值得期待尽快被实现。</p>