Permissions API

Permissions API 提供了编程式地检测当前浏览上下文 API 权限

可以用于确定对应的 API 是否已授予权限或被拒绝授予权限，或等待授权权限

同时 API 还会考虑其他因素，如若该 API 对 Secure Context 的要求、Permissions-Policy 的限制等待

该 API 通过 Permissions 接口提供相关功能，并通过 Navigator.permissions 和 WorkerNavigator.permissions 对外暴露 Permissions 实例

检测权限

调用 Permissions 接口的 query() 方法检测给定 API 的权限状态

方法传入一个 permissionDescriptor 的配置项，其唯一参数 name 反映与给定 API 相关的名称

方法返回一个 Promise 的 PermissionStatus，代表与给定 API 相关的权限状态

const status = await navigator.permissions.query({
  name: 'geolocation',
})

console.log(status.state) // 'granted' 'denied' 'prompt'

PermissionStatus 的 state 属性返回一个 string，代表权限的状态，为 'granted' 'denied' 'prompt' 之一

PermissionStatus 的 name 属性返回一个 string，代表权限的名称，与 query() 方法传入的 name 参数一致

PermissionStatus 的 change 事件在权限的状态改变时触发，返回一个 Event

权限名称列表

Permission name	Permission description
accelerometer	Sensor APIs
ambient-light-sensor	Sensor APIs
background-sync	Background Synchronization API
camera	Media Capture and Streams API
clipboard-read	Clipboard API
clipboard-write	Clipboard API
geolocation	Geolocation API
gyroscope	Sensor APIs
local-fonts	Local Font Access API
magnetometer	Sensor APIs
microphone	Media Capture and Streams API
midi	Web MIDI API
notifications	Notifications API
payment-handler	Payment Handler API
persistent-storage	Storage API
push	Push API
speaker-selection	Web Audio Output Devices API
storage-access	Storage Access API
window-management	Window Management API

不同浏览器支持的权限名称参考如下

• Firefox 参见 https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10

• Chromium 参见 https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl#6

• Webkit 参见 https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl#L28

类型

interface Navigator {
  readonly permissions: Permissions
}

partial interface WorkerNavigator {
  readonly permissions: Permissions
}

interface Permissions {
   query(permissionDesc: PermissionDescriptor): Promise<PermissionStatus>
}

interface PermissionDescriptor {
  name: string
}

interface PermissionStatus extends EventTarget {
  readonly state: PermissionState
  readonly name: string

  onchange: ((this: PermissionStatus, ev: Event) => any) | null
}

enum PermissionState {
  "granted",
  "denied",
  "prompt",
}

链接

• https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API
• https://w3c.github.io/permissions/