browser.mimeHandler

설명

가용성

매니페스트

개념 및 사용법

이전에는 특정 문서 유형을 처리하는 서드 파티 확장 프로그램 (예: PDF 뷰어)이 네트워크 요청 가로채기를 사용하여 탐색을 포착하고 사용자를 확장 프로그램 페이지로 리디렉션했습니다. MIME 핸들러로 등록하면 이 접근 방식의 몇 가지 제한사항을 피할 수 있습니다.

• 원래 URL이 chrome-extension:// URL로 대체되지 않고 주소 표시줄에 그대로 유지됩니다.
• 확장 프로그램은 두 번째 네트워크 요청을 하는 대신 Chrome에서 이미 수신한 응답을 가져옵니다. POST 요청 또는 일회용 URL로 전송된 문서는 올바르게 작동합니다.
• 확장 프로그램은 <embed>, <object> 또는 <iframe> 요소 내에 로드된 문서를 렌더링할 수 있습니다.
• 로컬 파일 (file:// URL)은 사용자가 확장 프로그램 설정에서 '파일 URL에 대한 액세스 허용'을 수동으로 사용 설정하지 않아도 작동합니다.

MIME 핸들러는 전체 프레임을 차지하는 문서(최상위 탐색 및 삽입된 문서)에만 적용됩니다. 인라인 하위 리소스 (예: <audio>, <img> 또는 <video> 요소)에는 적용되지 않습니다.

핸들러 등록

확장 프로그램을 MIME 핸들러로 등록하려면 manifest에서 "mime_types_handler" 키를 선언합니다. 각 항목은 MIME 유형을 렌더링하는 확장 프로그램 페이지에 매핑합니다.

manifest.json:

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

"can_embed"을 true로 설정하여 <embed>, <object> 또는 <iframe> 요소에 삽입된 문서도 처리합니다. 생략하면 핸들러는 최상위 탐색만 수신합니다. Chrome 151부터 공개 핸들러에서 사용할 수 있는 MIME 유형은 application/pdf뿐입니다. 지원되지 않는 MIME 유형을 선언하면 설치 경고가 표시됩니다.

설치된 확장 프로그램이 두 개 이상 동일한 MIME 유형에 등록된 경우 가장 최근에 설치된 확장 프로그램이 이를 처리합니다. 해당 확장 프로그램이 제거되면 이전에 설치된 핸들러가 다시 활성화됩니다.

스트림 정보 검색

사용자가 등록된 MIME 유형의 문서를 열면 Chrome은 내장 뷰어 대신 핸들러 페이지를 로드합니다. 핸들러 페이지에서 getStreamInfo()를 호출하여 StreamInfo 객체를 가져옵니다. 여기에는 사용자가 탐색한 originalUrl, HTTP responseHeaders, 문서가 embedded 컨텍스트에 로드되었는지 여부, 문서의 콘텐츠를 가져오는 데 사용할 수 있는 streamUrl가 포함됩니다.

streamUrl는 정확히 한 번만 가져올 수 있으며 확장 프로그램의 출처에서만 가져올 수 있습니다. 응답을 처리하기 전에 완전히 읽습니다. 동일한 streamUrl의 두 번째 가져오기는 실패합니다. 원본 요청을 반복할 수 없으므로 콘텐츠를 가져오지 않고 문서의 위치 또는 제목을 표시할 때 originalUrl를 사용합니다.

네이티브 핸들러로 대체

핸들러에서 손상되거나 비밀번호로 보호된 파일과 같이 렌더링할 수 없는 문서를 발견할 수 있습니다. abortAndFallbackToNativeHandler()를 호출하여 문서 처리를 중지하고 사용자를 손상된 페이지에 남겨두는 대신 Chrome의 기본 제공 뷰어로 다시 전달합니다. Chrome은 대체 동작의 일부로 핸들러 페이지를 언로드합니다. 이 호출 후에는 코드가 실행되지 않습니다.

핸들러가 실행되는 동안 Chrome은 응답을 버퍼링합니다. 이 메서드를 호출할 때 응답이 완전히 수신된 경우 Chrome은 새 네트워크 요청 없이 버퍼링된 사본에서 기본 제공 뷰어를 제공합니다. 그렇지 않으면 Chrome이 네트워크에서 문서를 새로고침하며, POST로 전송되거나 일회용 URL에서 전송된 문서의 경우 새로고침이 실패할 수 있습니다. 렌더링할 수 있는지 결정하기 전에 스트림을 완전히 가져옵니다. streamUrl 가져오기가 완료되면 Chrome에 전체 응답이 표시됩니다.

API 사용 가능 여부 처리

Chrome 151 이전 버전의 Chrome에서는 "mime_types_handler"를 선언하는 확장 프로그램이 계속 설치되고 실행되지만 핸들러로 등록되지 않으며 browser.mimeHandler가 정의되지 않습니다. 네트워크 요청 가로채기에서 이전하는 확장 프로그램은 시작 시 API를 확인하고 기존 접근 방식을 대체 수단으로 유지할 수 있습니다.

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.
}

예

스트림 처리

다음 예는 매니페스트에 선언된 핸들러 페이지에서 실행됩니다. 문서의 콘텐츠를 가져오고 렌더링에 실패하면 Chrome의 내장 뷰어로 대체됩니다.

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();

사용자가 처리 전환하도록 허용

핸들러 옵션은 MIME 유형별로 저장됩니다. 다음 예에서는 getMimeHandlerOptions() 및 setMimeHandlerOptions()를 사용하여 사용자가 확장 프로그램을 제거하지 않고도 옵션 페이지에서 처리를 사용 중지할 수 있도록 합니다. 처리가 사용 중지되면 해당 유형의 문서가 더 이상 확장 프로그램으로 라우팅되지 않습니다.

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();

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>