chrome.mimeHandler

Açıklama

Üçüncü taraf uzantılarında MIME türü akışlarını işlemek için chrome.mimeHandler API'yi kullanın.

Kullanılabilirlik

Beklemede

Manifest

Bu API'yi kullanmak için aşağıdaki anahtarlar manifest dosyasında beyan edilmelidir.

"mime_types_handler"

Kavramlar ve kullanım

Geçmişte, belirli belge türlerini (ör. PDF görüntüleyiciler) işleyen üçüncü taraf uzantıları, gezinmeleri yakalamak ve kullanıcıları bir uzantı sayfasına yönlendirmek için ağ isteği yakalamaya dayanı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'si 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 istekleriyle veya tek kullanımlık URL'lerden teslim edilen dokümanlar düzgün ş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şleyicileri 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 değildir.

İşleyici kaydetme

Uzantınızı MIME işleyici olarak kaydetmek için manifest dosyasında "mime_types_handler" anahtarını beyan edin. Her giriş, bir MIME türünü onu oluşturacak 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" öğesini true olarak ayarlayın. Atlanırsa 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'dır. Desteklenmeyen bir MIME türünün bildirilmesi yükleme uyarısına neden olur.

Aynı MIME türü için birden fazla yüklü uzantı kaydedilirse bu türü en son yüklenen uzantı işler. Bu uzantı kaldırılırsa daha önce yüklenen işleyici tekrar etkin hale gelir.

Akış bilgilerini alma

Bir kullanıcı, kayıtlı bir MIME türüne ait bir doküman açtığında Chrome, yerleşik görüntüleyicisi yerine işleyici sayfanızı yükler. İşleyici sayfasından getStreamInfo() işlevini çağırarak StreamInfo nesnesini 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, tam olarak bir kez ve yalnızca uzantınızın kaynağına göre 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örüntülerken originalUrl kullanın.

Yerel işleyiciye geri dönme

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

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

API kullanılabilirliğini işleme

Chrome 151'den önceki Chrome sürümlerinde, "mime_types_handler" bildiren bir uzantı yüklenip çalıştırılmaya devam eder ancak işleyici olarak kaydedilmez ve chrome.mimeHandler tanımlanmamıştır. Ağ isteği yakalamadan geçiş yapan uzantılar, başlangıçta API'yi kontrol edebilir ve mevcut yaklaşımlarını yedek olarak kullanmaya devam edebilir:

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

Örnekler

Akışı işleme

Aşağıdaki örnek, manifest'te belirtilen işleyici sayfasında çalışır. Belgenin 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 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();

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

İş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şleme özelliğini kapatmasına olanak tanımak için getMimeHandlerOptions() ve setMimeHandlerOptions() kullanılmaktadır. İşleme devre dışıyken bu türdeki dokümanlar artık uzantınıza yönlendirilmez.

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

Türler

MimeHandlerOptions

Özellikler

  • etkin

    boole

    Bu işleyicinin, verilen MIME türü için etkin olup olmadığı.

StreamInfo

Özellikler

  • yerleştirilmiş

    boole

    Yerleştirilmiş bir bağlamda (iframe/embed/object) yüklenmişse doğru değerini döndürür.

  • mimeType

    dize

    Engellenen içeriğin MIME türü.

  • originalUrl

    dize

    Kullanıcının gittiği orijinal URL.

  • responseHeaders

    nesne

    Anahtar/değer çiftleri olarak HTTP yanıt başlıkları.

  • streamUrl

    dize

    Akış verilerinin getirileceği URL.

  • tabId

    sayı

    Belgeyi içeren sekmenin kimliği.

Yöntemler

abortAndFallbackToNativeHandler()

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

Mevcut akış işleme işlemini durdurur ve içeriği kullanıcı aracısının yerel işleyicisine devreder. Bu çağrıdan sonra uzantı çerçevesi kapatılır. Arayanlar başka bir yürütme işlemi beklememelidir.

İadeler

  • Promise<void>

getMimeHandlerOptions()

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

Bir MIME türü için kalıcı seçenekleri okur. Hiçbiri depolanmamışsa varsayılan değerleri (etkin=doğru) döndürür.

Parametreler

  • mimeType

    dize

    Okunacak seçeneklerin MIME türü.

İadeler

getStreamInfo()

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

Mevcut MIME işleyici bağlamı için akış bilgilerini alır. Bir MIME işleyici uzantısı sayfasından çağrılmalıdır.

İadeler

setMimeHandlerOptions()

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

Belirtilen bir MIME türü için yapılandırma seçeneklerini ayarlar.

Parametreler

  • mimeType

    dize

    Yapılandırılacak MIME türü.

  • seçenekler

    MimeHandlerOptions

    Kullanılacak yeni seçenekler.

İadeler

  • Promise<void>

    Yapılandırma ayarlandığında söz çözülür.