Deskripsi
chrome.debugger
API berfungsi sebagai transport alternatif untuk protokol proses debug jarak jauh Chrome. Gunakan chrome.debugger
untuk melampirkan ke satu atau beberapa tab untuk melengkapi interaksi jaringan, men-debug JavaScript, mengubah DOM dan CSS, dan lainnya. Gunakan properti Debuggee
tabId
untuk menargetkan tab dengan sendCommand
dan merutekan peristiwa menurut tabId
dari callback onEvent
.
Izin
debugger
Anda harus mendeklarasikan izin "debugger"
dalam manifes ekstensi untuk menggunakan API ini.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Konsep dan penggunaan
Setelah terpasang, chrome.debugger
API memungkinkan Anda mengirim perintah Protokol Chrome DevTools
(CDP) ke target tertentu. Menjelaskan CDP secara mendalam berada di luar cakupan
dokumentasi ini. Untuk mempelajari CDP lebih lanjut, lihat
dokumentasi CDP resmi.
Targets
Target mewakili sesuatu yang sedang di-debug—ini dapat mencakup tab,
iframe, atau pekerja. Setiap target diidentifikasi oleh UUID dan memiliki jenis
terkait (seperti iframe
, shared_worker
, dan lainnya).
Dalam satu target, mungkin ada beberapa konteks eksekusi. Misalnya, iframe proses yang sama tidak mendapatkan target unik, tetapi diwakili sebagai konteks berbeda yang dapat diakses dari satu target.
Domain yang dibatasi
Untuk alasan keamanan, chrome.debugger
API tidak menyediakan akses ke semua Domain Protokol
Chrome DevTools. Domain yang tersedia adalah: Accessibility,
Audits, CacheStorage, Console,
CSS, Database, Debugger, DOM,
DOMDebugger, DOMSnapshot, DOMSnapshot,WebAudioWebAuthn
Menggunakan bingkai
Tidak ada pemetaan satu lawan satu dari frame ke target. Dalam satu tab, beberapa frame proses yang sama dapat memiliki target yang sama, tetapi menggunakan konteks eksekusi yang berbeda. Di sisi lain, target baru mungkin dibuat untuk iframe di luar proses.
Untuk memasang ke semua bingkai, Anda harus menangani setiap jenis bingkai secara terpisah:
Proses peristiwa
Runtime.executionContextCreated
untuk mengidentifikasi konteks eksekusi baru yang terkait dengan frame proses yang sama.Ikuti langkah-langkah untuk melampirkan ke target terkait guna mengidentifikasi frame di luar proses.
Lampirkan ke target terkait
Setelah terhubung ke target, sebaiknya hubungkan ke target terkait lebih lanjut, termasuk frame turunan di luar proses atau pekerja terkait.
Mulai Chrome 125, chrome.debugger
API mendukung sesi datar. Hal ini
memungkinkan Anda menambahkan target lain sebagai turunan ke sesi debugger utama dan
mengirimnya pesan tanpa memerlukan panggilan lain ke chrome.debugger.attach
. Sebagai gantinya, Anda dapat menambahkan properti sessionId
saat memanggil chrome.debugger.sendCommand
untuk mengidentifikasi target turunan yang ingin dikirimi perintah.
Agar otomatis terhubung ke frame turunan di luar proses, tambahkan pemroses untuk peristiwa Target.attachedToTarget
terlebih dahulu:
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");
}
});
Kemudian, aktifkan lampiran otomatis dengan mengirimkan perintah Target.setAutoAttach
dengan
opsi flatten
yang disetel ke true
:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Contoh
Untuk mencoba API ini, instal contoh API debugger dari repositori chrome-extension-samples.
Jenis
Debuggee
ID debuggee. TabId, extensionId, atau targetId harus ditentukan
Properti
-
extensionId
string opsional
ID ekstensi yang ingin Anda debug. Melampirkan ke halaman latar belakang ekstensi hanya dapat dilakukan saat tombol command line
--silent-debugger-extension-api
digunakan. -
tabId
nomor opsional
ID tab yang ingin Anda debug.
-
targetId
string opsional
ID buram target debug.
DebuggerSession
ID sesi debugger. Salah satu tabId, extensionId, atau targetId harus ditentukan. Selain itu, sessionId opsional dapat diberikan. Jika sessionId ditentukan untuk argumen yang dikirim dari onEvent
, artinya peristiwa tersebut berasal dari sesi protokol turunan dalam sesi debuggee root. Jika sessionId ditentukan saat diteruskan ke sendCommand
, sessionId akan menargetkan sesi protokol turunan dalam sesi debuggee root.
Properti
-
extensionId
string opsional
ID ekstensi yang ingin Anda debug. Melampirkan ke halaman latar belakang ekstensi hanya dapat dilakukan saat tombol command line
--silent-debugger-extension-api
digunakan. -
sessionId
string opsional
ID buram sesi Chrome DevTools Protocol. Mengidentifikasi sesi turunan dalam sesi root yang diidentifikasi menurut tabId, extensionId, atau targetId.
-
tabId
nomor opsional
ID tab yang ingin Anda debug.
-
targetId
string opsional
ID buram target debug.
DetachReason
Alasan penghentian koneksi.
Enum
"target_closed"
TargetInfo
Informasi target debug
Properti
-
terpasang
boolean
True jika debugger sudah terpasang.
-
extensionId
string opsional
ID ekstensi, ditentukan jika jenisnya = 'background_page'.
-
faviconUrl
string opsional
URL favicon target.
-
id
string
ID target.
-
tabId
nomor opsional
ID tab, ditentukan jika jenis == 'page'.
-
title
string
Judul halaman target.
-
tipe
Jenis target.
-
url
string
URL Target.
TargetInfoType
Jenis target.
Enum
"background_page"
Metode
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Memasang debugger ke target yang ditentukan.
Parameter
-
target
Target proses debug yang ingin Anda lampirkan.
-
requiredVersion
string
Versi protokol proses debug yang diperlukan ("0.1"). Satu hanya dapat dipasang ke debuggee dengan versi utama yang cocok dan versi minor yang lebih besar atau sama. Daftar versi protokol dapat diperoleh di sini.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Melepaskan debugger dari target yang ditentukan.
Parameter
-
target
Target proses debug yang ingin Anda lepaskan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Menampilkan daftar target debug yang tersedia.
Parameter
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: TargetInfo[]) => void
-
hasil
Array objek TargetInfo yang sesuai dengan target debug yang tersedia.
-
Hasil
-
Promise<TargetInfo[]>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Mengirim perintah yang diberikan ke target proses debug.
Parameter
-
target
Men-debug target yang ingin Anda kirimi perintah.
-
method
string
Nama metode. Harus berupa salah satu metode yang ditentukan oleh protokol proses debug jarak jauh.
-
commandParams
objek opsional
Objek JSON dengan parameter permintaan. Objek ini harus sesuai dengan skema parameter proses debug jarak jauh untuk metode yang ditentukan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result?: object) => void
-
hasil
objek opsional
Objek JSON dengan respons. Struktur respons bervariasi, bergantung pada nama metode dan ditentukan oleh atribut 'returns' dari deskripsi perintah dalam protokol proses debug jarak jauh.
-
Hasil
-
Promise<object | undefined>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
Acara
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Diaktifkan saat browser menghentikan sesi proses debug untuk tab. Ini terjadi saat tab ditutup atau Chrome DevTools dipanggil untuk tab yang terpasang.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti:(source: Debuggee, reason: DetachReason) => void
-
source
-
alasan
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Diaktifkan setiap kali target proses debug menimbulkan peristiwa instrumentasi.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti:(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
string
-
params
objek opsional
-