chrome.devtools.inspectedWindow

Açıklama

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

Manifest

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

"devtools_page"

İncelenen pencereyle etkileşim kurmak için chrome.devtools.inspectedWindow simgesini 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'lerini kullanmaya ilişkin genel bir giriş için Geliştirici Araçları API'lerine genel bakış başlıklı makaleyi inceleyin.

Genel Bakış

tabId özelliği, chrome.tabs.* API çağrılarıyla kullanabileceğiniz sekme tanımlayıcısını sağlar. Ancak, güvenlik nedeniyle chrome.tabs.* API'nin geliştirici araçları uzantı sayfalarına sunulmadığını lütfen unutmayın. Sekme kimliğini arka plan sayfasına iletmeniz ve chrome.tabs.* API işlevlerini buradan çağırmanız gerekir.

Denetlenen sayfayı yeniden yüklemek için reload yöntemi kullanılabilir. Ayrıca, arayan kullanıcı aracısı dizesi için geçersiz kılma, sayfa yüklendiğinde erken enjekte edilecek bir komut dosyası veya önbelleğe alınmış kaynakların yeniden yüklenmesini zorlama seçeneği belirtebilir.

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

İncelenen Pencerede Kod Yürütme

eval yöntemi, uzantıların incelenen 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 kullanıldığında ise tehlikelidir. eval yönteminin sağladığı belirli işlevselliğe ihtiyacınız olmadığı sürece 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 yalıtılmış bir dünya kullanmaz. Bu nedenle, incelenen pencerenin JavaScript durumu koda erişilebilir. İ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, kodda inspect ve $0 kullanılabilir.
  • 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 yönelik döngüsüz referansları içerebilir). Lütfen incelenen sayfadan alınan verileri işlerken ekstra dikkatli olun. Yürütme bağlamı esasen 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 çerçevenin kendi bağlamı vardır. Ayrıca, bu çerçevede içerik komut dosyaları çalıştıran her uzantı için ek bir bağlam bulunur.

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ğruysa komut dosyasını uzantıların içerik komut dosyalarıyla aynı bağlamda yürütün. (Uzantının kendi web kaynağını bağlam güvenliği 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, incelenen sayfa tarafından kullanılan jQuery sürümünü kontrol eder:

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

    Promise

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

    getContent işlevi şu şekilde görünür: 

    (callback?: function) => {...}

    • callback

      işlev isteğe bağlı

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

      (response: object) => void

      • gönderin

        nesne

        Beklemede

        Kaynak içeriğini ve kodlamasını içeren bir nesne.

        • içerik

          dize

          Kaynağın içeriği (kodlanmış olabilir).

        • kodlama

          dize

          İçerik kodlanmamışsa boş, aksi takdirde kodlama adı. Şu anda yalnızca base64 desteklenmektedir.

    • returns

      Promise<object>

      Beklemede

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

      Promises yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdır.

  • setContent

    geçersiz

    Promise

    Kaynağın içeriğini ayarlar.

    setContent işlevi şu şekilde görünür: 

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

    • 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ğinin kalıcı olması gerekiyorsa true, kullanıcının kaynağı düzenleme işlemi devam ederken gönderilen küçük bir değişiklikse false.

    • callback

      işlev isteğe bağlı

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

      (error?: object) => void

      • hata

        object isteğe bağlı

        Kaynak içeriği başarıyla ayarlandıysa undefined olarak ayarlanır, aksi takdirde hatayı açıklar.

    • returns

      Promise<object>

      Beklemede

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

      Promises yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdır.

Özellikler

tabId

İncelenen sekmenin kimliği. Bu kimlik, chrome.tabs.* ile kullanılabilir. API'yi seçin.

Tür

sayı

Yöntemler

eval()

Promise 
chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): 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 istisna oluşturulur. eval işlevi, değerlendirme sırasında oluşan bir DevTools tarafı hatası veya JavaScript istisnası 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ş olmayan bir değerdir ve isError değeri doğru, code değeri ise bir hata kodu olarak ayarlanır. JavaScript hatası durumunda isException değeri doğru, value değeri ise oluşturulan nesnenin dize değeri olarak ayarlanır.

Parametreler

  • ifade

    dize

    Değerlendirilecek ifade.

  • seçenekler

    object isteğe bağlı

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

    • frameURL

      dize isteğe bağlı

      Belirtilmişse ifade, URL'si belirtilenle eşleşen iframe'de değerlendirilir. İfade varsayılan olarak incelenen sayfanın üst çerçevesinde değerlendirilir.

    • scriptExecutionContext

      dize isteğe bağlı

      Chrome 107 ve sonraki sürümler

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

    • useContentScriptContext

      boolean isteğe bağlı

      İçerik komut dosyası, incelenen sayfaya zaten yerleştirilmişse 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 nesneyle çağrılır.

  • callback

    işlev isteğe bağlı

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

    (response: object) => void

    • gönderin

      nesne

      Beklemede

      Değerlendirme sonucu ve istisna bilgileri.

      • exceptionInfo

        nesne

        İfade değerlendirilirken bir istisna oluştuysa ayrıntıları sağlayan bir nesne.

        • kod

          dize

          İfade değerlendirilmeden önce hatanın Geliştirici Araçları tarafında oluşup oluşmadığını ayarlar.

        • açıklama

          dize

          İfade değerlendirilmeden önce hatanın Geliştirici Araçları tarafında oluşup oluşmadığını ayarlar.

        • ayrıntılar

          any[]

          Hatanın, ifade değerlendirilmeden önce Geliştirici Araçları tarafında oluşup oluşmadığını ayarlar. Hatanın nedeni hakkında daha fazla bilgi sağlamak için açıklama dizesine eklenebilecek değerler dizisini içerir.

        • isError

          boole

          İfade değerlendirilmeden önce hatanın Geliştirici Araçları tarafında oluşup oluşmadığını ayarlar.

        • isException

          boole

          Değerlendirilen kodun işlenmemiş bir istisna oluşturup oluşturmadığını ayarlayın.

        • value

          dize

          Değerlendirilen kodun işlenmemiş bir istisna oluşturup oluşturmadığını ayarlayın.

      • sonuç

        nesne

        Değerlendirme sonucu.

İadeler

  • Promise<object>

    Beklemede

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

    Promises yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdır.

getResources()

Promise 
chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

Denetlenen sayfadaki kaynakların listesini alır.

Parametreler

  • callback

    işlev isteğe bağlı

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

    (resources: Resource[]) => void

    • kaynaklarımızdan

      Kaynak[]

      Sayfadaki kaynaklar.

İadeler

  • Promise<Resource[]>

    Beklemede

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

    Promises yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformlarda geri çağırmalar kullanılmalıdır.

reload()

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

Denetlenen sayfayı yeniden yükler.

Parametreler

  • reloadOptions

    object isteğe bağlı

    • ignoreCache

      boolean isteğe bağlı

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

    • injectedScript

      dize isteğe bağlı

      Belirtilirse komut dosyası, incelenen sayfanın her çerçevesine yüklenir yüklenmez, çerçevenin komut dosyalarından önce yerleştirilir. Kullanıcı Ctrl+R tuşlarına bastığında olduğu gibi, sonraki yeniden yüklemelerde komut dosyası eklenmez.

    • userAgent

      dize isteğe bağlı

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

Etkinlikler

onResourceAdded

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

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