Permissions：query() 方法

基线

广泛可用

自 2022年9月起，此特性已在主流浏览器中得到支持，可在大多数设备和浏览器版本中正常使用。

查看完整兼容性
了解更多

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

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

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

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

语法

query(permissionDescriptor)

参数

permissionDescriptor

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

name: 包含要查询其权限的 API 名称的字符串，例如 camera、bluetooth、microphone、geolocation（有关更完整的列表，请参阅 Permissions）。如果浏览器不支持权限名称，则返回的 Promise 将使用 TypeError 拒绝。

对于 push 权限，你还可以指定：

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

对于 midi 权限，你还可以指定：

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

返回值

一个兑现为 PermissionStatus 对象的 Promise。

异常

InvalidStateError DOMException: 如果在浏览上下文中调用了 query() 方法，而其关联文档尚未完全激活，则抛出此异常。
TypeError: 如果检索 PermissionDescriptor 信息以某种方式失败，或者权限不存在或用户代理不支持该权限，则抛出此异常。

示例

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

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

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 就会被拒绝。

<pre id="log"></pre>

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

#log {
  height: 320px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

// 权限数组
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}（不支持）`;
  }
}

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

规范

规范
Permissions # dom-permissions-query

浏览器兼容性

帮助改进 MDN

了解如何参与贡献

此页面最后更新于 2025年6月24日，由 MDN 贡献者更新。

在 GitHub 上查看此页面 • 报告此内容的问题