本頁面由 Cloud Translation API 翻譯而成。

使用 Content Indexing API 為可離線存取的網頁建立索引

讓服務工作人員判斷哪些網頁可離線運作

Jeff Posnick

什麼是 Content Indexing API？

使用漸進式網頁應用程式，就能取得以提供使用者關注的資訊，包括圖片、影片、文章等等網路連線目前狀態的狀態諸如服務 Worker 等技術 Cache Storage API 和 IndexedDB 機構也能提供基礎模型，直接與 PWA 互動但要打造優質的離線優先 PWA 只有部分劇情發展如果使用者不知道網頁應用程式的內容離線時可以使用這些檔案導入該功能

這就是探索問題。PWA 該如何告知使用者以便他們發掘和查看可離線觀看的內容 Content Indexing API 能夠解決這個問題。面向開發人員的部分這個解決方案是服務工作處理程序的延伸，可讓開發人員將支援離線網頁的網址和中繼資料，新增至由。這項強化功能適用於 Chrome 84 以上版本。

將 PWA 等內容安裝的 PWA 時，瀏覽器將顯示這個 PWA，如下所示。

Chrome 新分頁中「下載」選單項目的螢幕截圖。 — 首先，在 Chrome 新分頁中選取「下載」選單項目。

已新增至索引的媒體和文章。 — 已新增至索引的媒體和文章會顯示在「為你推薦的報導」一節。

此外，Chrome 可在偵測到使用者離線。

Content Indexing API 不是另一種快取內容的方式。是您可以為服務已快取的網頁提供中繼資料它，這樣瀏覽器就能在使用者或是瀏覽這些內容Content Indexing API 可讓您輕鬆發掘快取網頁。

實例觀摩

如要大致瞭解 Content Indexing API，最佳方式就是試用範例應用程式。

確認您使用的是支援的瀏覽器和平台。目前， 在 Android 裝置上搭載 Chrome 84 以上版本。前往「about://version」查看目前使用的 Chrome 版本。
前往 https://contentindex.dev
在清單中按一下一或多個項目旁邊的 + 按鈕。
(選用) 停用裝置的 Wi-Fi 和行動數據連線，或是啟用飛航模式，藉此模擬瀏覽器離線。
從 Chrome 選單中選擇「下載內容」，然後切換至「為你推薦的文章」分頁。
瀏覽您先前儲存的內容。

您可以查看 GitHub 上的範例應用程式來源。

另一個範例應用程式是 Scrapbook PWA，說明如何搭配使用 Content Indexing API 和 Web Share Target API。程式碼示範了一種技巧可讓 Content Indexing API 與網頁應用程式儲存的項目保持同步使用 Cache Storage API。

使用 API

如要使用 API，應用程式必須有 Service Worker 和可瀏覽的網址如果您的網頁應用程式目前沒有 Service Worker，可以使用 Workbox 程式庫簡化建立政策

哪些類型的網址可以建立索引為可離線使用？

這個 API 支援為與 HTML 文件對應的網址建立索引。快取的網址例如，無法直接建立索引媒體檔案。您需要改為提供顯示媒體的網頁網址，可離線運作。

建議建立「檢視器」可接受做為查詢參數，然後顯示檔案，可能會包含其他控制項或內容。

網頁應用程式只能將網址新增到位於以下位置的內容索引：範圍目前 Service Worker。換句話說，網頁應用程式無法新增網址新增至內容索引中完全不同的網域。

總覽

Content Indexing API 支援三種作業：新增、列出和移除中繼資料這些方法會從新屬性 index 公開，已加入 ServiceWorkerRegistration 存取 API

建立索引的第一步是取得對現有內容的參照 ServiceWorkerRegistration。使用 navigator.serviceWorker.ready 是最直接的方式：

const registration = await navigator.serviceWorker.ready;

// Remember to feature-detect before using the API:
if ('index' in registration) {
  // Your Content Indexing API code goes here!
}

如果你是從 Service Worker 內呼叫 Content Indexing API，而非在網頁中，您可以參照 ServiceWorkerRegistration 直接透過 registration 設定目前已預先定義作為「ServiceWorkerGlobalScope.」的一部分

新增至索引

使用 add() 方法為網址及其相關聯的中繼資料建立索引。取決於讓您選擇將項目新增至索引的時機您可能會想將為回應輸入索引，例如按一下 [離線儲存]按鈕。或是您可能會在每次透過機制更新快取資料時，自動新增項目，例如定期背景同步處理。

await registration.index.add({
  // Required; set to something unique within your web app.
  id: 'article-123',

  // Required; url needs to be an offline-capable HTML page.
  url: '/articles/123',

  // Required; used in user-visible lists of content.
  title: 'Article title',

  // Required; used in user-visible lists of content.
  description: 'Amazing article about things!',

  // Required; used in user-visible lists of content.
  icons: [{
    src: '/img/article-123.png',
    sizes: '64x64',
    type: 'image/png',
  }],

  // Optional; valid categories are currently:
  // 'homepage', 'article', 'video', 'audio', or '' (default).
  category: 'article',
});

新增項目只會影響內容索引；該函式不會新增任何項目 cache。

邊緣情況：如果圖示需要使用 `fetch` 處理常式，從 `window` 結構定義呼叫 `add()`

當你呼叫 add() 時，Chrome 會要求存取每個圖示的網址都必須包含圖示副本，顯示已建立索引的內容清單

如果您從 window 情境 (也就是從網站呼叫) 呼叫 add() 網頁)，該要求會在 Service Worker 上觸發 fetch 事件。
如果您在 Service Worker 中呼叫 add() (可能是在其他事件內呼叫) 處理常式)，該要求「不會」觸發 Service Worker 的 fetch 處理常式。圖示將直接擷取，服務工作人員不需進行任何操作。保留請注意，如果圖示依賴 fetch 處理常式，或許是因為只存在於本機快取中，而不存在於網路中。如果有的話，請確認您只能從 window 情境呼叫 add()。

列出索引的內容

getAll() 方法會傳回已建立索引項目的可疊代清單承諾和中繼資料傳回的項目會包含所有以此方式儲存的資料 add()。

const entries = await registration.index.getAll();
for (const entry of entries) {
  // entry.id, entry.launchUrl, etc. are all exposed.
}

從索引中移除項目

如要從索引中移除項目，請使用該項目的 id 呼叫 delete()，以便：移除：

await registration.index.delete('article-123');

呼叫 delete() 只會影響索引。這不會刪除 cache。

處理使用者刪除事件

瀏覽器顯示已編入索引的內容時，可能包括擁有的使用者介面與「Delete」選單項目一致，讓使用者有機會表示會瀏覽先前編入索引的內容這就是刪除資料的方式 Chrome 80 版的介面：

有人選取該選單項目時，網頁應用程式的 Service Worker 就會收到 contentdelete 事件。雖然處理這個事件是選擇性的，但是其會提供讓您的服務工作人員「清理」例如本機快取媒體表示已經有人使用這些檔案

您不需要呼叫 registration.index.delete() contentdelete 處理常式；如果事件已觸發，則相關索引瀏覽器已執行刪除作業。

self.addEventListener('contentdelete', (event) => {
  // event.id will correspond to the id value used
  // when the indexed content was added.
  // Use that value to determine what content, if any,
  // to delete from wherever your app stores it—usually
  // the Cache Storage API or perhaps IndexedDB.
});

敬上

注意：只有在刪除作業因下列原因發生時，才會觸發 contentdelete 事件能夠與瀏覽器內建使用者介面互動不會觸發事件系統已呼叫 registration.index.delete()。如果您的網頁應用程式觸發索引使用這個 API 方法執行刪除作業時，系統應也會清除快取內容

對 API 設計提供意見

您認為這個 API 是否有任何問題或無法正常運作？或實現構想時，你還需要具備某些要素嗎？

請在 Content Indexing API 說明 GitHub 存放區中回報問題，或是提供你的想法現有問題。

無法導入嗎？

您發現 Chrome 實作錯誤嗎？

前往 https://new.crbug.com 回報錯誤。盡可能加入盡可能詳細、重現重製操作說明，並設定「元件」至 Blink>ContentIndexing。

想要使用這個 API 嗎？

想要在網頁應用程式中使用 Content Indexing API 嗎？你的公開支援服務協助 Chrome 優先處理功能，並向其他瀏覽器廠商說明這項功能的重要性支持他們

使用主題標記將推文傳送至 @ChromiumDev #ContentIndexingAPI敬上以及使用位置和方式的詳細說明

內容索引功能對安全性和隱私權帶來哪些影響？

查看解答為回應 W3C 的安全性與隱私權問卷。如果發生以下情況：如有其他問題，請透過專案的 GitHub 存放區發起討論。

主頁橫幅由 Maksym Kaharlytskyi 於 Unsplash 提供。