browser.mimeHandler

Açıklama

Kullanılabilirlik

Manifest

Kavramlar ve kullanım

Geçmişte, belirli doküman türlerini işleyen üçüncü taraf uzantıları (ör. PDF görüntüleyiciler), gezinmeleri yakalamak ve kullanıcıları bir uzantı sayfasına yönlendirmek için ağ isteği müdahalesini kullanıyordu. MIME işleyici olarak kaydolmak, bu yaklaşımın çeşitli sınırlamalarını ortadan kaldırır:

• Orijinal URL, chrome-extension:// URL ile değiştirilmek yerine adres çubuğunda kalır.
• Uzantınız, ikinci bir ağ isteği göndermek yerine Chrome'un zaten aldığı yanıtı getirir. POST istekleri veya tek kullanımlık URL'ler tarafından gönderilen belgeler doğru şekilde çalışır.
• Uzantınız, <embed>, <object> veya <iframe> öğelerine yüklenen dokümanları oluşturabilir.
• Yerel dosyalar (file:// URL'leri), kullanıcının uzantı ayarlarında "Dosya URL'lerine erişime izin ver" seçeneğini manuel olarak etkinleştirmesine gerek kalmadan çalışır.

MIME işleyiciler yalnızca bir çerçevenin tamamını kaplayan dokümanlar (üst düzey gezinmeler ve yerleştirilmiş dokümanlar) için geçerlidir. Satır içi alt kaynaklar (ör. <audio>, <img> veya <video> öğeleri) için hiçbir zaman geçerli olmazlar.

İşleyici kaydetme

Uzantınızı MIME işleyici olarak kaydetmek için manifest dosyasında "mime_types_handler" anahtarını tanımlayın. Her giriş, bir MIME türünü, bu türü oluşturan uzantı sayfasına eşler:

manifest.json:

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

<embed>, <object> veya <iframe> öğelerine yerleştirilmiş dokümanları da işlemek için "can_embed" değerini true olarak ayarlayın. Bu parametre belirtilmezse işleyiciniz yalnızca üst düzey gezinmeleri alır. Chrome 151'den itibaren, herkese açık işleyiciler için kullanılabilen tek MIME türü application/pdf'dir. Desteklenmeyen bir MIME türü beyan edildiğinde yükleme uyarısı gösterilir.

Yüklü birden fazla uzantı aynı MIME türü için kaydolursa en son yüklenen uzantı bu türü işler. Bu uzantı kaldırılırsa daha önce yüklenen işleyici tekrar etkinleşir.

Yayın bilgilerini alma

Bir kullanıcı kayıtlı bir MIME türünde doküman açtığında Chrome, yerleşik görüntüleyicisi yerine işleyici sayfanızı yükler. İşleyici sayfasından getStreamInfo() yöntemini çağırarak bir StreamInfo nesnesi alın. Buna, kullanıcının gittiği originalUrl, HTTP responseHeaders, dokümanın embedded bağlamında yüklenip yüklenmediği ve dokümanın içeriğini getirmek için kullanılabilecek bir streamUrl dahildir.

streamUrl yalnızca bir kez ve yalnızca uzantınızın kaynağından getirilebilir. Yanıtı işlemeden önce tamamen okuyun. Aynı streamUrl için ikinci bir getirme işlemi başarısız olur. Orijinal istek tekrarlanamayabileceğinden, içeriği getirmek için değil, dokümanın konumunu veya başlığını gösterirken originalUrl kullanın.

Yerel işleyiciye geri dönme

İşleyiciniz, bozuk veya şifre korumalı dosyalar gibi oluşturamayacağı dokümanlarla karşılaşabilir. Kullanıcıyı bozuk bir sayfada bırakmak yerine, dokümanı işlemeyi durdurmak ve Chrome'un yerleşik görüntüleyicisine geri vermek için abortAndFallbackToNativeHandler() yöntemini çağırın. Chrome, yedek işlemin bir parçası olarak işleyici sayfanızı kaldırır. Bu çağrıdan sonra hiçbir kod çalıştırılmaz.

İşleyiciniz çalışırken Chrome, yanıtı arabelleğe alır. Bu yöntemi çağırdığınızda yanıt tamamen alınmışsa Chrome, yeni bir ağ isteği olmadan yerleşik görüntüleyiciyi arabelleğe alınmış kopyadan sunar. Aksi takdirde Chrome, dokümanı ağdan yeniden yükler. Bu işlem, POST tarafından veya tek kullanımlık URL'lerden gönderilen dokümanlar için başarısız olabilir. Akışı oluşturup oluşturamayacağınıza karar vermeden önce akışı tamamen getirin. streamUrl getirme işleminiz tamamlandığında Chrome tam yanıta sahip olur.

API kullanılabilirliğini yönetme

Chrome 151'den önceki Chrome sürümlerinde, "mime_types_handler" beyan eden bir uzantı yine de yüklenir ve çalışır ancak işleyici olarak kaydedilmez ve browser.mimeHandler tanımlanmaz. Ağ isteği müdahalesinden geçiş yapan uzantılar, başlangıçta API'yi kontrol edebilir ve mevcut yaklaşımlarını yedek olarak kullanabilir:

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

Örnekler

Akışları işleme

Aşağıdaki örnek, manifest dosyasında belirtilen işleyici sayfasında çalışır. Dokümanın içeriğini getirir ve oluşturma başarısız olursa Chrome'un yerleşik görüntüleyicisine geri döner:

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

Kullanıcıların işlemeyi açıp kapatmasına izin ver

İşleyici seçenekleri MIME türüne göre depolanır. Aşağıdaki örnekte, kullanıcıların uzantıyı kaldırmadan seçenekler sayfasından işlemeyi devre dışı bırakmasına olanak tanımak için getMimeHandlerOptions() ve setMimeHandlerOptions() kullanılmıştır. İşleme devre dışı bırakıldığında, bu türdeki belgeler artık uzantınıza yönlendirilmez.

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

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

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

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

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