chrome.debugger

Açıklama

chrome.debugger API, Chrome'un uzaktan hata ayıklama protokolü için alternatif bir aktarım işlevi görür. Ağ etkileşimini değerlendirmek, JavaScript'te hata ayıklamak, DOM ve CSS'yi değiştirmek vb. için bir veya daha fazla sekmeye ekleme yapmak üzere chrome.debugger kullanın.tabIdtabId

İzinler

debugger

Bu API'yi kullanmak için uzantınızın manifest dosyasında "debugger" iznini beyan etmeniz gerekir.

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

Kavramlar ve kullanım

Eklendikten sonra chrome.debugger API, belirli bir hedefe Chrome Geliştirici Araçları Protokolü (CDP) komutlarını gönderebilmenizi sağlar. CDP'nin ayrıntılı olarak açıklanması bu dokümanın kapsamı dışındadır. CDP hakkında daha fazla bilgi edinmek için resmi CDP belgelerine bakın.

Hedefler

Hedefler, hata ayıklaması yapılan bir öğeyi temsil eder. Bu öğelere bir sekme, bir iframe veya bir çalışan dahil olabilir. Her hedef bir UUID ile tanımlanır ve ilişkilendirilmiş bir türe (ör. iframe, shared_worker ve daha fazlası) sahiptir.

Bir hedef içinde birden çok yürütme bağlamı olabilir. Örneğin, aynı işlem iframe'leri benzersiz bir hedef almaz, bunun yerine tek bir hedeften erişilebilen farklı bağlamlar olarak temsil edilir.

Kısıtlanmış alanlar

chrome.debugger API, güvenlik nedeniyle tüm Chrome Geliştirici Araçları Protokol Alan Adlarına erişim sağlamaz. Şu alanlar kullanılabilir: Accessibility, Audits, CacheStorage, Console CSS, Database, Debugger, DOMDebugger, DOMDebugger, DOMDebugger, DOM Snapshot DOMSnapshotWebAudioWebAuthn

Çerçevelerle çalışma

Hedeflerle bire bir kare eşlemesi yok. Tek bir sekmede, birden fazla aynı işlem çerçevesi aynı hedefi paylaşabilir ancak farklı bir yürütme bağlamı kullanabilir. Diğer yandan, işlem dışı bir iframe için yeni bir hedef oluşturulabilir.

Tüm karelere eklemek için her kare türünü ayrı olarak işlemeniz gerekir:

  • Aynı işlem çerçeveleriyle ilişkili yeni yürütme bağlamlarını tanımlamak için Runtime.executionContextCreated etkinliğini dinleyin.

  • İşlem dışı çerçeveleri tanımlamak için ilgili hedeflere ekleme adımlarını uygulayın.

Bir hedefe bağlandıktan sonra, işlem dışı alt çerçeveler veya ilişkili çalışanlar dahil olmak üzere daha fazla alakalı hedefe bağlanmak isteyebilirsiniz.

Chrome 125'ten itibaren chrome.debugger API, düz oturumları desteklemektedir. Böylece, ana hata ayıklayıcı oturumunuza alt öğeler olarak ek hedefler ekleyebilir ve chrome.debugger.attach için başka bir çağrıya gerek kalmadan bu kullanıcılara mesaj gönderebilirsiniz. Bunun yerine, komut göndermek istediğiniz alt hedefi tanımlamak için chrome.debugger.sendCommand çağırırken sessionId özelliği ekleyebilirsiniz.

İşlem dışı alt karelere otomatik olarak eklemek için önce Target.attachedToTarget etkinliği için bir işleyici ekleyin:

chrome.debugger.onEvent.addListener((source, method, params) => {
  if (method === "Target.attachedToTarget") {
    // `source` identifies the parent session, but we need to construct a new
    // identifier for the child session
    const session = { ...source, sessionId: params.sessionId };

    // Call any needed CDP commands for the child session
    await chrome.debugger.sendCommand(session, "Runtime.enable");
  }
});

Ardından, flatten seçeneği true değerine ayarlı Target.setAutoAttach komutunu göndererek otomatik ekle özelliğini etkinleştirin:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

Örnekler

Bu API'yi denemek için chrome-extension-samples deposundan debugger API örneğini yükleyin.

Türler

Debuggee

Hata ayıklama aracı tanımlayıcısı. tabId, extensionId veya targetId belirtilmelidir

Özellikler

  • extensionId

    string isteğe bağlı

    Hata ayıklamak istediğiniz uzantının kimliği. Uzantı arka plan sayfasına ekleme işlemi yalnızca --silent-debugger-extension-api komut satırı anahtarı kullanıldığında mümkündür.

  • tabId

    numara isteğe bağlı

    Hata ayıklamak istediğiniz sekmenin kimliği.

  • targetId

    string isteğe bağlı

    Hata ayıklama hedefinin opak kimliği.

DebuggerSession

Chrome 125 ve sonraki sürümler

Debugger oturum tanımlayıcısı. tabId, extensionsId veya targetId değerlerinden biri belirtilmelidir. Ayrıca, isteğe bağlı bir sessionId sağlanabilir. onEvent kaynağından gönderilen bağımsız değişkenler için sessionId belirtildiyse bu, etkinliğin kök hata ayıklama oturumundaki bir alt protokol oturumundan geldiği anlamına gelir. sessionId değeri sendCommand'e iletilirken belirtilirse kök hata ayıklama oturumundaki bir alt protokol oturumunu hedefler.

Özellikler

  • extensionId

    string isteğe bağlı

    Hata ayıklamak istediğiniz uzantının kimliği. Uzantı arka plan sayfasına ekleme işlemi yalnızca --silent-debugger-extension-api komut satırı anahtarı kullanıldığında mümkündür.

  • sessionId

    string isteğe bağlı

    Chrome Geliştirici Araçları Protokolü oturumunun opak kimliği. tabId, extensionId veya targetId tarafından tanımlanan kök oturumdaki bir alt oturum tanımlar.

  • tabId

    numara isteğe bağlı

    Hata ayıklamak istediğiniz sekmenin kimliği.

  • targetId

    string isteğe bağlı

    Hata ayıklama hedefinin opak kimliği.

DetachReason

Chrome 44 ve sonraki sürümler

Bağlantının feshi nedeni.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Hata ayıklama hedefi bilgileri

Özellikler

  • ekli

    boolean

    Hata ayıklayıcı zaten ekliyse doğru değerini alır.

  • extensionId

    string isteğe bağlı

    Tür = "background_page" ise tanımlanan uzantı kimliği.

  • faviconUrl

    string isteğe bağlı

    Site simgesinin URL'sini hedefleyin.

  • id

    dize

    Hedef kimliği.

  • tabId

    numara isteğe bağlı

    Tür == 'sayfa' ise tanımlanan sekme kimliği.

  • title

    dize

    Hedef sayfa başlığı.

  • Hedef türü.

  • url

    dize

    Hedef URL.

TargetInfoType

Chrome 44 ve sonraki sürümler

Hedef türü.

Enum

"background_page"

Yöntemler

attach()

Söz 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

Hata ayıklayıcıyı belirtilen hedefe ekler.

Parametreler

  • Eklemek istediğiniz hata ayıklama hedefi.

  • requiredVersion

    dize

    Gerekli hata ayıklama protokolü sürümü ("0.1"). Biri hata ayıklayıcıya yalnızca eşleşen ana sürüme ve daha büyük veya eşit bir alt sürüme sahip olabilir. Protokol sürümlerinin listesine buradan ulaşabilirsiniz.

  • geri çağırma

    Functions (isteğe bağlı)

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

    ()=>void

İlerlemeler

  • Promise<void>

    Chrome 96 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

detach()

Söz 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

Hata ayıklayıcıyı belirtilen hedeften ayırır.

Parametreler

  • Çıkarmak istediğiniz hedef hata ayıklama hedefi.

  • geri çağırma

    Functions (isteğe bağlı)

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

    ()=>void

İlerlemeler

  • Promise<void>

    Chrome 96 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

getTargets()

Söz 
chrome.debugger.getTargets(
  callback?: function,
)

Kullanılabilir hata ayıklama hedeflerinin listesini döndürür.

Parametreler

  • geri çağırma

    Functions (isteğe bağlı)

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

    (result: TargetInfo[])=>void

    • sonuç

      TargetInfo[]

      Kullanılabilir hata ayıklama hedeflerine karşılık gelen TargetInfo nesneleri dizisi.

İlerlemeler

  • Promise<TargetInfo[]>

    Chrome 96 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

sendCommand()

Söz 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

Verilen komutu hata ayıklama hedefine gönderir.

Parametreler

  • Komutu göndermek istediğiniz hata ayıklama hedefi.

  • method

    dize

    Yöntem adı. Uzaktan hata ayıklama protokolü tarafından tanımlanan yöntemlerden biri olmalıdır.

  • commandParams

    isteğe bağlı

    İstek parametreleri içeren JSON nesnesi. Bu nesne, belirtilen yöntemin uzaktan hata ayıklama parametreleri şemasına uymalıdır.

  • geri çağırma

    Functions (isteğe bağlı)

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

    (result?: object)=>void

    • sonuç

      isteğe bağlı

      Yanıt içeren JSON nesnesi. Yanıtın yapısı yöntem adına bağlı olarak değişir ve uzaktan hata ayıklama protokolündeki komut açıklamasının "returns" özelliği tarafından tanımlanır.

İlerlemeler

  • Promise<object|undefined>

    Chrome 96 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

Etkinlikler

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

Tarayıcı, sekme için hata ayıklama oturumunu sonlandırdığında tetiklenir. Bu durum, sekme kapatılırken veya eklenen sekme için Chrome Geliştirici Araçları çağrılırken ortaya çıkar.

Parametreler

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

Hedef sorunları araçları etkinliğinde hata ayıklandığında tetiklenir.

Parametreler

  • geri çağırma

    işlev

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

    (source: DebuggerSession,method: string,params?: object)=>void