chrome.mimeHandler

Mô tả

Phạm vi cung cấp

Tệp kê khai

Khái niệm và cách sử dụng

Trước đây, các tiện ích của bên thứ ba xử lý các loại tài liệu cụ thể (chẳng hạn như trình xem PDF) dựa vào tính năng chặn yêu cầu mạng để nắm bắt các thao tác điều hướng và chuyển hướng người dùng đến một trang tiện ích. Việc đăng ký làm trình xử lý MIME giúp tránh được một số hạn chế của phương pháp đó:

• URL ban đầu vẫn nằm trong thanh địa chỉ thay vì được thay thế bằng URL chrome-extension://.
• Tiện ích của bạn sẽ tìm nạp phản hồi mà Chrome đã nhận được, thay vì đưa ra yêu cầu mạng thứ hai. Các tài liệu được gửi bằng yêu cầu POST hoặc từ URL dùng một lần hoạt động chính xác.
• Tiện ích của bạn có thể kết xuất các tài liệu được tải trong các phần tử <embed>, <object> hoặc <iframe>.
• Các tệp cục bộ (URL file://) hoạt động mà không cần người dùng bật chế độ "Cho phép truy cập vào các URL của tệp" theo cách thủ công trong phần cài đặt của tiện ích.

Trình xử lý MIME chỉ áp dụng cho những tài liệu chiếm toàn bộ khung hình: các thao tác điều hướng cấp cao nhất và tài liệu được nhúng. Chúng không bao giờ áp dụng cho các tài nguyên phụ nội tuyến (ví dụ: phần tử <audio>, <img> hoặc <video>).

Đăng ký một trình xử lý

Để đăng ký tiện ích của bạn làm trình xử lý MIME, hãy khai báo khoá "mime_types_handler" trong manifest. Mỗi mục ánh xạ một loại MIME đến trang tiện ích kết xuất loại MIME đó:

manifest.json:

{
  "name": "My PDF Viewer",
  ...
  "mime_types_handler": {
    "application/pdf": {
      "handler_url": "viewer.html",
      "can_embed": true
    }
  },
  ...
}

Đặt "can_embed" thành true để xử lý cả những tài liệu được nhúng trong các phần tử <embed>, <object> hoặc <iframe>. Nếu bị bỏ qua, trình xử lý của bạn sẽ chỉ nhận được các thao tác điều hướng cấp cao nhất. Kể từ Chrome 151, application/pdf là loại MIME duy nhất có sẵn cho các trình xử lý công khai; việc khai báo một loại MIME không được hỗ trợ sẽ gây ra cảnh báo cài đặt.

Nếu có nhiều tiện ích đã cài đặt đăng ký cùng một loại MIME, thì tiện ích được cài đặt gần đây nhất sẽ xử lý loại MIME đó. Nếu tiện ích đó bị gỡ cài đặt, trình xử lý đã cài đặt trước đó sẽ hoạt động trở lại.

Truy xuất thông tin về luồng

Khi người dùng mở một tài liệu thuộc loại MIME đã đăng ký, Chrome sẽ tải trang trình xử lý của bạn thay vì trình xem tích hợp sẵn. Từ trang trình xử lý, hãy gọi getStreamInfo() để truy xuất một đối tượng StreamInfo. Trong đó có originalUrl mà người dùng đã chuyển đến, responseHeaders HTTP, liệu tài liệu có được tải trong ngữ cảnh embedded hay không và streamUrl có thể dùng để tìm nạp nội dung của tài liệu.

Bạn chỉ có thể tìm nạp streamUrl một lần và chỉ từ nguồn gốc của tiện ích. Đọc toàn bộ phản hồi trước khi xử lý; lần tìm nạp thứ hai của cùng một streamUrl sẽ không thành công. Sử dụng originalUrl khi hiển thị vị trí hoặc tiêu đề của tài liệu, chứ không phải để tìm nạp nội dung, vì yêu cầu ban đầu có thể không lặp lại được.

Quay lại trình xử lý gốc

Trình xử lý của bạn có thể gặp phải những tài liệu mà trình xử lý đó không thể hiển thị, chẳng hạn như tệp bị hỏng hoặc được bảo vệ bằng mật khẩu. Gọi abortAndFallbackToNativeHandler() để ngừng xử lý tài liệu và trả lại tài liệu cho trình xem tích hợp của Chrome, thay vì để người dùng trên một trang bị lỗi. Chrome huỷ tải trang trình xử lý của bạn trong quá trình dự phòng; không có mã nào chạy sau lệnh gọi này.

Chrome sẽ lưu vào bộ nhớ đệm phản hồi trong khi trình xử lý của bạn chạy. Nếu bạn đã nhận được toàn bộ phản hồi khi gọi phương thức này, thì Chrome sẽ phân phát trình xem tích hợp từ bản sao được lưu vào bộ nhớ đệm mà không cần yêu cầu mạng mới. Nếu không, Chrome sẽ tải lại tài liệu từ mạng. Việc này có thể không thành công đối với các tài liệu được gửi bằng POST hoặc từ URL dùng một lần. Hãy tìm nạp toàn bộ luồng trước khi quyết định xem bạn có thể kết xuất luồng đó hay không; sau khi quá trình tìm nạp streamUrl hoàn tất, Chrome sẽ có toàn bộ phản hồi.

Xử lý khả năng sử dụng của API

Trong các phiên bản Chrome trước Chrome 151, một tiện ích khai báo "mime_types_handler" vẫn cài đặt và chạy, nhưng không được đăng ký làm trình xử lý và chrome.mimeHandler không xác định. Các tiện ích di chuyển từ tính năng chặn yêu cầu mạng có thể kiểm tra API khi khởi động và giữ lại phương pháp hiện có làm phương án dự phòng:

service-worker.js:

if (chrome.mimeHandler) {
  // Chrome routes registered MIME types to the handler page
  // declared in the manifest.
} else {
  // Fall back to network request interception.
}

Ví dụ

Xử lý luồng

Ví dụ sau đây chạy trong trang trình xử lý được khai báo trong tệp kê khai. Thao tác này tìm nạp nội dung của tài liệu và quay lại trình xem tích hợp của Chrome nếu quá trình kết xuất không thành công:

viewer.js:

async function loadDocument() {
  const streamInfo = await chrome.mimeHandler.getStreamInfo();

  // The `embedded` property is true if the document is loaded
  // within an <embed>, <object>, or <iframe> element.
  if (streamInfo.embedded) {
    // Adjust the UI (e.g., hide the top navigation bar).
    document.body.classList.add('embedded-view');
  }

  // Fetch the content using the provided streamUrl. The stream can
  // only be consumed once, so read it fully before continuing.
  const response = await fetch(streamInfo.streamUrl);
  const data = await response.arrayBuffer();

  try {
    // Render the document (e.g., using PDF.js).
    await renderDocument(data);
  } catch (e) {
    // Can't render this document. Fall back to Chrome's built-in
    // viewer; the page unloads and no code runs after this call.
    chrome.mimeHandler.abortAndFallbackToNativeHandler();
  }
}

loadDocument();

Cho phép người dùng bật/tắt tính năng xử lý

Các lựa chọn về trình xử lý được lưu trữ theo từng loại MIME. Ví dụ sau đây sử dụng getMimeHandlerOptions() và setMimeHandlerOptions() để cho phép người dùng tắt tính năng xử lý trên trang tuỳ chọn mà không cần gỡ cài đặt tiện ích. Khi tính năng xử lý bị vô hiệu hoá, các tài liệu thuộc loại đó sẽ không còn được chuyển đến tiện ích của bạn nữa.

options.js:

const checkbox = document.querySelector('#handle-pdfs');

async function initOptions() {
  const options =
      await chrome.mimeHandler.getMimeHandlerOptions('application/pdf');
  // Handling is enabled unless it has been explicitly disabled.
  checkbox.checked = options.enabled !== false;
}

checkbox.addEventListener('change', async () => {
  await chrome.mimeHandler.setMimeHandlerOptions('application/pdf', {
    enabled: checkbox.checked
  });
});

initOptions();

chrome.mimeHandler.abortAndFallbackToNativeHandler(): Promise<void>

chrome.mimeHandler.getMimeHandlerOptions(
  mimeType: string,
): Promise<MimeHandlerOptions>

chrome.mimeHandler.getStreamInfo(): Promise<StreamInfo>

chrome.mimeHandler.setMimeHandlerOptions(
  mimeType: string,
  options: MimeHandlerOptions,
): Promise<void>