权限:query() 方法
注意:此功能在 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
将会拒绝。
// 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 |
浏览器兼容性
加载中…