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() 可能會在清除後自動為 Sync 帳戶重新建立 Cookie。這是為了確保 Sync 能繼續正常運作，確保最終能刪除伺服器上的資料。不過，更明確的 chrome.browsingData.removeCookies() 可用來清除 Sync 帳戶的 Cookie，且會暫停同步處理。

重要事項：移除瀏覽資料必須在背景處理大量資料，可能需要數十秒才能完成，具體時間視使用者的設定檔而定。您應使用傳回的承諾或回呼，讓使用者能瞭解移除作業的最新狀態。

特定來源

如要移除特定來源的資料，或將一組來源排除在刪除範圍之外，可以使用 RemovalOptions.origins 和 RemovalOptions.excludeOrigins 參數。只能套用到 Cookie、快取和儲存空間 (CacheStorage、FileSystems、IndexedDB、LocalStorage、ServiceWorkers 和 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 涵蓋已安裝為代管應用程式的網路來源。 舉例來說，安裝 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。

屬性

• 應用程式快取

  布林值 (選用)

  網站的應用程式快取。

• 快取

  布林值 (選用)

  瀏覽器的快取。

• 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 會排除整個可註冊網域的 Cookie。

• originTypes

  物件選用

  物件的屬性會指定要清除的來源類型。如未指定這個物件，則預設為僅清除「未保護」來源。請務必先移除應用程式資料，再新增「 ProtectedWeb」或「extensions」。

  • 擴充功能

    布林值 (選用)

    使用者已安裝的擴充功能和封裝應用程式 (請小心謹慎！)。

  • protectedWeb

    布林值 (選用)

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

  • unprotectedWeb

    布林值 (選用)

    一般網站。

• 來源

  string[] 選填

  Chrome 74 以上版本

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

• 開始於

  數字 選填

  移除在此日期當天或之後累積的資料，以 Epoch 紀元時間起算 (以毫秒為單位) 表示 (可透過 JavaScript Date 物件的 getTime 方法存取)。如果缺少該值，則預設值為 0 (這會移除所有瀏覽資料)。

方法

remove()

Promise

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

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

參數

• 選項

  RemovalOptions

• dataToRemove

  DataTypeSet

  要移除的資料類型組合。

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeAppcache()

Promise

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

清除網站的 Appcache 資料。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeCache()

Promise

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

清除瀏覽器的快取。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeCacheStorage()

Promise Chrome 72 以上版本

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

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

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeCookies()

Promise

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

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

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeDownloads()

Promise

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

清除瀏覽器的下載檔案清單，而「不是」下載檔案本身。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeFileSystems()

Promise

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

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

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeFormData()

Promise

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

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

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeHistory()

Promise

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

清除瀏覽器的歷史記錄。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeIndexedDB()

Promise

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

清除網站的 IndexedDB 資料。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeLocalStorage()

Promise

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

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

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removePasswords()

Promise

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

清除瀏覽器儲存的密碼。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removePluginData()

Promise 自 Chrome 88 版起已淘汰的項目

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

不再支援 Flash。這個函式不會產生任何作用。

清除外掛程式的資料。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeServiceWorkers()

Promise Chrome 72 以上版本

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

清除網站的 Service Worker。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeWebSQL()

Promise

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

清除網站的 WebSQL 資料。

參數

• 選項

  RemovalOptions

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

settings()

Promise

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

「清除瀏覽資料」設定使用者介面目前選取的報表類型。注意：設定使用者介面中不會顯示這個 API 包含的部分資料類型，部分使用者介面設定可控管多種資料類型。

參數

• 回呼

  函式選用

  callback 參數如下所示：

  (result: object)=>void

  • 結果

    物件

    • dataRemovalPermitted

      DataTypeSet

      結果中會顯示所有型別，如果它們允許移除值 (如企業政策)，則這些型別會是 true；如果不行，則為 false。

    • dataToRemove

      DataTypeSet

      結果中會顯示所有類型，如果兩個類型都已選取並允許移除，則值為 true，否則會出現 false。

    • 選項

      RemovalOptions

傳回

• Promise<object>

  Chrome 96 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。