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

Cho phép trình chạy dịch vụ biết trang nào hoạt động ngoại tuyến

Jeff Posnick

API Lập chỉ mục nội dung là gì?

Sử dụng một ứng dụng web tiến bộ đồng nghĩa với việc 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.v.), bất kể trạng thái kết nối mạng hiện tại. Các công nghệ như service worker, Cache Storage API và IndexedDB cung cấp cho bạn các khối bản 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 PWA. Tuy nhiên, việc xây dựng một PWA chất lượng cao, ưu tiên sử dụng ngoại tuyến mới chỉ là một phần của câu chuyện. Nếu mọi người không biết rằng nội dung của ứng dụng web vẫn có sẵn khi họ không có kết nối mạng, thì họ sẽ không thể khai thác tối đa công việc bạn bỏ ra để triển khai chức năng đó.

Đây là một vấn đề về khám phá; làm cách nào PWA của bạn có thể cho người dùng biết về nội dung có thể không kết nối mạng để 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 phần mở rộng dành cho trình chạy 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ó chức năng ngoại tuyến vào 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 điền sẵn nội dung từ PWA, cũng như mọi PWA khác đã cài đặt, trình duyệt sẽ hiển thị chỉ mục như sau.

Ảnh chụp màn hình mục trong trình đơn 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 trong trình đơn **Tải xuống** trên trang thẻ mới của Chrome.

Nội dung đa phương tiện và bài viết đã được thêm vào chỉ mục. — Nội dung nghe nhìn và các 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 thấy người dùng không có kết nối mạng.

API Lập chỉ mục nội dung 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 trình chạy 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ó thể muốn xem. API Lập chỉ mục nội dung giúp phát hiện các trang được lưu vào bộ nhớ đệm.

Xem ví dụ thực tiễn

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

Đảm bảo bạn đang sử dụng một trình duyệt và nền tảng được hỗ trợ. Hiện tại, quy trình này chỉ giới hạn ở Chrome 84 trở lên trên Android. Truy cập about://version để xem phiên bản Chrome bạn đang dùng.
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 dữ liệu di động và Wi-Fi 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 xuống chế độ ngoại tuyến.
Chọn Nội dung tải xuống từ menu của Chrome và chuyển sang tab Tin bài dành cho bạn.
Duyệt qua nội dung mà 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 là PWA Scrapbook cho thấy cách sử dụng API Lập chỉ mục nội dung thông qua Web Share Target API. Mã này minh hoạ một kỹ thuật để đồng bộ hoá API Lập chỉ mục nội dung với các mục do một ứng dụng web lưu trữ bằng API Bộ nhớ 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ó trình chạy dịch vụ, thì thư viện Workbox có thể đơn giản hoá quá trình tạo trình chạy dịch vụ.

Loại URL nào có thể được lập chỉ mục là có thể sử dụng chế độ ngoại tuyến?

API hỗ trợ lập chỉ mục các URL tương ứng với tài liệu HTML. Ví dụ: bạn không thể lập chỉ mục trực tiếp một URL cho tệp nội dung nghe nhìn đã 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à hoạt động khi không có mạng.

Mẫu đề xuất là tạo một trang HTML "trình xem" có thể chấp nhận URL nội dung nghe nhìn cơ sở làm 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 nằm trong 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

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ị qua một thuộc tính mới là 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ì trong một trang web, bạn có thể tham chiếu đến ServiceWorkerRegistration trực tiếp thông qua registration. Dữ liệu này đã được xác định như một phần của ServiceWorkerGlobalScope.

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

Sử dụng phương thức add() để lập chỉ mục các URL và siêu dữ liệu liên kết với các URL đó. Bạn có thể 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 thông tin đầu vào, chẳng hạn như nhấp vào nút "lưu để xem ngoại tuyến". Hoặc bạn có thể tự động thêm các mục mỗi khi dữ liệu đã lưu vào bộ nhớ đệm được cập nhật thông qua một cơ chế như đồng bộ hoá định kỳ ở chế độ nền.

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 nội dung nào vào bộ nhớ đệm.

Trường hợp đặc biệt: 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ẽ yêu cầu URL của từng biểu tượng để đảm bảo URL đó có bản sao của biểu tượng để sử dụng khi cho thấy danh sách nội dung đã 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), thì yêu cầu này sẽ kích hoạt một sự kiện fetch trên trình chạy dịch vụ.
Nếu bạn gọi add() trong trình chạy dịch vụ (có thể là 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 sự tham gia của trình chạy dịch vụ. Hãy lưu ý điều này nếu các biểu tượng của bạn dựa vào trình xử lý fetch, có thể là vì các biểu tượng đó chỉ tồn tại trong bộ nhớ đệm cục bộ chứ không tồn tạ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 lời hứa cho một danh sách lặp lại các mục nhập đã lập chỉ mục và siêu dữ liệu của các mục nhập đó. Các mục nhập được trả về sẽ chứa tất cả dữ liệu đã lưu bằng add().

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

Đang xoá các mục khỏi chỉ mục

Để xoá một mục khỏi chỉ mục, hãy gọi delete() với 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á 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 trong trình đơn Delete (Xoá) trong trình đơn. Nhờ vậy, người dùng có cơ hội cho biết rằng họ đã xem xong nội dung được lập chỉ mục trước đó. Sau đây là giao diện xoá trong Chrome 80:

Khi ai đó chọn mục trong trình đơn đó, trình chạy 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 nó giúp trình chạy dịch vụ có cơ hội "dọn dẹp" nội dung (chẳng hạn như các tệp nội dung nghe nhìn được lưu vào bộ nhớ đệm trên máy) mà ai đó đã cho biết rằng họ đã xử lý xong.

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

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. Mã này không được kích hoạt khi registration.index.delete() được gọi. Nếu ứng dụng web của bạn kích hoạt tính năng xoá chỉ mục bằng phương thức API đó, thì ứng dụng web của bạn cũng phải xoá nội dung đã lưu vào bộ nhớ đệm cùng lúc.

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

Có điều gì đó khó xử hoặc không hoạt động như mong đợi không? Hay có phần nào bị thiếu mà bạn cần triển khai ý tưởng không?

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

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

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

Báo cáo lỗi tại https://new.crbug.com. Hãy cung cấp nhiều chi tiết 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 định sử dụng API?

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

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

Việc lập chỉ mục nội dung có những ảnh hưởng gì về bảo mật và quyền riêng tư?

Hãy xem câu trả lời được đưa ra theo bộ 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 qua kho lưu trữ GitHub của dự án.

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