瞭解如何使用 Cache API,讓應用程式資料可供離線使用。
Cache API 是用於儲存及擷取網路要求及其對應回應的系統。這些可能會是執行應用程式時建立的一般要求和回應,也可能會是為了儲存資料以供日後使用而建立。
Cache API 的建立目的是讓服務工作者快取網路要求,無論網路速度或可用性如何,都能提供快速回應。不過,您也可以將 API 用於一般儲存機制。
點此查看服務地區
Cache API 適用於所有新式瀏覽器。這項屬性會透過全域 caches
屬性公開,因此您可以透過簡單的功能偵測功能,測試 API 是否存在:
const cacheAvailable = 'caches' in self;
您可以透過視窗、iframe、worker 或 Service Worker 存取 Cache API。
可儲存的內容
快取只會儲存 Request
和 Response
物件的組合,分別代表 HTTP 要求和回應。不過,要求和回應可以包含任何可透過 HTTP 傳輸的資料。
可儲存多少資料?
簡單來說,很多,至少有幾百 MB,甚至可能有數百 GB 以上。瀏覽器實作方式各有不同,但可用的儲存空間量通常取決於裝置的可用儲存空間量。
建立及開啟快取
如要開啟快取,請使用 caches.open(name)
方法,並將快取名稱傳遞為單一參數。如果指定的快取不存在,系統會建立快取。這個方法會傳回與 Cache
物件解析的 Promise
。
const cache = await caches.open('my-cache');
// do something with cache...
新增至快取
將項目新增至快取有三種方法:add
、addAll
和 put
。這三種方法都會傳回 Promise
。
cache.add
首先,有 cache.add()
。它會採用一個參數,可能是 Request
或網址 (string
)。它會向網路發出要求,並將回應儲存在快取中。如果擷取失敗,或是回應的狀態碼不在 200 範圍內,則不會儲存任何內容,且 Promise
會拒絕。請注意,如果跨來源要求不在 CORS 模式中,就無法儲存,因為這類要求會傳回 0
的 status
。這類要求只能儲存在 put
中。
// Retreive data.json from the server and store the response.
cache.add(new Request('/data.json'));
// Retreive data.json from the server and store the response.
cache.add('/data.json');
cache.addAll
接下來是「cache.addAll()
」。其運作方式與 add()
類似,但會採用 Request
物件或網址 (string
) 陣列。這與針對每項個別要求呼叫 cache.add
的運作方式類似,但如果任何個別要求未快取,Promise
就會拒絕。
const urls = ['/weather/today.json', '/weather/tomorrow.json'];
cache.addAll(urls);
在上述每種情況中,新項目都會覆寫任何相符的現有項目。這會使用「擷取」一節所述的相同比對規則。
cache.put
最後,您可以使用 cache.put()
儲存網路的回應,或是自行建立及儲存 Response
。這個函式會採用兩個參數。第一個可以是 Request
物件或網址 (string
)。第二個必須是 Response
,可以來自網路,也可以由程式碼產生。
// Retrieve data.json from the server and store the response.
cache.put('/data.json');
// Create a new entry for test.json and store the newly created response.
cache.put('/test.json', new Response('{"foo": "bar"}'));
// Retrieve data.json from the 3rd party site and store the response.
cache.put('https://example.com/data.json');
put()
方法比 add()
或 addAll()
更為寬鬆,可讓您儲存非 CORS 回應,或回應狀態碼不在 200 範圍內的其他回應。這會覆寫先前針對相同要求的任何回應。
建立 Request 物件
使用儲存物件的網址建立 Request
物件:
const request = new Request('/my-data-store/item-id');
使用 Response 物件
Response
物件建構函式可接受多種資料類型,包括 Blob
、ArrayBuffer
、FormData
物件和字串。
const imageBlob = new Blob([data], {type: 'image/jpeg'});
const imageResponse = new Response(imageBlob);
const stringResponse = new Response('Hello world');
您可以設定適當的標頭,設定 Response
的 MIME 類型。
const options = {
headers: {
'Content-Type': 'application/json'
}
}
const jsonResponse = new Response('{}', options);
如果您已擷取 Response
並想存取其內容,可以使用幾種輔助方法。每個方法都會傳回 Promise
,該方法會以不同類型的值解析。
方法 | 說明 |
---|---|
arrayBuffer |
傳回包含主體的 ArrayBuffer ,已序列化為位元組。 |
blob |
傳回 Blob 。如果 Response 是使用 Blob 建立的,則這個新 Blob 會具有相同的類型。否則,系統會使用 Response 的 Content-Type 。 |
text |
將內文的位元組解讀為 UTF-8 編碼字串。 |
json |
將主體的位元組解讀為 UTF-8 編碼字串,然後嘗試將其剖析為 JSON。傳回產生的物件,如果字串無法解析為 JSON,則擲回 TypeError 。 |
formData |
將內文的位元組解讀為 HTML 表單,並以 multipart/form-data 或 application/x-www-form-urlencoded 編碼。傳回 FormData 物件,如果無法剖析資料,則擲回 TypeError 。 |
body |
傳回內容資料的 ReadableStream。 |
範例說明
const response = new Response('Hello world');
const buffer = await response.arrayBuffer();
console.log(new Uint8Array(buffer));
// Uint8Array(11) [72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]
從快取擷取
如要尋找快取中的項目,您可以使用 match
方法。
const response = await cache.match(request);
console.log(request, response);
如果 request
是字串,瀏覽器會呼叫 new Request(request)
將其轉換為 Request
。如果找到相符的項目,這個函式會傳回會解析為 Response
的 Promise
,否則會傳回 undefined
。
為了判斷兩個 Requests
是否相符,瀏覽器會使用其他資訊,而非僅使用網址。如果兩個要求的查詢字串、Vary
標頭或 HTTP 方法 (GET
、POST
、PUT
等) 不同,系統會視為不同的要求。
您可以將選項物件做為第二個參數傳遞,藉此忽略部分或所有這些項目。
const options = {
ignoreSearch: true,
ignoreMethod: true,
ignoreVary: true
};
const response = await cache.match(request, options);
// do something with the response
如果有多個快取要求符合條件,系統會傳回先建立的要求。如果您想擷取所有相符的回應,可以使用 cache.matchAll()
。
const options = {
ignoreSearch: true,
ignoreMethod: true,
ignoreVary: true
};
const responses = await cache.matchAll(request, options);
console.log(`There are ${responses.length} matching responses.`);
您可以使用 caches.match()
一次搜尋所有快取,而非為每個快取呼叫 cache.match()
,這也是捷徑。
搜尋中
Cache API 不提供搜尋要求或回應的方法,但可比對 Response
物件的項目。不過,您可以使用篩選器或建立索引來實作自訂搜尋。
篩選
實作自訂搜尋功能的方法之一,是逐一檢查所有項目,並篩選出您需要的項目。假設您想找出所有網址結尾為 .png
的項目。
async function findImages() {
// Get a list of all of the caches for this origin
const cacheNames = await caches.keys();
const result = [];
for (const name of cacheNames) {
// Open the cache
const cache = await caches.open(name);
// Get a list of entries. Each item is a Request object
for (const request of await cache.keys()) {
// If the request URL matches, add the response to the result
if (request.url.endsWith('.png')) {
result.push(await cache.match(request));
}
}
}
return result;
}
這樣一來,您就能使用 Request
和 Response
物件的任何屬性篩選項目。請注意,如果搜尋大量資料,這項操作會變得緩慢。
建立索引
實作自訂搜尋的另一種方式,是維護可搜尋項目的索引,並將索引儲存在 IndexedDB 中。這是 IndexedDB 設計用來處理大量項目的作業類型,因此在處理大量項目時,效能會大幅提升。
如果您將 Request
的網址與可搜尋的屬性一併儲存,就能在搜尋後輕鬆擷取正確的快取項目。
刪除項目
如要從快取中刪除項目,請按照下列步驟操作:
cache.delete(request);
其中要求可以是 Request
或網址字串。這個方法也會採用與 cache.match
相同的選項物件,讓您可以刪除同一個網址的多個 Request
/Response
組合。
cache.delete('/example/file.txt', {ignoreVary: true, ignoreSearch: true});
刪除快取
如要刪除快取,請呼叫 caches.delete(name)
。如果快取存在且已刪除,這個函式會傳回會解析為 true
的 Promise
,否則會傳回 false
。
謝謝
感謝 Mat Scales 撰寫本文的原始版本,該版本最早出現在 WebFundamentals 上。