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

Cho phép trình chạy dịch vụ cho trình duyệt biết trang nào hoạt động khi không có mạng

Content Indexing API là gì?

Khi sử dụng ứng dụng web tiến bộ, bạn có thể 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.v.) 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ớ đệmIndexedDB 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 một ứng dụng web có sẵn khi không có kết nối mạng, họ sẽ không tận dụng hết công việc mà bạn dành để triển khai chức năng đó.

Đây là vấn đề về 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ó thể dùng khi không có mạng để họ có thể khám phá và xem 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ó trên 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 Tệp đã 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à cách cung cấp siêu dữ liệu về các trang đã được nhân viên dịch vụ của bạn lưu vào bộ nhớ đệm, để trình duyệt có thể hiển thị các trang đó khi người dùng có khả năng muốn xem. API Lập chỉ mục nội dung giúp tăng khả năng khám phá các trang được lưu vào bộ nhớ đệm.

Xem ví dụ thực tiễn

Cách tốt nhất để cảm nhận API Lập chỉ mục nội dung là dùng thử một ứng dụng mẫu.

  1. Đảm bảo rằng bạn đang sử dụng 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.
  2. Truy cập vào https://contentindex.dev
  3. Nhấp vào nút + bên cạnh một hoặc nhiều mặt hàng trong danh sách.
  4. (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.
  5. 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.
  6. 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 giúp đảm bảo API Lập chỉ mục nội dung đồng bộ hoá với các mục do ứng dụng web lưu trữ bằng API Bộ nhớ đệm.

Sử dụng API

Để sử dụng API này, ứng dụng của bạn phải có một trình chạy 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 URL cho một trang hiển thị nội dung nghe nhìn và trang hoạt động ngoại tuyến.

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.

Các ứng dụng web chỉ có thể thêm URL vào chỉ mục nội dung thuộc phạm vi của trình chạy 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

Content Indexing API 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 worker 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 thông qua registration. Phương thức này sẽ đã được xác định trong ServiceWorkerGlobalScope.

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 quan. Bạn có quyền 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 chứ không thêm bất cứ nội dung gì 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, từ trang web của bạn), yêu cầu này sẽ kích hoạt sự kiện fetch trên worker dịch vụ.

  • 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() bằng id của mục cần 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 đã 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ục trình đơn Xoá, cho phép mọi người cho biết rằng họ đã xem xong nội dung đã lập chỉ mục trước đó. Giao diện xoá trong Chrome 80 sẽ có dạng như sau:

Mục xoá trong trình đơn.

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

Ý kiến 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 có dự định sử dụng Content Indexing API trong ứng dụng web của mình không? 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 đó.

Một số hệ quả về tính bảo mật và quyền riêng tư của việc lập chỉ mục nội dung là gì?

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.