chrome.mimeHandler

Mô tả

Sử dụng API chrome.mimeHandler để xử lý luồng loại MIME trong tiện ích bên thứ ba.

Phạm vi cung cấp

Đang chờ xử lý

Tệp kê khai

Bạn phải khai báo các khoá sau trong tệp kê khai để sử dụng API này.

"mime_types_handler"

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

Trước đây, các tiện ích 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 việc chặn yêu cầu mạng để nắm bắt các lượt chuyển hướng và chuyển hướng người dùng đến trang tiện ích. Việc đăng ký làm trình xử lý MIME giúp tránh một số giới hạn của phương pháp đó:

  • URL gốc 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 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 phân phối theo 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 "Cho phép truy cập vào URL 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 các tài liệu chiếm toàn bộ khung: các lượt chuyển 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ụ: <audio>, <img>, hoặc <video> phần tử).

Đăng ký 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 tệp kê khai . 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ả các tài liệu được nhúng trong các phần tử <embed>, <object> hoặc <iframe>. Nếu bạn bỏ qua, trình xử lý của bạn chỉ nhận được các lượt chuyển hướng cấp cao nhất. Kể từ Chrome 151, application/pdf là loại MIME duy nhất có sẵn cho trình xử lý công khai; việc khai báo 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 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 cho trình xem tích hợp. Trên trang trình xử lý, hãy gọi getStreamInfo() để truy xuất đối tượng StreamInfo. Đối tượng này bao gồm originalUrl mà người dùng đã chuyển hướng đế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 đúng 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, 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 các tài liệu mà trình xử lý đó không thể kết xuất, chẳng hạn như tệp bị hỏng hoặc được bảo vệ bằng mật khẩu. Hãy gọi abortAndFallbackToNativeHandler() để ngừng xử lý tài liệu và chuyển tài liệu đó trở lại trình xem tích hợp của Chrome thay vì để người dùng ở lại trang bị hỏng. 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 đệm phản hồi trong khi trình xử lý của bạn chạy. Nếu phản hồi đã được nhận đầy đủ khi bạn gọi phương thức này, Chrome sẽ phân phát trình xem tích hợp từ bản sao được đệ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. Thao tác này có thể không thành công đối với các tài liệu được phân phối theo yêu cầu 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ó phản hồi đầy đủ.

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

Trong các phiên bản Chrome trước Chrome 151, 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ừ việc chặn yêu cầu mạng có thể kiểm tra API khi khởi động và giữ 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. Ví dụ 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 tuỳ chọn 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ị tắt, 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();

Loại

MimeHandlerOptions

Thuộc tính

  • đang bật

    boolean

    Liệu trình xử lý này có hoạt động cho loại MIME đã cho hay không.

StreamInfo

Thuộc tính

  • được nhúng

    boolean

    True nếu được tải trong ngữ cảnh được nhúng (iframe/embed/object).

  • mimeType

    chuỗi

    Loại MIME của nội dung bị chặn.

  • originalUrl

    chuỗi

    URL gốc mà người dùng đã chuyển hướng đến.

  • responseHeaders

    đối tượng

    Tiêu đề phản hồi HTTP dưới dạng cặp khoá-giá trị.

  • streamUrl

    chuỗi

    URL để tìm nạp dữ liệu luồng.

  • tabId

    số

    Mã thẻ chứa tài liệu.

Phương thức

abortAndFallbackToNativeHandler()

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

Huỷ bỏ quá trình xử lý luồng hiện tại và chuyển nội dung cho trình xử lý gốc của tác nhân người dùng. Sau lệnh gọi này, khung tiện ích sẽ bị huỷ; người gọi không nên mong đợi quá trình thực thi tiếp theo.

Giá trị trả về

  • Promise<void>

getMimeHandlerOptions()

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

Đọc các tuỳ chọn được duy trì cho một loại MIME. Trả về giá trị mặc định (enabled=true) nếu chưa có tuỳ chọn nào được lưu trữ.

Thông số

  • mimeType

    chuỗi

    Loại MIME có các tuỳ chọn cần đọc.

Giá trị trả về

  • Promise được phân giải bằng các tuỳ chọn được duy trì cho loại MIME.

getStreamInfo()

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

Truy xuất thông tin luồng cho ngữ cảnh trình xử lý MIME hiện tại. Phải được gọi trong trang tiện ích trình xử lý MIME.

Giá trị trả về

setMimeHandlerOptions()

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

Đặt các tuỳ chọn cấu hình cho một loại MIME được chỉ định.

Thông số

  • mimeType

    chuỗi

    Loại MIME cần định cấu hình.

  • tùy chọn

    MimeHandlerOptions

    Các tuỳ chọn mới cần sử dụng.

Giá trị trả về

  • Promise<void>

    Promise được phân giải khi cấu hình đã được đặt.