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ụ cho trình duyệt biết trang nào hoạt động khi không có mạng

Jeff Posnick

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

Việc sử dụng ứng dụng web tiến bộ nghĩa là 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à những nội dung khác) bất kể về trạng thái hiện tại của kết nối mạng. Các công nghệ như nhân viên dịch vụ, Cache Storage API (API Bộ nhớ đệm) và IndexedDB cung cấp cho bạn các nền tảng để lưu trữ và phân phối 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 ứng dụng web tiến bộ (PWA) chất lượng cao và có chế độ ngoại tuyến chỉ là một phần của câu chuyện. Nếu mọi người không nhận ra rằng nội dung của ứng dụng web khi không có mạng, nên chúng sẽ không tận dụng được công việc mà bạn để triển khai chức năng đó.

Đây là vấn đề khám phá; làm cách nào để PWA của bạn khiến người dùng biết về nội dung có thể truy cập ngoại tuyến để họ có thể khám phá và xem những nội dung nào có sẵn? Chiến lược phát hành đĩa đơ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 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 không thể truy cập ngoại tuyến vào chỉ mục cục bộ được duy trì bởi trình duyệt. 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ư bất kỳ nội dung nào khác PWA đã cài đặt, ứng dụng này sẽ hiển thị trên trình duyệt như minh hoạ dưới đây.

Ả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 trong 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 đa phương tiện và bài viết đã được thêm vào chỉ mục sẽ hiển thị trong mục **Tin bài 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 một Người dùng đang ngoại tuyến.

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. Bây giờ một cách cung cấp siêu dữ liệu về những trang đã được 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 muốn xem các bài đăng đó. 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 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 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, giới hạn ở Chrome 84 trở lên trên Android. Hãy truy cập about://version để xem phiên bản Chrome nào 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 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 trình duyệt của bạn không có kết nối mạng.
Chọn Nội dung tải xuống từ 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, PWA Sổ tay lưu trữ, minh hoạ cách dùng API Lập chỉ mục nội dung bằng API Mục tiêu chia sẻ web. Mã này minh hoạ một kỹ thuật để đảm bảo API Lập chỉ mục nội dung đồng bộ với các mục do ứng dụng web lưu trữ bằng cách sử dụng API Lưu trữ 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 ngoại tuyến. 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 Hộp làm việc có thể đơn giản hoá đang tạo một tài khoản.

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

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

Bạn nên tạo một mô hình "người xem" trang HTML có thể chấp nhận URL phương tiện cơ bản dưới dạng tham số truy vấn rồi hiển thị nội dung của , có thể có các tùy chọn kiểm soát 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 về 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ợ ba 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ị trên một thuộc tính mới là index đã được thêm vào ServiceWorkerRegistration .

Bước đầu tiên trong quá trình lập chỉ mục nội dung là lấy tham chiếu đến ServiceWorkerRegistration. 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 bạn thực hiện lệnh gọi đến API Lập chỉ mục nội dung thông qua một trình chạy dịch vụ, thay vì vào trong một trang web, bạn có thể tham khảo ServiceWorkerRegistration trực tiếp thông qua registration. Thuộc tính 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 quan. Tùy chọn bạn chọn thời điểm các mục được thêm vào chỉ mục. Bạn nên thêm vào lập chỉ mục để phản hồi thông tin đầu vào, chẳng hạn như nhấp vào "lưu để xem ngoại tuyến" . Hoặc bạn có thể tự động thêm mục mỗi lần 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 nhập chỉ ảnh hưởng đến chỉ mục nội dung; nó không thêm bất cứ thứ gì vào bộ nhớ đệm.

Trường hợp ngoại lệ: 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 rằng biểu tượng đó có bản sao của biểu tượng để sử dụng khi cho thấy 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 trang), 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 sự kiện khác) trình xử lý), yêu cầu này 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. Giữ lại hãy lưu ý điều này nếu các biểu tượng dựa vào trình xử lý fetch, có thể là vì 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 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 chúng. Các mục nhập được trả về sẽ chứa tất cả dữ liệu được lưu cùng add().

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

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() cùng với id của mục đó để xóa:

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á người dùng

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

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

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

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 việc xoá xảy ra do tương tác với giao diện người dùng tích hợp sẵn của trình duyệt. Mã này không được kích hoạt khi registration.index.delete() sẽ được gọi. Nếu ứng dụng web của bạn kích hoạt chỉ mục xoá bằng phương thức API đó, thì nó cũng sẽ dọn dẹp bộ nhớ đệm ở cùng lúc.

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

Có điều gì đó khiến API bị lỗi hoặc không hoạt động như mong đợi không? Hoặc có thiếu phần nào mà bạn cần để triển khai ý tưởng của mình không?

Hãy báo cáo vấn đề trong kho lưu trữ GitHub về giải thích API Lập chỉ mục nội dung hoặc chia sẻ ý kiến của bạn cho vấn đề hiện tại.

Bạn gặp vấn đề trong quá trình triển khai?

Bạn có phát hiện lỗi trong quá trình triển khai Chrome không?

Báo cáo lỗi tại https://new.crbug.com. Thêm tối đa chi tiết nhất có thể, hướng dẫn đơn giản để tái tạo và thiết lập Thành phần đến Blink>ContentIndexing.

Dự định sử dụng API?

Bạn định dùng API Lập chỉ mục nội dung trong ứng dụng web? Sự 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 thấy tầm quan trọng của tính năng này để hỗ trợ họ.

Gửi một bài đăng đến @ChromiumDev kèm theo hashtag #ContentIndexingAPI cũng như thông tin chi tiết về vị trí và cách bạn sử dụng ứng dụ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ì?

Xem câu trả lời được cung cấp theo bảng câu hỏi về Bảo mật và quyền riêng tư của W3C. Nếu bạn 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.