許可權：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 上檢視此頁面 • 報告此內容的問題