Document: requestStorageAccess() 方法

基线 2023

新功能

自 2023 年 12 月起，此功能在最新的设备和浏览器版本中均可使用。此功能可能无法在旧设备或浏览器中使用。

requestStorageAccess() 是 Document 接口的方法，允许在第三方上下文中加载的内容（即嵌入在 <iframe> 中）请求访问第三方 Cookie 和未分区状态。这与默认情况下阻止访问第三方、未分区 Cookie 以提高隐私的用户代理相关（例如，为了防止跟踪），并且是存储访问 API 的一部分。

要检查是否已授予访问第三方 Cookie 的权限，可以调用 Permissions.query()，指定功能名称 "storage-access"。

注意： 服务器上设置的 storage-access 权限策略可能会阻止使用此功能。此外，文档必须通过其他浏览器特定的检查，例如允许列表、阻止列表、设备上的分类、用户设置、反点击劫持启发式算法，或提示用户明确许可。

语法

requestStorageAccess()
requestStorageAccess(types)

参数

types 可选

包含控制哪些未分区状态可访问的属性的对象。如果未指定，则属性的默认值为 false。可用的属性如下

all: 一个布尔值，指定所有可能的未分区状态都应可访问。
cookies: 一个布尔值，指定应允许访问第三方 Cookie。
sessionStorage: 一个布尔值，指定应允许访问 StorageAccessHandle.sessionStorage。
localStorage: 一个布尔值，指定应允许访问 StorageAccessHandle.localStorage。
indexedDB: 一个布尔值，指定应允许访问 StorageAccessHandle.indexedDB。
locks: 一个布尔值，指定应允许访问 StorageAccessHandle.locks。
caches: 一个布尔值，指定应允许访问 StorageAccessHandle.caches。
getDirectory: 一个布尔值，指定应允许访问 StorageAccessHandle.getDirectory()。
estimate: 一个布尔值，指定应允许访问 StorageAccessHandle.estimate()。
createObjectURL: 一个布尔值，指定应允许访问 StorageAccessHandle.createObjectURL()。
revokeObjectURL: 一个布尔值，指定应允许访问 StorageAccessHandle.revokeObjectURL()。
BroadcastChannel: 一个布尔值，指定应允许访问 StorageAccessHandle.BroadcastChannel()。
SharedWorker: 一个布尔值，指定应允许访问 StorageAccessHandle.SharedWorker()。

返回值

一个 Promise，如果授予访问第三方 Cookie 的权限且未提供 types 参数，则以 undefined 作为结果完成；如果授予 types 参数请求的未分区状态的访问权限，则以 StorageAccessHandle 作为结果完成；如果拒绝访问，则拒绝。

requestStorageAccess() 请求会自动拒绝，除非嵌入的内容当前正在处理用户手势（例如点击或轻触）（瞬时激活），或者先前已授予权限。如果之前未授予权限，则需要在基于用户手势的事件处理程序中运行它们。用户手势行为取决于 promise 的状态

如果 promise 解析（即授予权限），则用户手势尚未消耗，因此脚本随后可以调用需要用户手势的 API。
如果 promise 拒绝（即未授予权限），则用户手势已消耗，因此脚本无法执行任何需要手势的操作。这是一种故意针对滥用的保护措施——它阻止脚本在用户接受提示之前循环调用 requestStorageAccess()。

异常

InvalidStateError DOMException

如果以下情况发生，则抛出

当前 Document 尚未激活。
提供了 types 参数，并且其所有属性都为 false。

NotAllowedError DOMException

如果以下情况发生，则抛出

文档的窗口不是安全上下文。
使用被 storage-access 权限策略阻止。
文档或顶级文档具有 null 来源。
嵌入的 <iframe> 已沙箱化，并且未设置 allow-storage-access-by-user-activation 令牌。
用户代理使用 API 的权限请求被拒绝。

示例

document.requestStorageAccess().then(
  () => {
    console.log("cookie access granted");
  },
  () => {
    console.log("cookie access denied");
  },
);

document.requestStorageAccess({ localStorage: true }).then(
  (handle) => {
    console.log("localStorage access granted");
    handle.localStorage.setItem("foo", "bar");
  },
  () => {
    console.log("localStorage access denied");
  },
);

注意： 有关更完整的示例，请参阅使用存储访问 API。

规范

规范
存储访问 API # dom-document-requeststorageaccess

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅

Document.hasStorageAccess()、Document.hasUnpartitionedCookieAccess()、Document.requestStorageAccessFor()
使用存储访问 API
Introducing Storage Access API（WebKit 博客）