browser.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;
browser.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);

browser.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;
browser.browsingData.removeCookies({
  "since": oneWeekAgo
}, callback);

如果使用者正在同步資料，browser.browsingData.remove() 可能會在清除 Cookie 後，自動為同步帳戶重建 Cookie。這是為了確保同步功能可以繼續運作，以便最終在伺服器上刪除資料。不過，您可以使用更具體的 browser.browsingData.removeCookies() 清除同步帳戶的 Cookie，在這種情況下，同步功能會暫停。

特定來源

如要移除特定來源的資料，或從刪除作業中排除一組來源，可以使用 RemovalOptions.origins 和 RemovalOptions.excludeOrigins 參數。只能套用至 Cookie、快取和儲存空間 (CacheStorage、FileSystems、IndexedDB、LocalStorage、ServiceWorkers 和 WebSQL)。

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

來源類型

在 API 選項物件中加入 originTypes 屬性，即可指定應受影響的來源類型。來源分為三類：

  • unprotectedWeb 涵蓋使用者造訪網站的一般情況，不需採取任何特殊動作。如未指定 originTypes，API 預設會從未受保護的網路來源移除資料。
  • protectedWeb 涵蓋已安裝為代管應用程式的網路來源。 舉例來說，安裝「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;
browser.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);

範例

如要試用這個 API，請從 chrome-extension-samples 存放區安裝 browsingData API 範例。

類型

DataTypeSet

一組資料類型。遺漏的資料類型會解讀為 false。

屬性

  • appcache

    布林值 選填

    自 Chrome 152 起淘汰

    系統已移除對 appcache 的支援。系統會忽略這個資料類型。

    網站的應用程式快取。

  • 快取

    布林值 選填

    瀏覽器的快取。

  • cacheStorage

    布林值 選填

    Chrome 72 以上版本 瀏覽器。* 自 Chrome 148 起

    快取儲存空間

  • Cookie

    布林值 選填

    瀏覽器的 Cookie。

  • 下載

    布林值 選填

    瀏覽器的下載清單。

  • fileSystems

    布林值 選填

    網站的檔案系統。

  • formData

    布林值 選填

    瀏覽器儲存的表單資料。

  • 記錄

    布林值 選填

    瀏覽器的歷史記錄。

  • indexedDB

    布林值 選填

    網站的 IndexedDB 資料。

  • localStorage

    布林值 選填

    網站的本機儲存空間資料。

  • 密碼

    布林值 選填

    自 Chrome 144 版起淘汰

    我們已移除透過擴充功能刪除密碼的功能。系統會忽略這個資料類型。

    已儲存的密碼。

  • pluginData

    布林值 選填

    自 Chrome 88 起淘汰

    我們已停止支援 Flash。系統會忽略這個資料類型。

    外掛程式資料。

  • serverBoundCertificates

    布林值 選填

    Chrome 76 起已淘汰

    我們已移除對伺服器繫結憑證的支援。系統會忽略這個資料類型。

    伺服器繫結憑證。

  • serviceWorkers

    布林值 選填

    Service Worker。

  • webSQL

    布林值 選填

    自 Chrome 152 起淘汰

    已停止支援 WebSQL。系統會忽略這個資料類型。

    網站的 WebSQL 資料。

RemovalOptions

決定要移除哪些資料的選項。

屬性

  • excludeOrigins

    string[] 選填

    Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

    如果存在，系統會排除這份清單中的來源資料，不予刪除。無法與 origins 搭配使用。僅支援 Cookie、儲存空間和快取。系統會排除整個可註冊網域的 Cookie。

  • originTypes

    物件 選填

    這個物件的屬性會指定應清除哪些來源類型。如未指定這個物件，預設只會清除「未受保護」的來源。請確認您確實要移除應用程式資料，再新增「protectedWeb」或「extensions」。

    • 擴充功能

      布林值 選填

      使用者安裝的擴充功能和套裝應用程式 (請「務必」小心！)。

    • protectedWeb

      布林值 選填

      以代管應用程式形式安裝的網站 (請小心！)。

    • unprotectedWeb

      布林值 選填

      一般網站。

  • origins

    [string, ...string[]] 選用

    Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

    如果提供這項資訊，系統只會刪除清單中來源的資料。僅支援 Cookie、儲存空間和快取。系統會清除整個可註冊網域的 Cookie。

  • 開始於

    數字 選填

    移除這個日期當天或之後累積的資料，以自紀元起算的毫秒數表示 (可透過 JavaScript Date 物件的 getTime 方法存取)。如未指定，預設值為 0 (會移除所有瀏覽資料)。

方法

remove()

browser.browsingData.remove(
  options: RemovalOptions,
  dataToRemove: DataTypeSet,
): Promise<void>

清除使用者設定檔中儲存的各種瀏覽資料。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    刪除完成後，系統會傳回 Promise。

removeAppcache()

自 Chrome 152 起淘汰
browser.browsingData.removeAppcache(
  options: RemovalOptions,
): Promise<void>

系統已移除對 appcache 的支援。這個函式不會產生任何效果。

清除網站的 AppCache 資料。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    網站的 appcache 資料清除後，就會解析。

removeCache()

browser.browsingData.removeCache(
  options: RemovalOptions,
): Promise<void>

清除瀏覽器快取。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    瀏覽器快取清除完畢後，系統會解析這個 Promise。

removeCacheStorage()

Chrome 72 以上版本 瀏覽器。* 自 Chrome 148 起 
browser.browsingData.removeCacheStorage(
  options: RemovalOptions,
): Promise<void>

清除網站的快取儲存空間資料。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    網站快取儲存空間清除完畢後，就會解析。

removeCookies()

browser.browsingData.removeCookies(
  options: RemovalOptions,
): Promise<void>

清除瀏覽器在特定時間範圍內修改的 Cookie 和伺服器繫結憑證。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    清除瀏覽器的 Cookie 和伺服器繫結憑證後，就會解析。

removeDownloads()

browser.browsingData.removeDownloads(
  options: RemovalOptions,
): Promise<void>

清除瀏覽器的下載檔案清單 (不清除下載的檔案本身)。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    瀏覽器的下載檔案清單清除完畢後，系統會解析這個事件。

removeFileSystems()

browser.browsingData.removeFileSystems(
  options: RemovalOptions,
): Promise<void>

清除網站的檔案系統資料。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    網站檔案系統清除完畢後，就會解析。

removeFormData()

browser.browsingData.removeFormData(
  options: RemovalOptions,
): Promise<void>

清除瀏覽器儲存的表單資料 (自動填入)。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    瀏覽器的表單資料清除完畢後，系統會解析。

removeHistory()

browser.browsingData.removeHistory(
  options: RemovalOptions,
): Promise<void>

清除瀏覽器的歷史記錄。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    瀏覽器記錄清除後，系統會解析。

removeIndexedDB()

browser.browsingData.removeIndexedDB(
  options: RemovalOptions,
): Promise<void>

清除網站的 IndexedDB 資料。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    網站的 IndexedDB 資料清除後，就會解析。

removeLocalStorage()

browser.browsingData.removeLocalStorage(
  options: RemovalOptions,
): Promise<void>

清除網站的本機儲存空間資料。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    網站的本機儲存空間清除完畢後，就會解析。

removePasswords()

自 Chrome 144 版起淘汰
browser.browsingData.removePasswords(
  options: RemovalOptions,
): Promise<void>

我們已移除透過擴充功能刪除密碼的功能。這個函式不會產生任何效果。

清除瀏覽器儲存的密碼。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    瀏覽器密碼清除完畢後，系統會解析。

removePluginData()

自 Chrome 88 起淘汰
browser.browsingData.removePluginData(
  options: RemovalOptions,
): Promise<void>

我們已停止支援 Flash。這個函式不會產生任何效果。

清除外掛程式的資料。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    外掛程式資料清除完畢後，就會解析。

removeServiceWorkers()

Chrome 72 以上版本 瀏覽器。* 自 Chrome 148 起 
browser.browsingData.removeServiceWorkers(
  options: RemovalOptions,
): Promise<void>

清除網站的 Service Worker。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    網站的 Service Worker 清除完畢後，系統會解析。

removeWebSQL()

自 Chrome 152 起淘汰
browser.browsingData.removeWebSQL(
  options: RemovalOptions,
): Promise<void>

已停止支援 WebSQL。這個函式不會產生任何效果。

清除網站的 WebSQL 資料。

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    網站的 WebSQL 資料庫清除完畢後，就會解析。

settings()

browser.browsingData.settings(): Promise<object>

回報「清除瀏覽資料」設定使用者介面中目前選取的資料類型。注意：這個 API 包含的部分資料類型無法在設定 UI 中使用，且部分 UI 設定會控制多種此處列出的資料類型。

傳回

  • Promise<object>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*