From a203e103fb62c3f2bd041e6b83f3235405c38f9e Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Mon, 9 Sep 2024 13:23:14 +0800 Subject: [PATCH 1/7] sync --- files/zh-cn/web/api/permissions/index.md | 6 +-- .../zh-cn/web/api/permissions/query/index.md | 2 +- .../zh-cn/web/api/permissions/revoke/index.md | 6 ++- files/zh-cn/web/api/permissions_api/index.md | 3 +- .../using_the_permissions_api/index.md | 47 +++++-------------- .../api/workernavigator/permissions/index.md | 4 +- 6 files changed, 22 insertions(+), 46 deletions(-) diff --git a/files/zh-cn/web/api/permissions/index.md b/files/zh-cn/web/api/permissions/index.md index a277033bdb522b..684cb7e671be3f 100644 --- a/files/zh-cn/web/api/permissions/index.md +++ b/files/zh-cn/web/api/permissions/index.md @@ -2,7 +2,7 @@ title: Permissions slug: Web/API/Permissions l10n: - sourceCommit: ee253ac58d71b2ed336b705ab97dbe93122b3e04 + sourceCommit: 805d398f95c9d1ad8769e65d56bbfe2a31205021 --- {{APIRef("Permissions API")}}{{AvailableInWorkers}} @@ -13,10 +13,6 @@ l10n: - {{domxref("Permissions.query","Permissions.query()")}} - : 返回给定 API 的用户权限状态。 -- {{domxref("Permissions.request","Permissions.request()")}} {{Experimental_Inline}} - - : 请求使用给定 API 的权限。目前任何浏览器都不支持此功能。 -- {{domxref("Permissions.requestAll","Permissions.requestAll()")}} {{Experimental_Inline}} {{Non-standard_Inline}} - - : 请求使用一组给定 API 的权限。目前任何浏览器都不支持此功能。 - {{domxref("Permissions.revoke","Permissions.revoke()")}} {{Deprecated_Inline}} - : 撤消当前在给定 API 上设置的权限。 diff --git a/files/zh-cn/web/api/permissions/query/index.md b/files/zh-cn/web/api/permissions/query/index.md index 81d68ff3f7f150..88e4b0ed56a266 100644 --- a/files/zh-cn/web/api/permissions/query/index.md +++ b/files/zh-cn/web/api/permissions/query/index.md @@ -2,7 +2,7 @@ title: Permissions：query() 方法 slug: Web/API/Permissions/query l10n: - sourceCommit: ee253ac58d71b2ed336b705ab97dbe93122b3e04 + sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 --- {{APIRef("Permissions API")}}{{AvailableInWorkers}} diff --git a/files/zh-cn/web/api/permissions/revoke/index.md b/files/zh-cn/web/api/permissions/revoke/index.md index 6535c7d1742d59..3dae46e5411f0e 100644 --- a/files/zh-cn/web/api/permissions/revoke/index.md +++ b/files/zh-cn/web/api/permissions/revoke/index.md @@ -2,13 +2,17 @@ title: Permissions：revoke() 方法 slug: Web/API/Permissions/revoke l10n: - sourceCommit: afdbe078d7c0357430ff360538edafba3af5496d + sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 --- {{APIRef("Permissions API")}}{{AvailableInWorkers}}{{deprecated_header}} {{domxref("Permissions")}} 接口的 **`revoke()`** 方法可将当前设置的权限还原为默认状态，即通常的 `prompt` 状态。该方法在全局 {{domxref("Permissions")}} 对象 {{domxref("navigator.permissions")}} 上调用。 +This method is removed from the main permissions API specification because its use case is unclear. Permissions are managed by the browser and the current permission model does not involve the site developer being able to imperatively request or revoke permissions. Browsers have shipped this API behind preferences but it's unlikely to reach the standards track. For more context, see the [original discussion to remove `permissions.revoke()`](https://github.com/w3c/permissions/issues/46). + +此方法已从主 Permissions API 规范中删除，因为其用例不明确。权限由浏览器管理，当前权限模型不涉及网站开发人员能够强制请求或撤销权限。浏览器已将此 A​​PI 放在首选项后面，但它不太可能达到标准轨道。有关更多上下文，请参阅[关于删除 `permissions.revoke()` 的原始讨论](https://github.com/w3c/permissions/issues/46)。 + ## 语法 ```js-nolint diff --git a/files/zh-cn/web/api/permissions_api/index.md b/files/zh-cn/web/api/permissions_api/index.md index f053a1393550d3..0df42ad606e895 100644 --- a/files/zh-cn/web/api/permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/index.md @@ -2,7 +2,7 @@ title: 权限 API slug: Web/API/Permissions_API l10n: - sourceCommit: ee253ac58d71b2ed336b705ab97dbe93122b3e04 + sourceCommit: a251e34887530216e319fee73b5b859c8c943a53 --- {{DefaultAPISidebar("Permissions API")}}{{AvailableInWorkers}} @@ -24,6 +24,7 @@ l10n: 并非所有 API 的权限状态都可以通过权限 API 查询。权限相关的 API 的非详尽列表包括： - [Background Synchronization API](/zh-CN/docs/Web/API/Background_Synchronization_API)：`background-sync`（应当总是被授予） +- [Compute Pressure API](/zh-CN/docs/Web/API/Compute_Pressure_API)：`compute-pressure` - [Geolocation API](/zh-CN/docs/Web/API/Geolocation_API)：`geolocation` - [Local Font Access API](/zh-CN/docs/Web/API/Local_Font_Access_API)：`local-fonts` - [Media Capture and Streams API](/zh-CN/docs/Web/API/Media_Capture_and_Streams_API)：`microphone`、`camera` diff --git a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md index 276fbb9d77a124..6dd809fe036359 100644 --- a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md @@ -2,7 +2,7 @@ title: 使用 Permissions API slug: Web/API/Permissions_API/Using_the_Permissions_API l10n: - sourceCommit: 3dbfd299e6f34873d6355bae4b12b5c1c69242f1 + sourceCommit: 805d398f95c9d1ad8769e65d56bbfe2a31205021 --- {{DefaultAPISidebar("Permissions API")}} @@ -17,9 +17,7 @@ l10n: [Permissions API](/zh-CN/docs/Web/API/Permissions_API) 提供了一系列工具来让开发者在权限方面实现更好的用户体验。具体来说，开发人员可以使用 {{domxref("Permissions.query()")}} 来检查在当前上下文中使用特定 API 的权限是已授予、已拒绝还是需要通过提示获得特定用户权限。在主线程中查询权限是被[广泛支持](/zh-CN/docs/Web/API/Permissions_API#api.navigator.permissions)的，在 [Worker](/zh-CN/docs/Web/API/Permissions_API#api.workernavigator.permissions) 中也是如此（但有一个明显的例外）。 -许多 API 现在都能进行权限查询，例如 [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API)、[Notifications API](/zh-CN/docs/Web/API/Notifications_API) - -- [Push API](/zh-CN/docs/Web/API/Push_API)、[Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)。[API 概览](/zh-CN/docs/Web/API/Permissions_API#permission-aware_apis)中提供了许多启用权限的 API 的列表，你可以在[此处的兼容性表](/zh-CN/docs/Web/API/Permissions_API#api.permissions)中了解浏览器的支持情况。 +许多 API 现已启用权限查询，例如 [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API)、[Notifications API](/zh-CN/docs/Web/API/Notifications_API)、[Push API](/zh-CN/docs/Web/API/Push_API) 和 [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)。[API 概览](/zh-CN/docs/Web/API/Permissions_API#permission-aware_apis)中提供了许多权限启用的 API 列表，您可以在[此处的兼容性表](/zh-CN/docs/Web/API/Permissions_API#api.permissions)中了解浏览器支持情况。 {{domxref("Permissions")}} 还有其他方法可用于专门请求使用 API 的权限和撤销权限，但这些方法已被弃用（非标准及不被广泛支持）。 @@ -33,18 +31,18 @@ l10n: ### 访问 Permissions API -浏览器现已包含 {{domxref("Navigator.permissions")}} 属性使开发者可以访问全局的 {{domxref("Permissions")}} 对象。这个对象最终将包含用来查询、申请和重置权限的方法，尽管，目前只有 {{domxref("Permissions.query()")}}; 我们接下来会讨论它。 +浏览器现已包含 {{domxref("Navigator.permissions")}} 属性使开发者可以访问全局的 {{domxref("Permissions")}} 对象。这个对象最终将包含用来查询、申请和重置权限的方法，尽管，目前只有 {{domxref("Permissions.query()")}}；我们接下来会讨论它。 ### 查询权限状态 -在我们的例子中，权限功能使用一个函数来处理— `handlePermission()`. 它开始于使用 {{domxref("Permissions.query()")}} 查询权限状态。根据 Promise resolve 后返回的 {{domxref("PermissionStatus")}} 对象的 {{domxref("PermissionStatus.state", "state")}} 属性，做出不同的处理： +在我们的例子中，权限功能使用一个函数来处理——`handlePermission()`。它开始于使用 {{domxref("Permissions.query()")}} 查询权限状态。根据 Promise 兑现后返回的 {{domxref("PermissionStatus")}} 对象的 {{domxref("PermissionStatus.state", "state")}} 属性，做出不同的处理： - `"granted"` - - : "Enable Geolocation" 按钮被隐藏掉了，因为 Geolocation 已经被允许了，不需要这个按钮了。 + - : “Enable Geolocation”按钮被隐藏掉了，因为 Geolocation 已经被允许了，不需要这个按钮了。 - `"prompt"` - - : 隐藏 "Enable Geolocation" 按钮，因为用户会被（浏览器）引导授权 Geolocation 权限，所以它不需要了。接下来 {{domxref("Geolocation.getCurrentPosition()")}} 函数会运行，它会引导用户授权；如果用户授权了，它会继续执行 `revealPosition()` 函数（会显示地图）；如果用户拒绝了， `positionDenied()` 函数会被执行（这会让 "Enable Geolocation" 按钮显示出来）。 + - : 隐藏“Enable Geolocation”按钮，因为用户会被（浏览器）引导授权 Geolocation 权限，所以它不需要了。接下来 {{domxref("Geolocation.getCurrentPosition()")}} 函数会运行，它会引导用户授权；如果用户授权了，它会继续执行 `revealPosition()` 函数（会显示地图）；如果用户拒绝了， `positionDenied()` 函数会被执行（这会让“Enable Geolocation”按钮显示出来）。 - `"denied"` - - : "Enable Geolocation" 按钮会被显示（这段代码也需要放在这里，以防在页面首次加载时，这个源的权限状态就已经被设置为拒绝了）。 + - : “Enable Geolocation”按钮会被显示（这段代码也需要放在这里，以防在页面首次加载时，这个源的权限状态就已经被设置为拒绝了）。 ```js function handlePermission() { @@ -79,32 +77,7 @@ handlePermission(); ### 权限描述符 -{{domxref("Permissions.query()")}} 方法接受一个 `PermissionDescriptor` 字典作为参数 — 它包含你感兴趣的 API 的名称。一些 API 有继承自默认的 `PermissionDescriptor` 的更加复杂的 `PermissionDescriptor`s 以包含更多额外的信息。例如，`PushPermissionDescriptor` 也包含一个比尔值指定 [`userVisibleOnly`](/zh-CN/docs/Web/API/PushManager/subscribe#Parameters) 是 `true` 还是 `false`. - -### 重置权限 - -从 Firefox 47 开始，你可以使用 {{domxref("Permissions.revoke()")}} 方法重置现有权限。它的调用方式和 {{domxref("Permissions.query()")}} 方法几乎一模一样，区别是，当 promise 成功 resolve 时，它会让一个现有的权限恢复默认状态（通常是 `prompt`）。让我们看看 demo 中的代码： - -```js -const revokeBtn = document.querySelector(".revoke"); - -// ... - -revokeBtn.onclick = () => { - revokePermission(); -}; - -// ... - -function revokePermission() { - navigator.permissions.revoke({ name: "geolocation" }).then((result) => { - report(result.state); - }); -} -``` - -> [!NOTE] -> 自 Firefox 51 开始 `revoke()` 函数被默认关闭了，因为它的设计带来了 [Web Applications Security Working Group](https://www.w3.org/2011/webappsec/) 中提到的问题。可以通过将设置项 `dom.permissions.revoke.enable` 置为 `true` 来重新开启它。 +{{domxref("Permissions.query()")}} 方法接受一个 `PermissionDescriptor` 字典作为参数——它包含你感兴趣的 API 的名称。一些 API 有继承自默认的 `PermissionDescriptor` 的更加复杂的 `PermissionDescriptor` 以包含更多额外的信息。例如，`PushPermissionDescriptor` 也包含一个布尔值指定 [`userVisibleOnly`](/zh-CN/docs/Web/API/PushManager/subscribe#Parameters) 是 `true` 还是 `false`。 ### 响应权限状态变化 @@ -115,6 +88,8 @@ function revokePermission() { 目前，较之我们已有的，这个 API 并没有提供太多额外内容。如果在浏览器询问时，我们选择了从不分享我们的位置，那么不使用浏览器菜单选项的话，我们将无法返回权限的初始状态（询问）： - **Firefox**：_工具 > 页面信息 > 权限 > 访问你的位置_。选择“总是询问”。 -- **Chrome**：_汉堡菜单 > 设置 > 显示高级设置。在隐私部分，点击“内容设置”。在出现的对话框中，找到“位置”部分，选择“当网站试图访问时询问”...最后，点击“管理特例”_，移除你对特定网站的授权。 +- **Chrome**：_汉堡菜单 > 设置 > 显示高级设置。在隐私部分，点击“内容设置”。在出现的对话框中，找到“位置”部分，选择“当网站试图访问时询问”……最后，点击“管理特例”_，移除你对特定网站的授权。 但是，未来浏览器会提供 `request()` 方法，他让我们可以在任何时候以编程的方式来请求权限。这非常值得期待尽快被实现。 + +有提案建议为网站添加强制[请求](https://github.com/WICG/permissions-request)和[撤销](https://github.com/WICG/permissions-revoke)权限的功能，但由于用例不明确且遭到浏览器供应商的反对，因此进展不大。请参阅从主规范中[删除 `permissions.request()`](https://github.com/w3c/permissions/issues/83) 和[删除 `permissions.revoke()`](https://github.com/w3c/permissions/issues/46) 的讨论。 diff --git a/files/zh-cn/web/api/workernavigator/permissions/index.md b/files/zh-cn/web/api/workernavigator/permissions/index.md index 619af770994cb1..3d504d2b557941 100644 --- a/files/zh-cn/web/api/workernavigator/permissions/index.md +++ b/files/zh-cn/web/api/workernavigator/permissions/index.md @@ -2,10 +2,10 @@ title: WorkerNavigator：permissions 属性 slug: Web/API/WorkerNavigator/permissions l10n: - sourceCommit: ee253ac58d71b2ed336b705ab97dbe93122b3e04 + sourceCommit: e8fe043f7d2ad7cd9804d1bf96e0310949f1dac7 --- -{{APIRef("Permissions API")}} +{{APIRef("Permissions API")}}{{AvailableInWorkers("worker")}} {{domxref("WorkerNavigator")}} 接口的 **`permissions`** 只读属性返回一个 {{domxref("Permissions")}} 对象，可以用于查询或更新 [Permissions API](/zh-CN/docs/Web/API/Permissions_API) 涵盖的 API 权限状态。 From 6790d6ebd7312bc9a0430d634a14f5731cd4c1eb Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Mon, 9 Sep 2024 13:27:56 +0800 Subject: [PATCH 2/7] Apply suggestions from code review --- files/zh-cn/web/api/permissions/revoke/index.md | 4 +--- .../api/permissions_api/using_the_permissions_api/index.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/files/zh-cn/web/api/permissions/revoke/index.md b/files/zh-cn/web/api/permissions/revoke/index.md index 3dae46e5411f0e..85cf5cdae879dd 100644 --- a/files/zh-cn/web/api/permissions/revoke/index.md +++ b/files/zh-cn/web/api/permissions/revoke/index.md @@ -9,9 +9,7 @@ l10n: {{domxref("Permissions")}} 接口的 **`revoke()`** 方法可将当前设置的权限还原为默认状态，即通常的 `prompt` 状态。该方法在全局 {{domxref("Permissions")}} 对象 {{domxref("navigator.permissions")}} 上调用。 -This method is removed from the main permissions API specification because its use case is unclear. Permissions are managed by the browser and the current permission model does not involve the site developer being able to imperatively request or revoke permissions. Browsers have shipped this API behind preferences but it's unlikely to reach the standards track. For more context, see the [original discussion to remove `permissions.revoke()`](https://github.com/w3c/permissions/issues/46). - -此方法已从主 Permissions API 规范中删除，因为其用例不明确。权限由浏览器管理，当前权限模型不涉及网站开发人员能够强制请求或撤销权限。浏览器已将此 A​​PI 放在首选项后面，但它不太可能达到标准轨道。有关更多上下文，请参阅[关于删除 `permissions.revoke()` 的原始讨论](https://github.com/w3c/permissions/issues/46)。 +此方法已从 Permissions API 主要规范中删除，因为其用例不明确。权限由浏览器管理，当前权限模型不涉及网站开发人员能够强制请求或撤销权限。浏览器已将此 A​​PI 放在首选项之后，但它不太可能达到标准轨道。有关更多上下文，请参阅[关于删除 `permissions.revoke()` 的原始讨论](https://github.com/w3c/permissions/issues/46)。 ## 语法 diff --git a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md index 6dd809fe036359..01659e0f59638b 100644 --- a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md @@ -17,7 +17,7 @@ l10n: [Permissions API](/zh-CN/docs/Web/API/Permissions_API) 提供了一系列工具来让开发者在权限方面实现更好的用户体验。具体来说，开发人员可以使用 {{domxref("Permissions.query()")}} 来检查在当前上下文中使用特定 API 的权限是已授予、已拒绝还是需要通过提示获得特定用户权限。在主线程中查询权限是被[广泛支持](/zh-CN/docs/Web/API/Permissions_API#api.navigator.permissions)的，在 [Worker](/zh-CN/docs/Web/API/Permissions_API#api.workernavigator.permissions) 中也是如此（但有一个明显的例外）。 -许多 API 现已启用权限查询，例如 [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API)、[Notifications API](/zh-CN/docs/Web/API/Notifications_API)、[Push API](/zh-CN/docs/Web/API/Push_API) 和 [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)。[API 概览](/zh-CN/docs/Web/API/Permissions_API#permission-aware_apis)中提供了许多权限启用的 API 列表，您可以在[此处的兼容性表](/zh-CN/docs/Web/API/Permissions_API#api.permissions)中了解浏览器支持情况。 +许多 API 现已启用权限查询，例如 [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API)、[Notifications API](/zh-CN/docs/Web/API/Notifications_API)、[Push API](/zh-CN/docs/Web/API/Push_API) 和 [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)。[API 概览](/zh-CN/docs/Web/API/Permissions_API#permission-aware_apis)中提供了许多权限启用的 API 列表，你可以在[此处的兼容性表](/zh-CN/docs/Web/API/Permissions_API#api.permissions)中了解浏览器支持情况。 {{domxref("Permissions")}} 还有其他方法可用于专门请求使用 API 的权限和撤销权限，但这些方法已被弃用（非标准及不被广泛支持）。 From 3d18daf8cc0429b209e9e4819f3430341ea92aa4 Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Mon, 9 Sep 2024 13:32:06 +0800 Subject: [PATCH 3/7] Update files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md --- .../web/api/permissions_api/using_the_permissions_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md index 01659e0f59638b..57248f4ebf5f0a 100644 --- a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md @@ -77,7 +77,7 @@ handlePermission(); ### 权限描述符 -{{domxref("Permissions.query()")}} 方法接受一个 `PermissionDescriptor` 字典作为参数——它包含你感兴趣的 API 的名称。一些 API 有继承自默认的 `PermissionDescriptor` 的更加复杂的 `PermissionDescriptor` 以包含更多额外的信息。例如，`PushPermissionDescriptor` 也包含一个布尔值指定 [`userVisibleOnly`](/zh-CN/docs/Web/API/PushManager/subscribe#Parameters) 是 `true` 还是 `false`。 +{{domxref("Permissions.query()")}} 方法接受一个 `PermissionDescriptor` 字典作为参数——它包含你感兴趣的 API 的名称。一些 API 有继承自默认的 `PermissionDescriptor` 的更加复杂的 `PermissionDescriptor` 以包含更多额外的信息。例如，`PushPermissionDescriptor` 也包含一个布尔值指定 [`userVisibleOnly`](/zh-CN/docs/Web/API/PushManager/subscribe#参数) 是 `true` 还是 `false`。 ### 响应权限状态变化 From 88a45a858743a4d00b511e44130e539af92a5435 Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Tue, 24 Sep 2024 15:59:19 +0800 Subject: [PATCH 4/7] sync --- .../zh-cn/web/api/permissions/query/index.md | 27 ++++++----- .../zh-cn/web/api/permissions/revoke/index.md | 33 ++++++++----- files/zh-cn/web/api/permissions_api/index.md | 48 +++++++++++++------ .../using_the_permissions_api/index.md | 21 ++------ 4 files changed, 75 insertions(+), 54 deletions(-) diff --git a/files/zh-cn/web/api/permissions/query/index.md b/files/zh-cn/web/api/permissions/query/index.md index 88e4b0ed56a266..9928f0f1fab5bd 100644 --- a/files/zh-cn/web/api/permissions/query/index.md +++ b/files/zh-cn/web/api/permissions/query/index.md @@ -2,13 +2,17 @@ title: Permissions：query() 方法 slug: Web/API/Permissions/query l10n: - sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 + sourceCommit: 3fde60e07c74ad4954a0c77fdd80958c7d07f088 --- {{APIRef("Permissions API")}}{{AvailableInWorkers}} {{domxref("Permissions")}} 接口的 **`query()`** 方法会返回全局作用域中用户权限的状态。 +用户权限名称在每个功能的各自规范中定义。不同浏览器版本支持的权限在 [`Permissions` 接口的兼容性数据](/zh-CN/docs/Web/API/Permissions#browser_compatibility)中列出（另请参阅 [Firefox 值](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10)、[Chromium 值](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl)和 [WebKit 值](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl)的相关源代码）。 + +每个权限所控制的 API 在[权限 API](/zh-CN/docs/Web/API/Permissions_API) 概述主题中的[权限相关的 API](/zh-CN/docs/Web/API/Permissions_API#权限相关的_api) 中列出。 + ## 语法 ```js-nolint @@ -19,23 +23,24 @@ query(permissionDescriptor) - `permissionDescriptor` - - : 一个为 `query` 操作设置选项的对象，由一个以逗号分隔的键——值对列表组成。可用的选项有： + - : 设置 `query` 操作选项的对象。此描述符的可用选项取决于权限类型。所有权限都有一个名称： - `name` - - : 要查询权限的 API 名称。每个浏览器支持不同的值集。Firefox 的值在[这里](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10)，Chromium 的值在[这里](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl)，WebKit 的值在[这里](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl)。 - - `userVisibleOnly` - - : （仅推送，不被 Firefox 所支持——请参阅下面的“浏览器兼容性”部分）表示是否希望为每条消息显示通知或发送静默推送通知。默认为 `false`。 - - `sysex`（仅限 MIDI） - - : 表示是否需要接收系统专有信息。默认为 `false`。 + - : 包含要查询其权限的 API 名称的字符串，例如 `camera`、`bluetooth`、`camera`、`geolocation`（有关更完整的列表，请参阅 [`Permissions`](/zh-CN/docs/Web/API/Permissions#浏览器兼容性)）。如果浏览器不支持权限名称，则返回的 {{jsxref("Promise")}} 将使用 {{jsxref("TypeError")}} 拒绝。 + + 对于 `push` 权限，你还可以指定： + + - `userVisibleOnly` {{optional_inline}} + - : （仅推送，Firefox 不支持——请参阅下面的浏览器支持部分）表示你是否要为每条消息显示通知或能够发送静默推送通知。默认值为 `false`。 -> [!NOTE] -> 从 Firefox 44 开始，[Notifications](/zh-CN/docs/Web/API/Notifications_API) 和 [Push](/zh-CN/docs/Web/API/Push_API) 的权限已经合并。如果权限已授予（例如由用户在相关权限对话框中授予），`navigator.permissions.query()` 将为 `notifications` 和 `push` 返回 `true`。 + 对于 `midi` 权限，你还可以指定： -> **备注：** `persistent-storage`权限允许根据 [Storage API](https://storage.spec.whatwg.org/) 使用持久盒（即[持久存储](https://storage.spec.whatwg.org/#persistence)）来进行存储。 + - `sysex` {{optional_inline}} + - : 指示是否需要接收系统独有消息。默认值为 `false`。 ### 返回值 -一个会兑现为 {{domxref("PermissionStatus")}} 对象的 {{jsxref("Promise")}}。 +一个兑现为 {{domxref("PermissionStatus")}} 对象的 {{jsxref("Promise")}}。 ### 异常 diff --git a/files/zh-cn/web/api/permissions/revoke/index.md b/files/zh-cn/web/api/permissions/revoke/index.md index 85cf5cdae879dd..ed97945da9f5e7 100644 --- a/files/zh-cn/web/api/permissions/revoke/index.md +++ b/files/zh-cn/web/api/permissions/revoke/index.md @@ -2,7 +2,7 @@ title: Permissions：revoke() 方法 slug: Web/API/Permissions/revoke l10n: - sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 + sourceCommit: 3fde60e07c74ad4954a0c77fdd80958c7d07f088 --- {{APIRef("Permissions API")}}{{AvailableInWorkers}}{{deprecated_header}} @@ -11,31 +11,38 @@ l10n: 此方法已从 Permissions API 主要规范中删除，因为其用例不明确。权限由浏览器管理，当前权限模型不涉及网站开发人员能够强制请求或撤销权限。浏览器已将此 A​​PI 放在首选项之后，但它不太可能达到标准轨道。有关更多上下文，请参阅[关于删除 `permissions.revoke()` 的原始讨论](https://github.com/w3c/permissions/issues/46)。 +{{domxref("Permissions")}} 接口的 **`revoke()`** 方法将当前设置的权限恢复为其默认状态，通常为 `prompt`。此方法在全局 {{domxref("Permissions")}} 对象 {{domxref("navigator.permissions")}} 上调用。 + +此方法已从主要权限 API 规范中删除，因为其用例不明确。权限由浏览器管理，当前权限模型不涉及网站开发人员能够强制请求或撤销权限。浏览器已将此 A​​PI 放在首选项后面，但它不太可能达到标准轨道。有关更多上下文，请参阅[删除 `permissions.revoke()` 的原始讨论](https://github.com/w3c/permissions/issues/46)。 + ## 语法 ```js-nolint -revoke(descriptor) +revoke(permissionDescriptor) ``` ### 参数 -- `descriptor` - - : 一个基于 `PermissionDescriptor` 字典的对象，用于设置由逗号分隔的键——值对列表组成的操作选项。可用的选项有： +- `permissionDescriptor` + + - : 设置 `revoke` 操作选项的对象。此描述符的可用选项取决于权限类型。所有权限都有一个名称： + - `name` - - : 要查询其权限的 API 的名称。每个浏览器支持不同的值集。你可以查阅 [Firefox 的值](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10)、[Chromium 的值](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl)、[WebKit 的值](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl)。 - - `userVisibleOnly` - - : （仅限推送，Firefox 不支持——请参阅下面的[浏览器兼容性](#浏览器兼容性)部分）表示是否要为每条信息显示通知，还是能够发送静默推送通知。默认为 `false`。 - - `sysex`（仅限 MIDI） - - : 表示是否需要接收系统专用消息。默认为 `false`。 + - : 包含要查询其权限的 API 名称的字符串。如果浏览器不支持该权限名称，则返回的 {{jsxref("Promise")}} 将使用 {{jsxref("TypeError")}} 拒绝。 + + 对于 `push` 权限，你还可以指定： + + - `userVisibleOnly` {{optional_inline}} + - : （仅推送，Firefox 不支持——请参阅下面的浏览器支持部分）表示你是否要为每条消息显示通知或能够发送静默推送通知。默认值为 `false`。 -> [!NOTE] -> 从 Firefox 44 开始，[Notifications](/zh-CN/docs/Web/API/Notifications_API) 和 [Push](/zh-CN/docs/Web/API/Push_API) 的权限已经合并。如果权限已授予（例如由用户在相关权限对话框中授予），`navigator.permissions.query()` 将为 `notifications` 和 `push` 返回 `true`。 + 对于 `midi` 权限，你还可以指定： -> **备注：** `persistent-storage` 权限允许使用持久盒（即[持久存储](https://storage.spec.whatwg.org/#persistence)）进行存储，如 [Storage API](https://storage.spec.whatwg.org/) 所述。 + - `sysex` {{optional_inline}} + - : 指示是否需要接收系统独有消息。默认值为 `false`。 ### 返回值 -一个 {{jsxref("Promise")}}，其会在调用兑现处理器时传入指示请求的结果的 {{domxref("PermissionStatus")}} 对象。 +使用 {{domxref("PermissionStatus")}} 对象调用其兑现处理器以指示请求的结果的 {{jsxref("Promise")}}。 ### 异常 diff --git a/files/zh-cn/web/api/permissions_api/index.md b/files/zh-cn/web/api/permissions_api/index.md index 0df42ad606e895..6993fda4148528 100644 --- a/files/zh-cn/web/api/permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/index.md @@ -2,30 +2,49 @@ title: 权限 API slug: Web/API/Permissions_API l10n: - sourceCommit: a251e34887530216e319fee73b5b859c8c943a53 + sourceCommit: 3fde60e07c74ad4954a0c77fdd80958c7d07f088 --- {{DefaultAPISidebar("Permissions API")}}{{AvailableInWorkers}} -**权限 API**（Permissions API）提供一致的编程方式来查询归因于当前上下文的 API 权限的状态。例如，权限 API 可用于确定是否已授予或拒绝访问特定 API 的权限，或者是否需要特定的用户权限。 - -请注意，此 API 的权限有效地聚合了上下文的所有安全限制，包括在安全上下文中使用 API 的任何要求，[Permissions-Policy](/zh-CN/docs/Web/HTTP/Headers/Permissions-Policy) 应用于文档的限制以及用户提示。因此，例如，如果 API 受到权限策略的限制，则返回的权限将被“拒绝”，并且不会提示用户访问。 +**权限 API** 提供了一种一致的编程方式来查询当前上下文（例如网页或 worker）的 API 权限状态。例如，它可用于确定访问特定功能或 API 的权限是否已被授予、被拒绝或需要特定用户权限。 ## 概念和用法 -历史上不同的 API 对自己的权限的处理方式不一致——例如，[Notifications API](/zh-CN/docs/Web/API/Notifications_API) 提供了自己的方法来请求权限和检查权限状态，而 [Geolocation API](/zh-CN/docs/Web/API/Geolocation) 没有。权限 API 提供的工具允许开发者在使用权限时实现一致且更好的用户体验。 +历史上不同的 API 对自己的权限的处理方式不一致——例如，[Notifications API](/zh-CN/docs/Web/API/Notifications_API) 提供了自己的方法来请求权限和检查权限状态，而 [Geolocation API](/zh-CN/docs/Web/API/Geolocation) 没有。权限 API 提供的工具允许开发者在使用权限时实现一致的用户体验。 + +此 API 的权限有效地汇总了上下文的所有安全限制，包括在安全上下文中使用 API 的任何要求、应用于文档的 [Permissions-Policy](/zh-CN/docs/Web/HTTP/Headers/Permissions-Policy) 限制、用户交互要求和用户提示。 +因此，例如，如果 API 受到权限策略的限制，则返回的权限将被 `denied`，并且不会提示用户访问。 + +`permissions` 属性已在 {{domxref("Navigator")}} 对象上可用，在标准浏览上下文和 worker 上下文中均可用（{{domxref("WorkerNavigator")}}——因此可在 worker 内进行权限检查），并返回 {{domxref("Permissions")}} 对象，该对象提供对权限 API 功能的访问。 + +一旦你有了这个对象，你就可以使用 {{domxref("Permissions.query()")}} 方法返回一个通过 {{domxref("PermissionStatus")}} 兑现特定 API 的 promise。 + +### 请求权限 + +如果权限状态为 `prompt`，则用户必须确认提示以授予对该特性的访问权限。 + +触发此提示的机制将取决于特定 API——它未定义为权限 API 的一部分。通常，触发器是调用方法来访问或打开该特性的代码，或者注册随后将访问该特性的通知的代码。 + +请注意，并非所有功能都需要提示。权限可能由 `Permission Policy` 授予，由{{glossary("transient activated", "瞬态激活")}}隐式授予，或通过其他机制授予。 + +### 撤销权限 -`permissions` 属性已在标准浏览上下文和 worker 上下文（{{domxref("WorkerNavigator")}} ——因此可以在 worker 内部进行权限检查）中的 {{domxref("Navigator")}} 对象上可用，并返回一个提供对权限 API 功能的访问的 {{domxref("Permissions")}} 对象。 +权限撤销不由 API 管理。更具体地说，{{domxref("Permissions.revoke()")}} 方法曾被提出，但此后已从实施该方法的浏览器中删除。 -获得此对象后，你可以使用 {{domxref("Permissions.query()")}} 方法返回一个 promise，该 promise 为特定的 API 解析 {{domxref("PermissionStatus")}} 对象。请注意，如果状态为 `prompt`，则用户必须在访问该功能之前确认提示，并且启动此提示的机制将取决于特定的 API——它并未定义为权限 API 的一部分。 +用户可以使用浏览器设置手动删除特定网站的权限： + +- **Firefox**：_汉堡菜单 > 设置 > 隐私和安全 > 权限_（然后选择感兴趣的权限的**设置**按钮）。 +- **Chrome**：_汉堡菜单 > 设置 > 显示高级设置_。在*隐私*部分中，单击*内容设置*。在出现的对话框中，找*位置*部分并选择*当网站尝试... 时询问*。最后，单击*管理例外*并删除你授予你感兴趣的网站的权限。 ### 权限相关的 API 并非所有 API 的权限状态都可以通过权限 API 查询。权限相关的 API 的非详尽列表包括： - [Background Synchronization API](/zh-CN/docs/Web/API/Background_Synchronization_API)：`background-sync`（应当总是被授予） +- [Clipboard_API](/zh-CN/docs/Web/API/Clipboard_API#security_considerations): `clipboard-read`, `clipboard-write` - [Compute Pressure API](/zh-CN/docs/Web/API/Compute_Pressure_API)：`compute-pressure` -- [Geolocation API](/zh-CN/docs/Web/API/Geolocation_API)：`geolocation` +- [Geolocation API](/zh-CN/docs/Web/API/Geolocation_API#security_considerations)：`geolocation` - [Local Font Access API](/zh-CN/docs/Web/API/Local_Font_Access_API)：`local-fonts` - [Media Capture and Streams API](/zh-CN/docs/Web/API/Media_Capture_and_Streams_API)：`microphone`、`camera` - [Notifications API](/zh-CN/docs/Web/API/Notifications_API)：`notifications` @@ -35,15 +54,10 @@ l10n: - [Sensor APIs](/zh-CN/docs/Web/API/Sensor_APIs)：`accelerometer`、`gyroscope`、`magnetometer`、`ambient-light-sensor` - [Storage Access API](/zh-CN/docs/Web/API/Storage_Access_API)：`storage-access`、`top-level-storage-access` - [Storage API](/zh-CN/docs/Web/API/Storage_API)：`persistent-storage` +- [Web Bluetooth API](/zh-CN/docs/Web/API/Web_Bluetooth_API): `bluetooth` - [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)：`midi` - [Window Management API](/zh-CN/docs/Web/API/Window_Management_API)：`window-management` -## 示例 - -我们创建了一个名为 Location Finder 的简单示例。你可以[实时运行示例](https://chrisdavidmills.github.io/location-finder-permissions-api/)，或[在 GitHub 上查看源代码](https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages)。 - -有关其工作原理的更多信息，请阅读我们的文章[使用权限 API](/zh-CN/docs/Web/API/Permissions_API/Using_the_Permissions_API)。 - ## 接口 - {{domxref("Permissions")}} @@ -56,6 +70,12 @@ l10n: - {{domxref("Navigator.permissions")}} 和 {{domxref("WorkerNavigator.permissions")}} {{ReadOnlyInline}} - : 分别用于访问主上下文和 worker 上下文的 {{domxref("Permissions")}} 对象。 +## 示例 + +我们创建了一个名为 Location Finder 的简单示例。你可以[实时运行示例](https://chrisdavidmills.github.io/location-finder-permissions-api/)、[在 GitHub 上查看源代码](https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages)，或者在我们的文章[使用权限 API](/zh-CN/docs/Web/API/Permissions_API/Using_the_Permissions_API)中阅读有关其工作原理的更多信息。 + +[`Permissions.query()` 示例](/zh-CN/docs/Web/API/Permissions/query#测试对不同权限的支持)也展示了在当前浏览器上测试大多数权限并记录结果的代码。 + ## 规范 {{Specifications}} diff --git a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md index 57248f4ebf5f0a..3541a0112d1deb 100644 --- a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md @@ -1,5 +1,5 @@ --- -title: 使用 Permissions API +title: 使用权限 API slug: Web/API/Permissions_API/Using_the_Permissions_API l10n: sourceCommit: 805d398f95c9d1ad8769e65d56bbfe2a31205021 @@ -7,7 +7,7 @@ l10n: {{DefaultAPISidebar("Permissions API")}} -本文提供了使用 W3C [Permissions API](/zh-CN/docs/Web/API/Permissions_API)——它提供了一种用于查询当前上下文的 API 权限授权状态的编程方式——的基本指南。 +本文提供了使用[权限 API](/zh-CN/docs/Web/API/Permissions_API)——它提供了一种用于查询当前上下文的 API 权限授权状态的编程方式——的基本指南。 ## 申请权限面临的困境 @@ -15,7 +15,7 @@ l10n: 由于历史原因，不同的 API 使用各自不同的方式来处理自己的权限──例如，[Notification API](/zh-CN/docs/Web/API/Notifications_API) 允许显式地检查权限状态和申请权限，然而，[Geolocation API](/zh-CN/docs/Web/API/Geolocation_API) 却不能。 -[Permissions API](/zh-CN/docs/Web/API/Permissions_API) 提供了一系列工具来让开发者在权限方面实现更好的用户体验。具体来说，开发人员可以使用 {{domxref("Permissions.query()")}} 来检查在当前上下文中使用特定 API 的权限是已授予、已拒绝还是需要通过提示获得特定用户权限。在主线程中查询权限是被[广泛支持](/zh-CN/docs/Web/API/Permissions_API#api.navigator.permissions)的，在 [Worker](/zh-CN/docs/Web/API/Permissions_API#api.workernavigator.permissions) 中也是如此（但有一个明显的例外）。 +[权限 API](/zh-CN/docs/Web/API/Permissions_API) 提供了一系列工具来让开发者在权限方面实现更好的用户体验。具体来说，开发人员可以使用 {{domxref("Permissions.query()")}} 来检查在当前上下文中使用特定 API 的权限是已授予、已拒绝还是需要通过提示获得特定用户权限。在主线程中查询权限是被[广泛支持](/zh-CN/docs/Web/API/Permissions_API#api.navigator.permissions)的，在 [Worker](/zh-CN/docs/Web/API/Permissions_API#api.workernavigator.permissions) 中也是如此（但有一个明显的例外）。 许多 API 现已启用权限查询，例如 [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API)、[Notifications API](/zh-CN/docs/Web/API/Notifications_API)、[Push API](/zh-CN/docs/Web/API/Push_API) 和 [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)。[API 概览](/zh-CN/docs/Web/API/Permissions_API#permission-aware_apis)中提供了许多权限启用的 API 列表，你可以在[此处的兼容性表](/zh-CN/docs/Web/API/Permissions_API#api.permissions)中了解浏览器支持情况。 @@ -27,9 +27,9 @@ l10n: ![英国格林菲尔德地图的截图](location-finder-with-permissions-api.png) -你可以[在线运行示例](https://chrisdavidmills.github.io/location-finder-permissions-api/)，或[在 Github 查看源代码](https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages)。大部分代码都很简单且常见──所以接下来我们会重点关注和 Permissions API 有关的代码，如果你想学习其他部分，请自行阅读。 +你可以[在线运行示例](https://chrisdavidmills.github.io/location-finder-permissions-api/)，或[在 Github 查看源代码](https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages)。大部分代码都很简单且常见──所以接下来我们会重点关注和权限 API 有关的代码，如果你想学习其他部分，请自行阅读。 -### 访问 Permissions API +### 访问权限 API 浏览器现已包含 {{domxref("Navigator.permissions")}} 属性使开发者可以访问全局的 {{domxref("Permissions")}} 对象。这个对象最终将包含用来查询、申请和重置权限的方法，尽管，目前只有 {{domxref("Permissions.query()")}}；我们接下来会讨论它。 @@ -82,14 +82,3 @@ handlePermission(); ### 响应权限状态变化 你会注意到，在上面的代码中，在 {{domxref("PermissionStatus")}} 对象上有一个 `onchange` 事件回调——这让我们可以对感兴趣的 API 的状态变化做出响应。目前，我们只是上报了状态的变化。 - -## 总结和展望未来 - -目前，较之我们已有的，这个 API 并没有提供太多额外内容。如果在浏览器询问时，我们选择了从不分享我们的位置，那么不使用浏览器菜单选项的话，我们将无法返回权限的初始状态（询问）： - -- **Firefox**：_工具 > 页面信息 > 权限 > 访问你的位置_。选择“总是询问”。 -- **Chrome**：_汉堡菜单 > 设置 > 显示高级设置。在隐私部分，点击“内容设置”。在出现的对话框中，找到“位置”部分，选择“当网站试图访问时询问”……最后，点击“管理特例”_，移除你对特定网站的授权。 - -但是，未来浏览器会提供 `request()` 方法，他让我们可以在任何时候以编程的方式来请求权限。这非常值得期待尽快被实现。 - -有提案建议为网站添加强制[请求](https://github.com/WICG/permissions-request)和[撤销](https://github.com/WICG/permissions-revoke)权限的功能，但由于用例不明确且遭到浏览器供应商的反对，因此进展不大。请参阅从主规范中[删除 `permissions.request()`](https://github.com/w3c/permissions/issues/83) 和[删除 `permissions.revoke()`](https://github.com/w3c/permissions/issues/46) 的讨论。 From 4553acd53a8e3436d13239825f4c9ea1ebfb4e56 Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Tue, 24 Sep 2024 16:29:05 +0800 Subject: [PATCH 5/7] Apply suggestions from code review --- files/zh-cn/web/api/permissions/query/index.md | 2 +- files/zh-cn/web/api/permissions_api/index.md | 6 +++--- .../api/permissions_api/using_the_permissions_api/index.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/files/zh-cn/web/api/permissions/query/index.md b/files/zh-cn/web/api/permissions/query/index.md index 9928f0f1fab5bd..f062e813d1b3ba 100644 --- a/files/zh-cn/web/api/permissions/query/index.md +++ b/files/zh-cn/web/api/permissions/query/index.md @@ -9,7 +9,7 @@ l10n: {{domxref("Permissions")}} 接口的 **`query()`** 方法会返回全局作用域中用户权限的状态。 -用户权限名称在每个功能的各自规范中定义。不同浏览器版本支持的权限在 [`Permissions` 接口的兼容性数据](/zh-CN/docs/Web/API/Permissions#browser_compatibility)中列出（另请参阅 [Firefox 值](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10)、[Chromium 值](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl)和 [WebKit 值](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl)的相关源代码）。 +用户权限名称在每个功能的各自规范中定义。不同浏览器版本支持的权限在 [`Permissions` 接口的兼容性数据](/zh-CN/docs/Web/API/Permissions#浏览器兼容性)中列出（另请参阅 [Firefox 值](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10)、[Chromium 值](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl)和 [WebKit 值](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl)的相关源代码）。 每个权限所控制的 API 在[权限 API](/zh-CN/docs/Web/API/Permissions_API) 概述主题中的[权限相关的 API](/zh-CN/docs/Web/API/Permissions_API#权限相关的_api) 中列出。 diff --git a/files/zh-cn/web/api/permissions_api/index.md b/files/zh-cn/web/api/permissions_api/index.md index 6993fda4148528..2b9bf39c55a450 100644 --- a/files/zh-cn/web/api/permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/index.md @@ -26,7 +26,7 @@ l10n: 触发此提示的机制将取决于特定 API——它未定义为权限 API 的一部分。通常，触发器是调用方法来访问或打开该特性的代码，或者注册随后将访问该特性的通知的代码。 -请注意，并非所有功能都需要提示。权限可能由 `Permission Policy` 授予，由{{glossary("transient activated", "瞬态激活")}}隐式授予，或通过其他机制授予。 +请注意，并非所有功能都需要提示。权限可能由 `Permission Policy` 授予，由{{glossary("transient activation", "瞬态激活")}}隐式授予，或通过其他机制授予。 ### 撤销权限 @@ -42,7 +42,7 @@ l10n: 并非所有 API 的权限状态都可以通过权限 API 查询。权限相关的 API 的非详尽列表包括： - [Background Synchronization API](/zh-CN/docs/Web/API/Background_Synchronization_API)：`background-sync`（应当总是被授予） -- [Clipboard_API](/zh-CN/docs/Web/API/Clipboard_API#security_considerations): `clipboard-read`, `clipboard-write` +- [Clipboard_API](/zh-CN/docs/Web/API/Clipboard_API#security_considerations)：`clipboard-read`、`clipboard-write` - [Compute Pressure API](/zh-CN/docs/Web/API/Compute_Pressure_API)：`compute-pressure` - [Geolocation API](/zh-CN/docs/Web/API/Geolocation_API#security_considerations)：`geolocation` - [Local Font Access API](/zh-CN/docs/Web/API/Local_Font_Access_API)：`local-fonts` @@ -54,7 +54,7 @@ l10n: - [Sensor APIs](/zh-CN/docs/Web/API/Sensor_APIs)：`accelerometer`、`gyroscope`、`magnetometer`、`ambient-light-sensor` - [Storage Access API](/zh-CN/docs/Web/API/Storage_Access_API)：`storage-access`、`top-level-storage-access` - [Storage API](/zh-CN/docs/Web/API/Storage_API)：`persistent-storage` -- [Web Bluetooth API](/zh-CN/docs/Web/API/Web_Bluetooth_API): `bluetooth` +- [Web Bluetooth API](/zh-CN/docs/Web/API/Web_Bluetooth_API)：`bluetooth` - [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)：`midi` - [Window Management API](/zh-CN/docs/Web/API/Window_Management_API)：`window-management` diff --git a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md index 3541a0112d1deb..41651e1f44a7a7 100644 --- a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md @@ -11,13 +11,13 @@ l10n: ## 申请权限面临的困境 -惨淡的事实是，权限在 Web 开发中是令人厌恶却不得不面对的问题，对于开发者而言，处理它毫无乐趣。 +Web 上的权限是令人厌恶却不得不面对的问题，但对于开发人员来说，处理它们并不是一件有趣的事。 由于历史原因，不同的 API 使用各自不同的方式来处理自己的权限──例如，[Notification API](/zh-CN/docs/Web/API/Notifications_API) 允许显式地检查权限状态和申请权限，然而，[Geolocation API](/zh-CN/docs/Web/API/Geolocation_API) 却不能。 [权限 API](/zh-CN/docs/Web/API/Permissions_API) 提供了一系列工具来让开发者在权限方面实现更好的用户体验。具体来说，开发人员可以使用 {{domxref("Permissions.query()")}} 来检查在当前上下文中使用特定 API 的权限是已授予、已拒绝还是需要通过提示获得特定用户权限。在主线程中查询权限是被[广泛支持](/zh-CN/docs/Web/API/Permissions_API#api.navigator.permissions)的，在 [Worker](/zh-CN/docs/Web/API/Permissions_API#api.workernavigator.permissions) 中也是如此（但有一个明显的例外）。 -许多 API 现已启用权限查询，例如 [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API)、[Notifications API](/zh-CN/docs/Web/API/Notifications_API)、[Push API](/zh-CN/docs/Web/API/Push_API) 和 [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)。[API 概览](/zh-CN/docs/Web/API/Permissions_API#permission-aware_apis)中提供了许多权限启用的 API 列表，你可以在[此处的兼容性表](/zh-CN/docs/Web/API/Permissions_API#api.permissions)中了解浏览器支持情况。 +许多 API 现已启用权限查询，例如 [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API)、[Notifications API](/zh-CN/docs/Web/API/Notifications_API)、[Push API](/zh-CN/docs/Web/API/Push_API) 和 [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)。[API 概览](/zh-CN/docs/Web/API/Permissions_API#权限相关的_api)中提供了许多权限启用的 API 列表，你可以在[此处的兼容性表](/zh-CN/docs/Web/API/Permissions_API#api.permissions)中了解浏览器支持情况。 {{domxref("Permissions")}} 还有其他方法可用于专门请求使用 API 的权限和撤销权限，但这些方法已被弃用（非标准及不被广泛支持）。 @@ -31,7 +31,7 @@ l10n: ### 访问权限 API -浏览器现已包含 {{domxref("Navigator.permissions")}} 属性使开发者可以访问全局的 {{domxref("Permissions")}} 对象。这个对象最终将包含用来查询、申请和重置权限的方法，尽管，目前只有 {{domxref("Permissions.query()")}}；我们接下来会讨论它。 +浏览器现已包含 {{domxref("Navigator.permissions")}} 属性使开发者可以访问全局的 {{domxref("Permissions")}} 对象。这个对象最终将包含用来查询、申请和撤销权限的方法，尽管，目前只有 {{domxref("Permissions.query()")}}；我们接下来会讨论它。 ### 查询权限状态 From 912787d0b38db5b4e2c9d244fbbbc559c16e9cd4 Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Thu, 26 Sep 2024 17:40:15 +0800 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Jason Ren <40999116+jasonren0403@users.noreply.github.com> --- files/zh-cn/web/api/permissions/revoke/index.md | 6 +----- files/zh-cn/web/api/permissions_api/index.md | 7 +++---- .../permissions_api/using_the_permissions_api/index.md | 8 ++++---- 3 files changed, 8 insertions(+), 13 deletions(-) diff --git a/files/zh-cn/web/api/permissions/revoke/index.md b/files/zh-cn/web/api/permissions/revoke/index.md index ed97945da9f5e7..f2b72976e1b1bb 100644 --- a/files/zh-cn/web/api/permissions/revoke/index.md +++ b/files/zh-cn/web/api/permissions/revoke/index.md @@ -9,11 +9,7 @@ l10n: {{domxref("Permissions")}} 接口的 **`revoke()`** 方法可将当前设置的权限还原为默认状态，即通常的 `prompt` 状态。该方法在全局 {{domxref("Permissions")}} 对象 {{domxref("navigator.permissions")}} 上调用。 -此方法已从 Permissions API 主要规范中删除，因为其用例不明确。权限由浏览器管理，当前权限模型不涉及网站开发人员能够强制请求或撤销权限。浏览器已将此 A​​PI 放在首选项之后，但它不太可能达到标准轨道。有关更多上下文，请参阅[关于删除 `permissions.revoke()` 的原始讨论](https://github.com/w3c/permissions/issues/46)。 - -{{domxref("Permissions")}} 接口的 **`revoke()`** 方法将当前设置的权限恢复为其默认状态，通常为 `prompt`。此方法在全局 {{domxref("Permissions")}} 对象 {{domxref("navigator.permissions")}} 上调用。 - -此方法已从主要权限 API 规范中删除，因为其用例不明确。权限由浏览器管理，当前权限模型不涉及网站开发人员能够强制请求或撤销权限。浏览器已将此 A​​PI 放在首选项后面，但它不太可能达到标准轨道。有关更多上下文，请参阅[删除 `permissions.revoke()` 的原始讨论](https://github.com/w3c/permissions/issues/46)。 +此方法已从主要权限 API 规范中删除，因为其用例不明确。权限由浏览器管理，当前权限模型不涉及网站开发人员能够强制请求或撤销权限。浏览器已以首选项形式提供此 API，但它不太可能达到标准轨道。有关更多上下文，请参阅[删除 `permissions.revoke()` 的原始讨论](https://github.com/w3c/permissions/issues/46)。 ## 语法 diff --git a/files/zh-cn/web/api/permissions_api/index.md b/files/zh-cn/web/api/permissions_api/index.md index 2b9bf39c55a450..c18aa9f3b84fae 100644 --- a/files/zh-cn/web/api/permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/index.md @@ -13,8 +13,7 @@ l10n: 历史上不同的 API 对自己的权限的处理方式不一致——例如，[Notifications API](/zh-CN/docs/Web/API/Notifications_API) 提供了自己的方法来请求权限和检查权限状态，而 [Geolocation API](/zh-CN/docs/Web/API/Geolocation) 没有。权限 API 提供的工具允许开发者在使用权限时实现一致的用户体验。 -此 API 的权限有效地汇总了上下文的所有安全限制，包括在安全上下文中使用 API 的任何要求、应用于文档的 [Permissions-Policy](/zh-CN/docs/Web/HTTP/Headers/Permissions-Policy) 限制、用户交互要求和用户提示。 -因此，例如，如果 API 受到权限策略的限制，则返回的权限将被 `denied`，并且不会提示用户访问。 +此 API 的权限有效地汇总了上下文的所有安全限制，包括在安全上下文中使用 API 的任何要求、应用于文档的 [Permissions-Policy](/zh-CN/docs/Web/HTTP/Headers/Permissions-Policy) 限制、用户交互要求和用户提示。因此，例如，如果 API 受到权限策略的限制，则返回的权限将会为 `denied`，并且不会提示用户访问。 `permissions` 属性已在 {{domxref("Navigator")}} 对象上可用，在标准浏览上下文和 worker 上下文中均可用（{{domxref("WorkerNavigator")}}——因此可在 worker 内进行权限检查），并返回 {{domxref("Permissions")}} 对象，该对象提供对权限 API 功能的访问。 @@ -34,8 +33,8 @@ l10n: 用户可以使用浏览器设置手动删除特定网站的权限： -- **Firefox**：_汉堡菜单 > 设置 > 隐私和安全 > 权限_（然后选择感兴趣的权限的**设置**按钮）。 -- **Chrome**：_汉堡菜单 > 设置 > 显示高级设置_。在*隐私*部分中，单击*内容设置*。在出现的对话框中，找*位置*部分并选择*当网站尝试... 时询问*。最后，单击*管理例外*并删除你授予你感兴趣的网站的权限。 +- **Firefox**：_菜单 > 设置 > 隐私和安全 > 权限_（然后选择感兴趣的权限的**设置**按钮）。 +- **Chrome**：_菜单 > 设置 > 显示高级设置_。在*隐私*部分中，单击*内容设置*。在出现的对话框中，找到*位置*部分并选择*当网站尝试... 时询问*。最后，单击*管理例外*并删除你授予你感兴趣的网站的权限。 ### 权限相关的 API diff --git a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md index 41651e1f44a7a7..2cc53eec70f687 100644 --- a/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/using_the_permissions_api/index.md @@ -2,7 +2,7 @@ title: 使用权限 API slug: Web/API/Permissions_API/Using_the_Permissions_API l10n: - sourceCommit: 805d398f95c9d1ad8769e65d56bbfe2a31205021 + sourceCommit: 3fde60e07c74ad4954a0c77fdd80958c7d07f088 --- {{DefaultAPISidebar("Permissions API")}} @@ -19,7 +19,7 @@ Web 上的权限是令人厌恶却不得不面对的问题，但对于开发人 许多 API 现已启用权限查询，例如 [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API)、[Notifications API](/zh-CN/docs/Web/API/Notifications_API)、[Push API](/zh-CN/docs/Web/API/Push_API) 和 [Web MIDI API](/zh-CN/docs/Web/API/Web_MIDI_API)。[API 概览](/zh-CN/docs/Web/API/Permissions_API#权限相关的_api)中提供了许多权限启用的 API 列表，你可以在[此处的兼容性表](/zh-CN/docs/Web/API/Permissions_API#api.permissions)中了解浏览器支持情况。 -{{domxref("Permissions")}} 还有其他方法可用于专门请求使用 API 的权限和撤销权限，但这些方法已被弃用（非标准及不被广泛支持）。 +{{domxref("Permissions")}} 还有其他方法可用于专门请求使用 API 的权限和撤销权限，但这些方法已被弃用（非标准且不被广泛支持）。 ## 一个简单的例子 @@ -42,7 +42,7 @@ Web 上的权限是令人厌恶却不得不面对的问题，但对于开发人 - `"prompt"` - : 隐藏“Enable Geolocation”按钮，因为用户会被（浏览器）引导授权 Geolocation 权限，所以它不需要了。接下来 {{domxref("Geolocation.getCurrentPosition()")}} 函数会运行，它会引导用户授权；如果用户授权了，它会继续执行 `revealPosition()` 函数（会显示地图）；如果用户拒绝了， `positionDenied()` 函数会被执行（这会让“Enable Geolocation”按钮显示出来）。 - `"denied"` - - : “Enable Geolocation”按钮会被显示（这段代码也需要放在这里，以防在页面首次加载时，这个源的权限状态就已经被设置为拒绝了）。 + - : “Enable Geolocation”按钮会显示（这段代码也需要放在这里，以防在页面首次加载时，这个源的权限状态就已经被设置为拒绝了）。 ```js function handlePermission() { @@ -77,7 +77,7 @@ handlePermission(); ### 权限描述符 -{{domxref("Permissions.query()")}} 方法接受一个 `PermissionDescriptor` 字典作为参数——它包含你感兴趣的 API 的名称。一些 API 有继承自默认的 `PermissionDescriptor` 的更加复杂的 `PermissionDescriptor` 以包含更多额外的信息。例如，`PushPermissionDescriptor` 也包含一个布尔值指定 [`userVisibleOnly`](/zh-CN/docs/Web/API/PushManager/subscribe#参数) 是 `true` 还是 `false`。 +{{domxref("Permissions.query()")}} 方法接受一个 `PermissionDescriptor` 字典作为参数——它包含你感兴趣的 API 的名称。一些 API 有更复杂的 `PermissionDescriptor` 结构，该结构继承自默认的 `PermissionDescriptor`，包含更多额外的信息。例如，`PushPermissionDescriptor` 也包含一个布尔值指定 [`userVisibleOnly`](/zh-CN/docs/Web/API/PushManager/subscribe#参数) 是 `true` 还是 `false`。 ### 响应权限状态变化 From 8c90ef15a574af43fb6e7c8242b18a2f47bda250 Mon Sep 17 00:00:00 2001 From: Jason Ren <40999116+jasonren0403@users.noreply.github.com> Date: Mon, 30 Sep 2024 09:14:41 +0800 Subject: [PATCH 7/7] Update files/zh-cn/web/api/permissions_api/index.md --- files/zh-cn/web/api/permissions_api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/zh-cn/web/api/permissions_api/index.md b/files/zh-cn/web/api/permissions_api/index.md index c18aa9f3b84fae..a922709ebb0489 100644 --- a/files/zh-cn/web/api/permissions_api/index.md +++ b/files/zh-cn/web/api/permissions_api/index.md @@ -41,7 +41,7 @@ l10n: 并非所有 API 的权限状态都可以通过权限 API 查询。权限相关的 API 的非详尽列表包括： - [Background Synchronization API](/zh-CN/docs/Web/API/Background_Synchronization_API)：`background-sync`（应当总是被授予） -- [Clipboard_API](/zh-CN/docs/Web/API/Clipboard_API#security_considerations)：`clipboard-read`、`clipboard-write` +- [Clipboard API](/zh-CN/docs/Web/API/Clipboard_API#安全考虑)：`clipboard-read`、`clipboard-write` - [Compute Pressure API](/zh-CN/docs/Web/API/Compute_Pressure_API)：`compute-pressure` - [Geolocation API](/zh-CN/docs/Web/API/Geolocation_API#security_considerations)：`geolocation` - [Local Font Access API](/zh-CN/docs/Web/API/Local_Font_Access_API)：`local-fonts`