chrome.mimeHandler

설명

가용성

매니페스트

개념 및 사용

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

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

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

핸들러 등록

확장 프로그램을 MIME 핸들러로 등록하려면 매니페스트에서 "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부터 application/pdf는 공개 핸들러에서 사용할 수 있는 유일한 MIME 유형입니다. 지원되지 않는 MIME 유형을 선언하면 설치 경고가 표시됩니다.

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

스트림 정보 가져오기

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

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

네이티브 핸들러로 대체

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

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

API 사용 가능 여부 처리

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

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

예

스트림 처리

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

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

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

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

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>