browser.devtools.inspectedWindow

Açıklama

İncelenen pencereyle etkileşim kurmak için chrome.devtools.inspectedWindow API'yi kullanın: İncelenen sayfanın sekme kimliğini alın, kodu incelenen pencere bağlamında değerlendirin, sayfayı yeniden yükleyin veya sayfadaki kaynakların listesini alın.

Geliştirici Araçları API'lerinin kullanımına genel bir giriş için Geliştirici Araçları API'leri özeti bölümüne bakın.

tabId özelliği, browser.tabs.* API çağrılarıyla kullanabileceğiniz sekme tanımlayıcısını sağlar. Ancak güvenlik nedeniyle browser.tabs.* API'si, Geliştirici Araçları uzantı sayfalarına gösterilmez. Sekme kimliğini arka plan sayfasına iletmeniz ve browser.tabs.* API işlevlerini buradan çağırmanız gerekir.

İncelenen sayfayı yeniden yüklemek için reload yöntemi kullanılabilir. Ayrıca, arayan kişi kullanıcı aracısı dizesi için bir geçersiz kılma, sayfa yüklenirken erken enjekte edilecek bir komut dosyası veya önbelleğe alınmış kaynakların yeniden yüklenmesini zorunlu kılacak bir seçenek belirtebilir.

İncelenen sayfadaki kaynakların (dokümanlar, stil sayfaları, komut dosyaları, resimler vb.) listesini almak için getResources çağrısını ve onResourceContent etkinliğini kullanın. Resource sınıfının getContent ve setContent yöntemleri, onResourceContentCommitted etkinliğiyle birlikte kaynak içeriğinin değiştirilmesini (ör. harici bir düzenleyici tarafından) desteklemek için kullanılabilir.

Manifest

Bu API'yi kullanmak için aşağıdaki anahtarların manifest dosyasında tanımlanması gerekir.

"devtools_page"

Kodu incelenen pencerede yürütme

eval yöntemi, uzantıların denetlenen sayfa bağlamında JavaScript kodu yürütmesine olanak tanır. Bu yöntem, doğru bağlamda kullanıldığında güçlü, uygunsuz şekilde kullanıldığında ise tehlikelidir. eval yönteminin sağladığı belirli bir işleve ihtiyacınız yoksa tabs.executeScript yöntemini kullanın.

eval ve tabs.executeScript yöntemleri arasındaki temel farklar şunlardır:

  • eval yöntemi, değerlendirilen kod için izole bir dünya kullanmaz. Bu nedenle, incelenen pencerenin JavaScript durumu koda erişebilir. İncelenen sayfanın JavaScript durumuna erişim gerektiğinde bu yöntemi kullanın.
  • Değerlendirilen kodun yürütme bağlamı, Geliştirici Araçları konsol API'sini içerir. Örneğin, kod inspect ve $0 kullanabilir.
  • Değerlendirilen kod, uzantı geri çağırmasına iletilen bir değer döndürebilir. Döndürülen değer, geçerli bir JSON nesnesi olmalıdır (yalnızca temel JavaScript türlerini ve diğer JSON nesnelerine döngüsel olmayan referansları içerebilir). İncelenen sayfadan alınan verileri işlerken lütfen daha dikkatli olun. Yürütme bağlamı, incelenen sayfa tarafından kontrol edilir. Kötü amaçlı bir sayfa, uzantıya döndürülen verileri etkileyebilir.

Bir sayfanın birden fazla farklı JavaScript yürütme bağlamı içerebileceğini unutmayın. Her karenin kendi bağlamı ve bu karede içerik komut dosyaları çalıştıran her uzantı için ek bir bağlamı vardır.

Varsayılan olarak eval yöntemi, incelenen sayfanın ana çerçevesi bağlamında yürütülür.

eval yöntemi, kodun değerlendirildiği bağlamı belirtmek için kullanabileceğiniz isteğe bağlı ikinci bir bağımsız değişken alır. Bu options nesnesi aşağıdaki anahtarlardan birini veya daha fazlasını içerebilir:

frameURL
İncelenen sayfanın ana çerçevesi dışında bir çerçeve belirtmek için kullanılır.
contextSecurityOrigin
Belirtilen çerçeve içindeki bir bağlamı web kaynağına göre seçmek için kullanılır.
useContentScriptContext
Doğru ise komut dosyasını uzantının içerik komut dosyalarıyla aynı bağlamda yürütün. (Uzantının kendi web kaynağını bağlam güvenlik kaynağı olarak belirtmeye eşdeğerdir.) Bu, içerik komut dosyasıyla veri alışverişi yapmak için kullanılabilir.

Örnekler

Aşağıdaki kod, denetlenen sayfa tarafından kullanılan jQuery sürümünü kontrol eder:

browser.devtools.inspectedWindow.eval(
  "jQuery.fn.jquery",
  function(result, isException) {
    if (isException) {
      console.log("the page is not using jQuery");
    } else {
      console.log("The page is using jQuery v" + result);
    }
  }
);

Bu API'yi denemek için chrome-extension-samples deposundan devtools API örneklerini yükleyin.

Türler

Resource

İncelenen sayfadaki bir kaynak (ör. doküman, komut dosyası veya resim).

Özellikler

  • url

    dize

    Kaynağın URL'si.

  • getContent

    geçersiz

    Kaynağın içeriğini alır.

    getContent işlevi şu şekildedir: 

    () => {...}

    • returns

      Promise<object>

      Chrome 151 ve sonraki sürümler Chrome 152'den itibaren browser.*

      İstek tamamlandığında kaynak içeriğini alan bir işlev.

  • setContent

    geçersiz

    Kaynağın içeriğini ayarlar.

    setContent işlevi şu şekildedir: 

    (content: string, commit: boolean) => {...}

    • içerik

      dize

      Kaynağın yeni içeriği. Şu anda yalnızca metin türündeki kaynaklar desteklenmektedir.

    • commit

      boole

      Kullanıcı kaynağı düzenlemeyi bitirdiyse ve kaynağın yeni içeriği kalıcı hale getirilecekse "true" (doğru); bu, kullanıcı kaynağı düzenlerken gönderilen küçük bir değişiklikse "false" (yanlış) değerini alır.

    • returns

      Promise<object>

      Chrome 151 ve sonraki sürümler Chrome 152'den itibaren browser.*

      İstek tamamlandığında çağrılan bir işlev.

Özellikler

tabId

İncelenen sekmenin kimliği. Bu kimlik, chrome.tabs.* ile kullanılabilir. API.

Tür

sayı

Yöntemler

eval()

browser.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
): Promise<object>

İncelenen sayfanın ana çerçevesi bağlamında bir JavaScript ifadesini değerlendirir. İfade, JSON uyumlu bir nesne olarak değerlendirilmelidir. Aksi takdirde bir istisna oluşturulur. eval işlevi, değerlendirme sırasında oluşan bir Geliştirici Araçları tarafı hatasını veya JavaScript istisnasını bildirebilir. Her iki durumda da geri çağırmanın result parametresi undefined olur. Geliştirici Araçları tarafında bir hata olması durumunda isException parametresi boş olmaz ve isError "true" değerine, code ise bir hata koduna ayarlanır. JavaScript hatası durumunda isException, true olarak ayarlanır ve value, oluşturulan nesnenin dize değerine ayarlanır.

Parametreler

  • ifade

    dize

    Değerlendirilecek ifade.

  • seçenekler

    isteğe bağlı nesne

    Seçenekler parametresi bir veya daha fazla seçenek içerebilir.

    • frameURL

      string isteğe bağlı

      Belirtilirse ifade, URL'si belirtilen URL ile eşleşen iframe'de değerlendirilir. Varsayılan olarak ifade, incelenen sayfanın üst çerçevesinde değerlendirilir.

    • scriptExecutionContext

      string isteğe bağlı

      Chrome 107 ve sonraki sürümler Chrome 152'den itibaren browser.*

      İfadeyi, belirtilen kaynakla eşleşen bir uzantının içerik komut dosyası bağlamında değerlendirin. Belirtilirse scriptExecutionContext, useContentScriptContext'teki "true" ayarını geçersiz kılar.

    • useContentScriptContext

      boole isteğe bağlı

      İçerik komut dosyasının incelenen sayfaya zaten yerleştirilmiş olması koşuluyla, ifadeyi çağıran uzantının içerik komut dosyası bağlamında değerlendirin. Aksi takdirde ifade değerlendirilmez ve geri çağırma, isError alanı true, code alanı ise E_NOTFOUND olarak ayarlanmış bir nesneye ayarlanmış istisna parametresiyle çağrılır.

İadeler

  • Promise<object>

    Chrome 151 ve sonraki sürümler Chrome 152'den itibaren browser.*

    Değerlendirme tamamlandığında çağrılan bir işlev.

getResources()

browser.devtools.inspectedWindow.getResources(): Promise<Resource[]>

İncelenen sayfadaki kaynakların listesini alır.

İadeler

  • Promise<Resource[]>

    Chrome 151 ve sonraki sürümler Chrome 152'den itibaren browser.*

    İstek tamamlandığında kaynak listesini alan bir işlev.

reload()

browser.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

İncelenen sayfayı yeniden yükler.

Parametreler

  • reloadOptions

    isteğe bağlı nesne

    • ignoreCache

      boole isteğe bağlı

      Doğru olduğunda yükleyici, load etkinliği tetiklenmeden önce yüklenen tüm denetlenen sayfa kaynakları için önbelleği atlar. Bu işlem, denetlenen pencerede veya Geliştirici Araçları penceresinde Ctrl+Üst Karakter+R tuşlarına basmaya benzer.

    • injectedScript

      string isteğe bağlı

      Belirtilirse komut dosyası, yükleme sırasında hemen incelenen sayfanın her karesine, karenin komut dosyalarından önce eklenir. Komut dosyası, sonraki yeniden yüklemelerden sonra (ör. kullanıcı Ctrl+R tuşlarına basarsa) eklenmez.

    • userAgent

      string isteğe bağlı

      Belirtilirse dize, incelenen sayfanın kaynakları yüklenirken gönderilen User-Agent HTTP üstbilgisinin değerini geçersiz kılar. Dize, incelenen sayfada çalışan komut dosyalarına döndürülen navigator.userAgent özelliğinin değerini de geçersiz kılar.

Etkinlikler

onResourceAdded

browser.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

İncelenen sayfaya yeni bir kaynak eklendiğinde tetiklenir.

Parametreler

  • callback

    işlev

    callback parametresi şu şekilde görünür: 

    (resource: Resource) => void

onResourceContentCommitted

browser.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

Kaynağın yeni bir düzeltmesi kaydedildiğinde (ör. kullanıcı, kaynağın düzenlenmiş bir sürümünü Geliştirici Araçları'na kaydettiğinde) tetiklenir.

Parametreler

  • callback

    işlev

    callback parametresi şu şekilde görünür: 

    (resource: Resource, content: string) => void