Trang này được dịch bởi Cloud Translation API.

Lập chỉ mục các trang có khả năng ngoại tuyến bằng API Lập chỉ mục nội dung

Bật trình chạy dịch vụ để cho trình duyệt biết những trang nào hoạt động khi không có mạng

Jeff Posnick

Content Indexing API là gì?

Việc sử dụng ứng dụng web tiến bộ có nghĩa là bạn có quyền truy cập vào thông tin mà mọi người quan tâm (hình ảnh, video, bài viết và nhiều nội dung khác) bất kể trạng thái kết nối mạng hiện tại của bạn. Các công nghệ như trình chạy dịch vụ, API bộ nhớ đệm và IndexedDB cung cấp cho bạn các khối xây dựng để lưu trữ và phân phát dữ liệu khi mọi người tương tác trực tiếp với một PWA. Tuy nhiên, việc xây dựng một PWA chất lượng cao, ưu tiên chế độ ngoại tuyến chỉ là một phần của câu chuyện. Nếu người dùng không nhận ra rằng nội dung của ứng dụng web vẫn có sẵn khi họ không có mạng, thì họ sẽ không tận dụng được hết công sức bạn đã bỏ ra để triển khai chức năng đó.

Đây là vấn đề về hoạt động khám phá; làm cách nào để PWA của bạn cho người dùng biết về nội dung có chế độ ngoại tuyến để họ có thể khám phá và xem những nội dung có sẵn? API Lập chỉ mục nội dung là một giải pháp cho vấn đề này. Phần dành cho nhà phát triển của giải pháp này là một tiện ích mở rộng cho worker dịch vụ, cho phép nhà phát triển thêm URL và siêu dữ liệu của các trang có thể hoạt động ngoại tuyến vào một chỉ mục cục bộ do trình duyệt duy trì. Tính năng nâng cao đó có trong Chrome 84 trở lên.

Sau khi chỉ mục được điền sẵn nội dung từ PWA của bạn, cũng như mọi PWA đã cài đặt khác, trình duyệt sẽ hiển thị chỉ mục đó như minh hoạ bên dưới.

Ảnh chụp màn hình mục trong trình đơn Tải xuống trên trang thẻ mới của Chrome. — Trước tiên, hãy chọn mục trình đơn **Tải xuống** trên trang thẻ mới của Chrome.

Nội dung nghe nhìn và bài viết đã được thêm vào chỉ mục. — Nội dung nghe nhìn và bài viết đã được thêm vào chỉ mục sẽ xuất hiện trong phần **Bài viết dành cho bạn**.

Ngoài ra, Chrome có thể chủ động đề xuất nội dung khi phát hiện người dùng đang ở chế độ ngoại tuyến.

Content Indexing API không phải là một cách thay thế để lưu nội dung vào bộ nhớ đệm. Đây là một cách cung cấp siêu dữ liệu về các trang đã được worker dịch vụ lưu vào bộ nhớ đệm để trình duyệt có thể hiển thị các trang đó khi mọi người có khả năng muốn xem. API Lập chỉ mục nội dung giúp khả năng phát hiện của các trang được lưu trong bộ nhớ đệm.

Xem ví dụ thực tiễn

Cách tốt nhất để làm quen với Content Indexing API là thử một ứng dụng mẫu.

Hãy đảm bảo rằng bạn đang sử dụng một trình duyệt và nền tảng được hỗ trợ. Hiện tại, tính năng này chỉ giới hạn ở Chrome 84 trở lên trên Android. Truy cập vào about://version để xem phiên bản Chrome bạn đang chạy.
Truy cập vào https://contentindex.dev
Nhấp vào nút + bên cạnh một hoặc nhiều mục trong danh sách.
(Không bắt buộc) Tắt kết nối Wi-Fi và dữ liệu di động của thiết bị hoặc bật chế độ trên máy bay để mô phỏng việc đưa trình duyệt của bạn sang chế độ ngoại tuyến.
Chọn Tệp đã tải xuống trong trình đơn của Chrome rồi chuyển sang thẻ Bài viết dành cho bạn.
Duyệt qua nội dung bạn đã lưu trước đó.

Bạn có thể xem nguồn của ứng dụng mẫu trên GitHub.

Một ứng dụng mẫu khác, Scrapbook PWA, minh hoạ cách sử dụng API Lập chỉ mục nội dung với API Mục tiêu chia sẻ trên web. Mã này minh hoạ một kỹ thuật để đồng bộ hoá Content Indexing API với các mục do ứng dụng web lưu trữ bằng cách sử dụng Cache Storage API.

Sử dụng API

Để sử dụng API này, ứng dụng của bạn phải có một worker dịch vụ và các URL có thể điều hướng khi không có mạng. Nếu ứng dụng web của bạn hiện không có worker dịch vụ, thì thư viện Workbox có thể đơn giản hoá việc tạo worker dịch vụ.

Loại URL nào có thể được lập chỉ mục là có thể truy cập khi không có mạng?

API hỗ trợ lập chỉ mục URL tương ứng với tài liệu HTML. Ví dụ: không thể lập chỉ mục trực tiếp URL của một tệp phương tiện được lưu vào bộ nhớ đệm. Thay vào đó, bạn cần cung cấp một URL cho trang hiển thị nội dung nghe nhìn và hoạt động khi không có mạng.

Bạn nên tạo một trang HTML "trình xem" có thể chấp nhận URL nội dung nghe nhìn cơ bản dưới dạng tham số truy vấn, sau đó hiển thị nội dung của tệp, có thể có các chế độ điều khiển hoặc nội dung bổ sung trên trang.

Ứng dụng web chỉ có thể thêm URL vào chỉ mục nội dung nằm trong phạm vi của worker dịch vụ hiện tại. Nói cách khác, ứng dụng web không thể thêm URL thuộc một miền hoàn toàn khác vào chỉ mục nội dung.

Tổng quan

API Lập chỉ mục nội dung hỗ trợ 3 thao tác: thêm, liệt kê và xoá siêu dữ liệu. Các phương thức này được hiển thị từ một thuộc tính mới, index, đã được thêm vào giao diện ServiceWorkerRegistration.

Bước đầu tiên trong việc lập chỉ mục nội dung là tham chiếu đến ServiceWorkerRegistration hiện tại. Sử dụng navigator.serviceWorker.ready là cách đơn giản nhất:

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!
}

Nếu đang thực hiện lệnh gọi đến API lập chỉ mục nội dung từ trong một trình chạy dịch vụ, thay vì bên trong một trang web, bạn có thể tham chiếu trực tiếp đến ServiceWorkerRegistration qua registration. Phương thức này sẽ đã được xác định trong ServiceWorkerGlobalScope.

Đang thêm vào chỉ mục

Sử dụng phương thức add() để lập chỉ mục URL và siêu dữ liệu liên kết với URL đó. Bạn có thể tuỳ ý chọn thời điểm thêm các mục vào chỉ mục. Bạn có thể muốn thêm vào chỉ mục để phản hồi một dữ liệu đầu vào, chẳng hạn như nhấp vào nút "lưu ngoại tuyến". Hoặc bạn có thể tự động thêm các mục mỗi khi dữ liệu được lưu vào bộ nhớ đệm được cập nhật thông qua một cơ chế như đồng bộ hoá trong nền định kỳ.

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',
});

Việc thêm một mục chỉ ảnh hưởng đến chỉ mục nội dung; không thêm bất kỳ mục nào vào bộ nhớ đệm.

Trường hợp hiếm gặp: Gọi `add()` từ ngữ cảnh `window` nếu các biểu tượng của bạn dựa vào trình xử lý `fetch`

Khi bạn gọi add(), Chrome sẽ đưa ra yêu cầu về URL của từng biểu tượng để đảm bảo rằng Chrome có một bản sao của biểu tượng đó để sử dụng khi hiển thị danh sách nội dung được lập chỉ mục.

Nếu bạn gọi add() từ ngữ cảnh window (nói cách khác là từ trang web), yêu cầu này sẽ kích hoạt sự kiện fetch trên trình chạy dịch vụ của bạn.
Nếu bạn gọi add() trong trình chạy dịch vụ (có thể bên trong một trình xử lý sự kiện khác), thì yêu cầu sẽ không kích hoạt trình xử lý fetch của trình chạy dịch vụ. Các biểu tượng sẽ được tìm nạp trực tiếp mà không cần đến bất kỳ trình chạy dịch vụ nào. Hãy lưu ý điều này nếu biểu tượng của bạn dựa vào trình xử lý fetch, có thể là do các biểu tượng đó chỉ tồn tại trong bộ nhớ đệm cục bộ chứ không phải trên mạng. Nếu có, hãy đảm bảo rằng bạn chỉ gọi add() từ ngữ cảnh window.

Liệt kê nội dung của chỉ mục

Phương thức getAll() trả về một hứa hẹn cho một danh sách có thể lặp lại gồm các mục đã lập chỉ mục và siêu dữ liệu của những mục đó. Các mục nhập được trả về sẽ chứa tất cả dữ liệu được lưu bằng add().

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

Xoá mục khỏi chỉ mục

Để xoá một mục khỏi chỉ mục, hãy gọi delete() cùng với id của mục đó để xoá:

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

Việc gọi delete() chỉ ảnh hưởng đến chỉ mục. Thao tác này không xoá bất kỳ nội dung nào khỏi bộ nhớ đệm.

Xử lý sự kiện xoá của người dùng

Khi hiển thị nội dung được lập chỉ mục, trình duyệt có thể bao gồm giao diện người dùng riêng với một mục trong trình đơn Xoá để người dùng có thể cho biết rằng họ đã xem xong nội dung được lập chỉ mục trước đó. Dưới đây là giao diện xoá của Chrome 80:

Khi người dùng chọn mục trình đơn đó, worker dịch vụ của ứng dụng web sẽ nhận được một sự kiện contentdelete. Mặc dù không bắt buộc phải xử lý sự kiện này, nhưng sự kiện này sẽ tạo cơ hội cho worker dịch vụ "dọn dẹp" nội dung, chẳng hạn như các tệp phương tiện được lưu vào bộ nhớ đệm cục bộ mà người dùng đã cho biết là đã hoàn tất.

Bạn không cần gọi registration.index.delete() bên trong trình xử lý contentdelete. Nếu sự kiện đã được kích hoạt thì trình duyệt đã thực hiện thao tác xoá chỉ mục liên quan.

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

Lưu ý: Sự kiện contentdelete chỉ được kích hoạt khi quá trình xoá xảy ra do tương tác với giao diện người dùng tích hợp của trình duyệt. Phương thức này không được kích hoạt khi gọi registration.index.delete(). Nếu ứng dụng web của bạn kích hoạt việc xoá chỉ mục bằng phương thức API đó, thì ứng dụng cũng sẽ dọn dẹp nội dung đã lưu vào bộ nhớ đệm cùng lúc.

Phản hồi về thiết kế API

API có gì khó hiểu hoặc không hoạt động như mong đợi không? Hay bạn còn thiếu những phần cần thiết để triển khai ý tưởng của mình?

Gửi vấn đề trên kho lưu trữ GitHub giải thích về Content Indexing API hoặc thêm ý kiến của bạn vào một vấn đề hiện có.

Bạn gặp vấn đề khi triển khai?

Bạn có phát hiện lỗi khi triển khai Chrome không?

Báo cáo lỗi tại https://new.crbug.com. Cung cấp nhiều thông tin nhất có thể, hướng dẫn đơn giản để tái tạo và đặt Thành phần thành Blink>ContentIndexing.

Bạn có dự định sử dụng API này không?

Bạn định dùng API Lập chỉ mục nội dung trong ứng dụng web? Việc bạn công khai ủng hộ Chrome giúp Chrome ưu tiên các tính năng và cho các nhà cung cấp trình duyệt khác thấy tầm quan trọng của việc hỗ trợ các tính năng đó.

Gửi một bài đăng đến @ChromiumDev kèm theo hashtag #ContentIndexingAPI kèm theo thông tin chi tiết về vị trí cũng như cách bạn đang sử dụng hashtag này.

Việc lập chỉ mục nội dung có tác động gì đến quyền riêng tư và khả năng bảo mật?

Hãy xem các câu trả lời được cung cấp để phản hồi bản câu hỏi về Bảo mật và quyền riêng tư của W3C. Nếu bạn có thêm câu hỏi, vui lòng bắt đầu thảo luận thông qua kho lưu trữ GitHub của dự án.

Hình ảnh chính của Maksym Kaharlytskyi trên Unsplash.