browser.mimeHandler

Mô tả

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

Phạm vi cung cấp

Chrome 151 trở lên

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 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 việc chặn yêu cầu mạng để nắm bắt hoạt động điều 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ố hạn chế 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 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. Tài liệu được gửi bằng yêu cầu POST hoặc từ URL sử dụng một lần sẽ hoạt động chính xác.
  • Tiện ích của bạn có thể kết xuất 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 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 các tài liệu chiếm toàn bộ khung: thành phần điều hướng cấp cao nhất và tài liệu được nhúng. Các chính sách này không bao giờ áp dụng cho tài nguyên phụ cùng dòng (ví dụ: phần tử <audio>, <img> hoặc <video>).

Đă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 manifest. Mỗi mục nhập sẽ liên kết một loại MIME với trang tiện ích hiển thị loại đó:

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ả 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 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 dành 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 về sự kiện phát trực tiếp

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. Trên trang trình xử lý, hãy gọi getStreamInfo() để truy xuấ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 bối 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ể 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. 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 sẵn của Chrome, thay vì để người dùng ở lại một trang bị hỏng. Chrome sẽ 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 lưu phản hồi vào vùng đệm 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, thì Chrome sẽ phân phát trình xem tích hợp sẵn từ bản sao được lưu vào vùng đệ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 bằng POST hoặc từ URL sử dụng một lần. Tìm nạp toàn bộ luồng trước khi quyết định xem bạn có thể hiển thị 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, 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à browser.mimeHandler không được 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ữ nguyên phương pháp hiện có làm phương án dự phòng:

service-worker.js:

if (browser.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. Hàm 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 sẵn của Chrome nếu không kết xuất được:

viewer.js:

async function loadDocument() {
  const streamInfo = await browser.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.
    browser.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 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 bạn tắt tính năng xử lý, 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 browser.mimeHandler.getMimeHandlerOptions('application/pdf');
  // Handling is enabled unless it has been explicitly disabled.
  checkbox.checked = options.enabled !== false;
}

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

initOptions();

Loại

MimeHandlerOptions

Thuộc tính

  • canEmbed

    boolean không bắt buộc

    Chrome 157 trở lên

    Liệu trình xử lý này có thể được dùng cho các lượt tải được nhúng (iframe, nhúng, đối tượng) hay không. Giá trị mặc định là giá trị can_embed của mục nhập tệp kê khai. Không có hiệu lực khi enabled là false.

  • đang bật

    boolean không bắt buộc

    Liệu trình xử lý này có được bật hay không. Giá trị mặc định là giá trị enabled của mục nhập tệp kê khai.

StreamInfo

Thuộc tính

  • được nhúng

    boolean

    Đúng nếu được tải trong bối 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 đế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ỷ; phương thức gọi không nên thực thi thêm.

Giá trị trả về

  • Promise<void>

getMimeHandlerOptions()

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

Đọc các lựa chọn cho một loại MIME. Mỗi thành viên là giá trị mà tiện ích đặt hoặc giá trị của mục nhập tệp kê khai nếu tiện ích chưa đặt giá trị đó.

Thông số

  • mimeType

    chuỗi

    Loại MIME có các tuỳ chọn để đọc. Đây phải là loại MIME mà tiện ích xử lý thông qua mime_types_handler.

Giá trị trả về

  • Lời hứa được giải quyết bằng các lựa chọn cho loại MIME.

getStreamInfo()

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

Truy xuất thông tin luồng cho bối cảnh trình xử lý MIME hiện tại. Phải được gọi từ 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. Nếu tiện ích chạy ở chế độ ẩn danh phân tách, thì các tuỳ chọn được đặt từ chế độ ẩn danh chỉ áp dụng cho chế độ ẩn danh và kéo dài cho đến khi phiên truy cập ẩn danh kết thúc. Các lựa chọn không được đặt ở chế độ ẩn danh sẽ tuân theo các giá trị được đặt bên ngoài chế độ ẩn danh.

Thông số

  • mimeType

    chuỗi

    Loại MIME cần định cấu hình. Đây phải là loại MIME mà tiện ích xử lý thông qua mime_types_handler.

  • tùy chọn

    MimeHandlerOptions

    Các lựa chọn để thay đổi.

Giá trị trả về

  • Promise<void>

    Lời hứa được thực hiện khi cấu hình đã được thiết lập.