chrome.browsingData

说明

您可以使用 chrome.browsingData API 从用户的本地个人资料中移除浏览数据。

权限

browsingData

您必须在扩展程序清单中声明 "browsingData" 权限，才能使用此 API。

{
  "name": "My extension",
  ...
  "permissions": [
    "browsingData",
  ],
  ...
}

概念和用法

此 API 最简单的用例是基于时间的机制，用于清除用户浏览数据。您的代码应提供一个时间戳，指明应在该日期之后移除用户浏览数据。此时间戳的格式设置为自 Unix 纪元（可以使用 getTime() 方法从 JavaScript Date 对象检索）以来的毫秒数。

例如，如需清除用户上周的所有浏览数据，您可以编写如下代码：

var callback = function () {
  // Do something clever here once data has been removed.
};

var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
chrome.browsingData.remove({
  "since": oneWeekAgo
}, {
  "appcache": true,
  "cache": true,
  "cacheStorage": true,
  "cookies": true,
  "downloads": true,
  "fileSystems": true,
  "formData": true,
  "history": true,
  "indexedDB": true,
  "localStorage": true,
  "passwords": true,
  "serviceWorkers": true,
  "webSQL": true
}, callback);

借助 chrome.browsingData.remove() 方法，您只需调用一次即可移除各类浏览数据，而且速度比调用多个更具体的方法要快得多。不过，如果您只想清除一种特定类型的浏览数据（例如 Cookie），则可使用更精细的方法作为填充 JSON 的调用的替代方法。

var callback = function () {
  // Do something clever here once data has been removed.
};

var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
chrome.browsingData.removeCookies({
  "since": oneWeekAgo
}, callback);

如果用户正在同步其数据，chrome.browsingData.remove() 可能会在清除 Cookie 后自动为同步帐号重建 Cookie。这是为了确保同步功能可以继续运行，以便将数据最终从服务器上删除。不过，您可以使用更具体的 chrome.browsingData.removeCookies() 来清除同步帐号的 Cookie，并且在这种情况下会暂停同步。

重要提示：移除浏览数据会在后台执行大量繁重的工作，并且可能需要几十秒才能完成，具体取决于用户的个人资料。您应该使用返回的 promise 或回调函数，让用户了解移除的最新状态。

特定来源

如需移除特定源站的数据，或要从删除一组源站，您可以使用 RemovalOptions.origins 和 RemovalOptions.excludeOrigins 参数。它们只能应用于 Cookie、缓存和存储（CacheStorage、FileSystems、IndexedDB、LocalStorage、ServiceWorker 和 WebSQL）。

chrome.browsingData.remove({
  "origins": ["https://www.example.com"]
}, {
  "cacheStorage": true,
  "cookies": true,
  "fileSystems": true,
  "indexedDB": true,
  "localStorage": true,
  "serviceWorkers": true,
  "webSQL": true
}, callback);

重要提示：由于 Cookie 的范围比其他类型的存储更广泛，因此删除来源的 Cookie 将会删除该可注册网域的所有 Cookie。例如，删除 https://www.example.com 的数据也将删除网域为 .example.com 的 Cookie。

来源类型

通过向 API 选项对象添加 originTypes 属性，您可以指定应受影响的源站类型。起源分为三类：

• unprotectedWeb 涵盖用户访问网站的常见情况，无需执行任何特殊操作。如果您未指定 originTypes，该 API 会默认从不受保护的网站源中移除数据。
• protectedWeb 涵盖已作为托管应用安装的那些 Web 源。例如，安装 Angry Birds 可保护源 https://chrome.angrybirds.com 并将其从 unprotectedWeb 类别中移除。触发删除这些来源的数据时要小心：请确保您的用户知道他们将获取什么，因为这会导致用户无法撤销地移除他们的游戏数据。没有人愿意本来就不必要地翻过小猪屋。
• extension 涵盖 chrome-extensions: 架构下的源站。同样，移除扩展程序数据也值得格外小心。

我们可以调整前面的示例，仅移除受保护网站的数据，如下所示：

var callback = function () {
  // Do something clever here once data has been removed.
};

var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
chrome.browsingData.remove({
  "since": oneWeekAgo,
  "originTypes": {
    "protectedWeb": true
  }
}, {
  "appcache": true,
  "cache": true,
  "cacheStorage": true,
  "cookies": true,
  "downloads": true,
  "fileSystems": true,
  "formData": true,
  "history": true,
  "indexedDB": true,
  "localStorage": true,
  "passwords": true,
  "serviceWorkers": true,
  "webSQL": true
}, callback);

警告：请谨慎使用 protectedWeb 和 extension 源类型。这些都是破坏性操作，如果用户不清楚您的扩展程序代表用户移除数据时会发生什么，他们可能会感到意外。

示例

如需试用此 API，请从 chrome-extension-samples 代码库安装 browsingData API 示例。

类型

DataTypeSet

一组数据类型。缺失的数据类型会被解读为 false。

属性

• appcache

  布尔值 选填

  网站的应用缓存。

• 缓存

  布尔值 选填

  浏览器的缓存。

• cacheStorage

  布尔值 选填

  Chrome 72 及更高版本

  缓存存储空间

• Google Cloud 网站上的 Cookie，

  布尔值 选填

  浏览器的 Cookie。

• 下载次数增幅

  布尔值 选填

  浏览器的下载列表。

• fileSystems

  布尔值 选填

  网站的文件系统。

• formData

  布尔值 选填

  浏览器存储的表单数据。

• 历史

  布尔值 选填

  浏览器的历史记录。

• indexedDB

  布尔值 选填

  网站的 IndexedDB 数据。

• localStorage

  布尔值 选填

  网站的本地存储数据。

• 密码

  布尔值 选填

  存储的密码。

• pluginData

  布尔值 选填

  从 Chrome 88 开始已废弃

  不再支持 Flash。系统会忽略此数据类型。

  插件的数据。

• serverBoundCertificates

  布尔值 选填

  从 Chrome 76 开始已废弃

  不再支持服务器绑定证书。系统会忽略此数据类型。

  服务器绑定证书。

• serviceWorkers

  布尔值 选填

  Service Worker。

• webSQL

  布尔值 选填

  网站的 WebSQL 数据。

RemovalOptions

用于确定具体移除哪些数据的选项。

属性

• excludeOrigins

  string[] 可选

  Chrome 74 及更高版本

  如果存在，此列表中源站的数据将被排除在删除范围之外。不能与 origins 一起使用。仅支持 Cookie、存储和缓存。整个可注册网域都排除了 Cookie。

• originTypes

  对象（可选）

  一个对象，其属性指定应清除的源类型。如果未指定此对象，则默认为仅清除“未受保护的”源站。请确保您确实要删除应用数据，然后再添加“protectedWeb”或“extensions”。

  • 扩展程序

    布尔值 选填

    用户已安装的扩展程序和打包应用程序（_一定要_小心！）。

  • protectedWeb

    布尔值 选填

    以托管应用程序的形式安装的网站（请注意！）。

  • unprotectedWeb

    布尔值 选填

    常规网站。

• 源

  string[] 可选

  Chrome 74 及更高版本

  如果存在，系统只会删除此列表中源站的数据。仅支持 Cookie、存储和缓存。清除整个可注册网域的 Cookie。

• 开始于

  数字可选

  移除此日期当天或之后累积的数据（以自纪元以来的毫秒数表示）（可通过 JavaScript Date 对象的 getTime 方法访问）。如果没有，则默认为 0（这将移除所有浏览数据）。

方法

remove()

Promise

chrome.browsingData.remove(
  options: RemovalOptions,
  dataToRemove: DataTypeSet,
  callback?: function,
)

清除用户个人资料中存储的各类浏览数据。

参数

• 选项

  RemovalOptions

• dataToRemove

  DataTypeSet

  要移除的数据类型集。

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeAppcache()

Promise

chrome.browsingData.removeAppcache(
  options: RemovalOptions,
  callback?: function,
)

清除网站的应用缓存数据。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeCache()

Promise

chrome.browsingData.removeCache(
  options: RemovalOptions,
  callback?: function,
)

清除浏览器的缓存。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeCacheStorage()

Promise Chrome 72 及更高版本

chrome.browsingData.removeCacheStorage(
  options: RemovalOptions,
  callback?: function,
)

清除网站的缓存存储数据。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeCookies()

Promise

chrome.browsingData.removeCookies(
  options: RemovalOptions,
  callback?: function,
)

清除在特定时间范围内修改的浏览器 Cookie 和服务器绑定证书。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeDownloads()

Promise

chrome.browsingData.removeDownloads(
  options: RemovalOptions,
  callback?: function,
)

清除浏览器的已下载文件列表（而非已下载的文件本身）。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeFileSystems()

Promise

chrome.browsingData.removeFileSystems(
  options: RemovalOptions,
  callback?: function,
)

清除网站的文件系统数据。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeFormData()

Promise

chrome.browsingData.removeFormData(
  options: RemovalOptions,
  callback?: function,
)

清除浏览器存储的表单数据（自动填充）。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeHistory()

Promise

chrome.browsingData.removeHistory(
  options: RemovalOptions,
  callback?: function,
)

清除浏览器的历史记录。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeIndexedDB()

Promise

chrome.browsingData.removeIndexedDB(
  options: RemovalOptions,
  callback?: function,
)

清除网站的 IndexedDB 数据。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeLocalStorage()

Promise

chrome.browsingData.removeLocalStorage(
  options: RemovalOptions,
  callback?: function,
)

清除网站的本地存储数据。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removePasswords()

Promise

chrome.browsingData.removePasswords(
  options: RemovalOptions,
  callback?: function,
)

清除浏览器存储的密码。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removePluginData()

Promise 从 Chrome 88 开始已废弃

chrome.browsingData.removePluginData(
  options: RemovalOptions,
  callback?: function,
)

不再支持 Flash。此函数不起作用。

清除插件的数据。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeServiceWorkers()

Promise Chrome 72 及更高版本

chrome.browsingData.removeServiceWorkers(
  options: RemovalOptions,
  callback?: function,
)

清除网站的 Service Worker。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeWebSQL()

Promise

chrome.browsingData.removeWebSQL(
  options: RemovalOptions,
  callback?: function,
)

清除网站的 WebSQL 数据。

参数

• 选项

  RemovalOptions

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

settings()

Promise

chrome.browsingData.settings(
  callback?: function,
)

报告当前在“清除浏览数据”设置界面中选择了哪些类型的数据。注意：此 API 中包含的某些数据类型在设置界面中不可用，而有些界面设置可以控制此处列出的多种数据类型。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (result: object)=>void

  • 结果

    对象

    • dataRemovalPermitted

      DataTypeSet

      所有类型都会显示在结果中，如果允许移除（例如通过企业政策），则值为 true；否则，值为 false。

    • dataToRemove

      DataTypeSet

      所有类型都会出现在结果中，如果同时选择移除和允许移除，则值为 true，否则为 false。

    • 选项

      RemovalOptions

返回

• Promise<object>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。