Permissions:query() 方法

Baseline 2022
Newly available

Since September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

备注: 此特性在 Web Worker 中可用。

Permissions 接口的 query() 方法会返回全局作用域中用户权限的状态。

用户权限名称在每个功能的各自规范中定义。不同浏览器版本支持的权限在 Permissions 接口的兼容性数据中列出(另请参阅 Firefox 值Chromium 值WebKit 值的相关源代码)。

每个权限所控制的 API 在权限 API 概述主题中的权限相关的 API 中列出。

语法

js
query(permissionDescriptor)

参数

permissionDescriptor

设置 query 操作选项的对象。此描述符的可用选项取决于权限类型。所有权限都有一个名称:

name

包含要查询其权限的 API 名称的字符串,例如 camerabluetoothmicrophonegeolocation(有关更完整的列表,请参阅 Permissions)。如果浏览器不支持权限名称,则返回的 Promise 将使用 TypeError 拒绝。

对于 push 权限,你还可以指定:

userVisibleOnly 可选

(仅推送,Firefox 不支持——请参阅下面的浏览器支持部分)表示你是否要为每条消息显示通知或能够发送静默推送通知。默认值为 false

对于 midi 权限,你还可以指定:

sysex 可选

指示是否需要接收系统独有消息。默认值为 false

返回值

一个兑现为 PermissionStatus 对象的 Promise

异常

InvalidStateError DOMException

如果在浏览上下文中调用了 query() 方法,而其关联文档尚未完全激活,则抛出此异常。

TypeError

如果检索 PermissionDescriptor 信息以某种方式失败,或者权限不存在或用户代理不支持该权限,则抛出此异常。

示例

根据地理位置权限显示新闻

此示例显示了在授予 geolocation 权限的情况下,如何显示与当前位置相关的新闻,以及在其他情况下如何提示用户授予访问位置信息的权限。

js
navigator.permissions.query({ name: "geolocation" }).then((result) => {
  if (result.state === "granted") {
    showLocalNewsWithGeolocation();
  } else if (result.state === "prompt") {
    showButtonToEnableLocalNews();
  }
  // 如果权限被拒绝,就什么都不做。
});

测试对不同权限的支持

本例显示了查询每个权限的结果。

代码使用了 navigator.permissions.query() 来查询每个权限,记录权限状态或浏览器不支持该权限。请注意,query() 是在 try...catch 代码块中调用的,因为如果不支持权限,相关的 Promise 就会被拒绝。

js
// 权限数组
const permissions = [
  "accelerometer",
  "accessibility-events",
  "ambient-light-sensor",
  "background-sync",
  "camera",
  "clipboard-read",
  "clipboard-write",
  "geolocation",
  "gyroscope",
  "local-fonts",
  "magnetometer",
  "microphone",
  "midi",
  "notifications",
  "payment-handler",
  "persistent-storage",
  "push",
  "screen-wake-lock",
  "storage-access",
  "top-level-storage-access",
  "window-management",
];

processPermissions();

// 遍历权限并将结果记录下来
async function processPermissions() {
  for (const permission of permissions) {
    const result = await getPermission(permission);
    log(result);
  }
}

// 在 try...catch 块中查询单个权限并返回结果
async function getPermission(permission) {
  try {
    let result;
    if (permission === "top-level-storage-access") {
      result = await navigator.permissions.query({
        name: permission,
        requestedOrigin: window.location.origin,
      });
    } else {
      result = await navigator.permissions.query({ name: permission });
    }
    return `${permission}${result.state}`;
  } catch (error) {
    return `${permission}(不支持)`;
  }
}

运行代码的日志如下所示:

规范

Specification
Permissions
# dom-permissions-query

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
query

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support