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 belirlemek, JavaScript'te hata ayıklamak, DOM ve CSS'yi değiştirmek ve daha pek çok işlem için bir veya daha fazla sekmeye eklemek üzere chrome.debugger
kullanın. sendCommand
içeren sekmeleri hedeflemek ve onEvent
geri aramadan tabId
bazında etkinlikleri yönlendirmek için Debuggee
özelliğini tabId
kullanın.
İ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.
İlgili hedeflere ekle
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
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
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ığı.
-
tür
Hedef türü.
-
url
dize
Hedef URL.
TargetInfoType
Hedef türü.
Enum
"background_page"
Yöntemler
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Hata ayıklayıcıyı belirtilen hedefe ekler.
Parametreler
-
hedef
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ümlerVaatler, 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()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Hata ayıklayıcıyı belirtilen hedeften ayırır.
Parametreler
-
hedef
Çı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ümlerVaatler, 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()
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ç
Kullanılabilir hata ayıklama hedeflerine karşılık gelen TargetInfo nesneleri dizisi.
-
İlerlemeler
-
Promise<TargetInfo[]>
Chrome 96 ve sonraki sürümlerVaatler, 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()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Verilen komutu hata ayıklama hedefine gönderir.
Parametreler
-
hedef
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ümlerVaatler, 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
-
geri çağırma
işlev
callback
parametresi şu şekilde görünür:(source: Debuggee, reason: DetachReason) => void
-
source
-
neden
-
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
-
source
-
method
dize
-
params
isteğe bağlı
-