权限：query() 方法

Baseline 已广泛支持

此功能已成熟，并可在多种设备和浏览器版本上运行。自 2022 年 9 月起，所有浏览器都已支持此功能。

注意：此功能在 Web Workers 中可用。

query() 方法是 Permissions 接口的一个方法，用于查询全局作用域下的用户权限状态。

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

每个权限所控制的 API 列表，请参阅 Permissions API 概览主题中的权限感知 API。

语法

query(permissionDescriptor)

参数

permissionDescriptor

一个对象，用于设置 query 操作的选项。此描述符的可用选项取决于权限类型。

所有权限都有一个名称

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

对于 push 权限，您还可以指定

userVisibleOnly 可选: （仅限 Push，Firefox 不支持 - 请参阅下面的浏览器支持部分）指示您是否希望为每条消息显示通知，或者是否能够发送静默推送通知。默认值为 false。

对于 midi 权限，您还可以指定

sysex 可选: 指示您是否需要和/或接收系统独占消息。默认值为 false。

返回值

一个 Promise，它解析为一个 PermissionStatus 对象。

异常

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

示例

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

此示例说明如何在授予 geolocation 权限的情况下显示与当前位置相关的新闻，否则会提示用户允许访问位置信息。

navigator.permissions.query({ name: "geolocation" }).then((result) => {
  if (result.state === "granted") {
    showLocalNewsWithGeolocation();
  } else if (result.state === "prompt") {
    showButtonToEnableLocalNews();
  }
  // Don't do anything if the permission was denied.
});

测试各种权限的支持情况

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

代码使用 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;
}

// Array of permissions
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();

// Iterate through the permissions and log the result
async function processPermissions() {
  for (const permission of permissions) {
    const result = await getPermission(permission);
    log(result);
  }
}

// Query a single permission in a try...catch block and return result
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} (not supported)`;
  }
}

运行代码的日志如下所示

规范

规范
Permissions # dom-permissions-query

浏览器兼容性

帮助改进 MDN

了解如何贡献

此页面最后修改于 2025年8月20日，由 MDN 贡献者修改。

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