說明
使用 chrome.mimeHandler API 處理第三方擴充功能中的 MIME 類型串流。
可用性
資訊清單
概念和用途
過去，處理特定文件類型 (例如 PDF 檢視器) 的第三方擴充功能會攔截網路要求，以擷取導覽並將使用者重新導向至擴充功能頁面。註冊為 MIME 處理常式可避免該方法的幾項限制：
- 原始網址會保留在網址列中，不會由
chrome-extension://網址取代。 - 擴充功能會擷取 Chrome 已收到的回應，而不是發出第二個網路要求。透過 POST 要求或單次使用網址傳送的文件可正常運作。
- 擴充功能可以轉譯
<embed>、<object>或<iframe>元素中載入的文件。 - 使用者不必在擴充功能設定中手動啟用「允許存取檔案網址」，即可使用本機檔案 (
file://網址)。
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，而非擷取內容，因為原始要求可能無法重複。
改用原生處理常式
處理常式可能會遇到無法轉譯的文件，例如毀損或受密碼保護的檔案。呼叫 abortAndFallbackToNativeHandler() 停止處理文件，並將文件交還給 Chrome 的內建檢視器，而不是讓使用者停留在損毀的頁面上。Chrome 會卸載處理常式頁面做為備援機制的一部分；此呼叫後不會執行任何程式碼。
Chrome 會在處理常式執行時緩衝處理回應。如果您在完整收到回應時呼叫這個方法，Chrome 會從緩衝副本提供內建檢視器，而不會發出新的網路要求。否則，Chrome 會從網路重新載入文件，但這可能會失敗，因為文件是透過 POST 或單次使用的網址傳送。請先完整擷取串流，再決定是否可以轉譯；擷取 streamUrl 完成後，Chrome 就會取得完整的回應。
處理 API 適用性
在 Chrome 151 之前的 Chrome 版本中，宣告 "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();
類型
MimeHandlerOptions
屬性
-
已啟用
布林值
這個處理常式是否適用於指定的 MIME 類型。
StreamInfo
屬性
-
嵌入
布林值
如果載入嵌入式環境 (iframe/embed/object)，則為 True。
-
mimeType
字串
攔截內容的 MIME 類型。
-
originalUrl
字串
使用者前往的原始網址。
-
responseHeaders
物件
HTTP 回應標頭，以鍵/值組合形式表示。
-
streamUrl
字串
要從中擷取串流資料的網址。
-
tabId
數字
包含文件的分頁 ID。
方法
abortAndFallbackToNativeHandler()
chrome.mimeHandler.abortAndFallbackToNativeHandler(): Promise<void>
中止目前的串流處理作業，並將內容交給使用者代理程式的原生處理常式。呼叫這個方法後，擴充功能影格就會遭到拆解，呼叫端不應預期後續執行作業。
傳回
-
Promise<void>
getMimeHandlerOptions()
chrome.mimeHandler.getMimeHandlerOptions(
mimeType: string,
): Promise<MimeHandlerOptions>
讀取 MIME 類型的持續性選項。如果沒有儲存任何預設值，則傳回預設值 (enabled=true)。
參數
-
mimeType
字串
要讀取選項的 MIME 類型。
傳回
-
Promise<MimeHandlerOptions>
Promise 會以 MIME 類型的持續性選項解析。
getStreamInfo()
chrome.mimeHandler.getStreamInfo(): Promise<StreamInfo>
擷取目前 MIME 處理常式環境的串流資訊。必須從 MIME 處理常式擴充功能頁面內呼叫。
傳回
-
Promise<StreamInfo>
setMimeHandlerOptions()
chrome.mimeHandler.setMimeHandlerOptions(
mimeType: string,
options: MimeHandlerOptions,
): Promise<void>
為指定的 MIME 類型設定設定選項。
參數
-
mimeType
字串
要設定的 MIME 類型。
-
可用的新選項。
傳回
-
Promise<void>
設定完成後，系統會解析 Promise。