Nội dung mô tả
API chrome.debugger
đóng vai trò là mạng truyền tải thay thế cho giao thức gỡ lỗi từ xa của Chrome. Sử dụng chrome.debugger
để đính kèm vào một hoặc nhiều thẻ để đo lường tương tác mạng, gỡ lỗi JavaScript, thay đổi DOM và CSS, v.v. Sử dụng thuộc tính Debuggee
tabId
để nhắm mục tiêu các thẻ bằng sendCommand
và định tuyến sự kiện theo tabId
từ lệnh gọi lại onEvent
.
Quyền
debugger
Bạn phải khai báo quyền "debugger"
trong tệp kê khai của tiện ích để sử dụng API này.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Khái niệm và cách sử dụng
Sau khi được đính kèm, API chrome.debugger
sẽ cho phép bạn gửi các lệnh Giao thức Công cụ của Chrome cho nhà phát triển (CDP) đến một mục tiêu nhất định. Việc giải thích chuyên sâu về CDP nằm ngoài phạm vi của tài liệu này — để tìm hiểu thêm về CDP, hãy xem tài liệu chính thức về CDP.
Mục tiêu
Mục tiêu đại diện cho một nội dung nào đó đang được gỡ lỗi – có thể bao gồm một thẻ, iframe hoặc một trình thực thi. Mỗi mục tiêu được xác định bằng một UUID và có một loại liên kết (chẳng hạn như iframe
, shared_worker
và các loại khác).
Trong một mục tiêu, có thể có nhiều ngữ cảnh thực thi – ví dụ: các iframe quy trình giống nhau không có mục tiêu duy nhất mà được biểu thị dưới dạng các ngữ cảnh khác nhau có thể truy cập được từ một mục tiêu duy nhất.
Miền bị hạn chế
Vì lý do bảo mật, API chrome.debugger
không cung cấp quyền truy cập vào tất cả Miền giao thức của Công cụ của Chrome cho nhà phát triển. Các miền hiện có là: Accessibility,
Testings, CacheStorage, Console,
CSS, Database, Trình gỡ lỗi, DOM, DOMDebugger, DOMSnapshotWebAudioWebAuthn
Thao tác với khung
Không có mối liên kết một với một giữa các khung hình với các mục tiêu. Trong một thẻ, nhiều khung quy trình giống nhau có thể có cùng một mục tiêu nhưng sử dụng ngữ cảnh thực thi khác. Mặt khác, một mục tiêu mới có thể được tạo cho một iframe ngoài quy trình.
Để đính kèm vào tất cả khung, bạn cần xử lý riêng từng loại khung:
Theo dõi sự kiện
Runtime.executionContextCreated
để xác định các ngữ cảnh thực thi mới được liên kết với cùng các khung quy trình.Làm theo các bước để đính kèm vào mục tiêu liên quan nhằm xác định các khung ngoài quy trình.
Đính kèm vào các mục tiêu có liên quan
Sau khi kết nối với một mục tiêu, bạn nên kết nối với các mục tiêu có liên quan khác, bao gồm cả các khung con ngoài quy trình hoặc trình thực thi được liên kết.
Kể từ Chrome 125, API chrome.debugger
sẽ hỗ trợ các phiên cố định. Nhờ vậy, bạn có thể thêm các mục tiêu khác làm mục tiêu con vào phiên trình gỡ lỗi chính và thông báo cho các mục tiêu đó mà không cần một lệnh gọi khác đến chrome.debugger.attach
. Thay vào đó, bạn có thể thêm thuộc tính sessionId
khi gọi chrome.debugger.sendCommand
để xác định mục tiêu con mà bạn muốn gửi lệnh đến.
Để tự động đính kèm vào các khung con ngoài quy trình, trước tiên, hãy thêm trình nghe cho sự kiện Target.attachedToTarget
:
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");
}
});
Sau đó, hãy bật tính năng tự động đính kèm bằng cách gửi lệnh Target.setAutoAttach
với tuỳ chọn flatten
được đặt thành true
:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Ví dụ
Để dùng thử API này, hãy cài đặt ví dụ về API trình gỡ lỗi trong kho lưu trữ chrome-extension-samples.
Loại
Debuggee
Giá trị nhận dạng trình gỡ lỗi. Bạn phải chỉ định mã thẻ, mã tiện ích hoặc mã mục tiêu
Thuộc tính
-
extensionId
chuỗi không bắt buộc
Mã của tiện ích mà bạn định gỡ lỗi. Bạn chỉ có thể đính kèm vào trang nền của tiện ích khi sử dụng nút chuyển dòng lệnh
--silent-debugger-extension-api
. -
tabId
số không bắt buộc
Mã của thẻ mà bạn định gỡ lỗi.
-
targetId
chuỗi không bắt buộc
Mã không rõ ràng của mục tiêu gỡ lỗi.
DebuggerSession
Giá trị nhận dạng phiên của trình gỡ lỗi. Phải chỉ định một trong số tabId, extensionsId hoặc targetId. Ngoài ra, bạn có thể cung cấp sessionId (mã phiên hoạt động) không bắt buộc. Nếu sessionId được chỉ định cho các đối số được gửi từ onEvent
, thì tức là sự kiện này đến từ một phiên giao thức con trong phiên gỡ lỗi gốc. Nếu sessionId được chỉ định khi chuyển đến sendCommand
, thì mã này sẽ nhắm đến một phiên giao thức con trong phiên gỡ lỗi gốc.
Thuộc tính
-
extensionId
chuỗi không bắt buộc
Mã của tiện ích mà bạn định gỡ lỗi. Bạn chỉ có thể đính kèm vào trang nền của tiện ích khi sử dụng nút chuyển dòng lệnh
--silent-debugger-extension-api
. -
sessionId
chuỗi không bắt buộc
Mã không rõ ràng của phiên Giao thức Công cụ của Chrome cho nhà phát triển. Xác định phiên con trong phiên gốc được xác định bằng tabId, ExtensionId hoặc targetId.
-
tabId
số không bắt buộc
Mã của thẻ mà bạn định gỡ lỗi.
-
targetId
chuỗi không bắt buộc
Mã không rõ ràng của mục tiêu gỡ lỗi.
DetachReason
Lý do chấm dứt kết nối.
Liệt kê
"target_closed"
"canceled_by_user"
TargetInfo
Thông tin về mục tiêu gỡ lỗi
Thuộc tính
-
đã đính kèm
boolean
Đúng nếu trình gỡ lỗi đã được đính kèm.
-
extensionId
chuỗi không bắt buộc
Mã tiện ích, được xác định nếu loại = 'background_page'.
-
faviconUrl
chuỗi không bắt buộc
URL biểu tượng trang web mục tiêu.
-
id
string
Mã mục tiêu.
-
tabId
số không bắt buộc
Mã thẻ, được xác định nếu loại == 'page'.
-
title
string
Tiêu đề trang đích.
-
loại
Loại mục tiêu.
-
url
string
URL mục tiêu.
TargetInfoType
Loại mục tiêu.
Liệt kê
"background_page"
"worker"
"other"
Phương thức
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Đính kèm trình gỡ lỗi vào mục tiêu nhất định.
Tham số
-
mục tiêu
Gỡ lỗi đích mà bạn muốn đính kèm.
-
requiredVersion
string
Phiên bản giao thức gỡ lỗi bắt buộc ("0.1"). Một ứng dụng chỉ có thể đính kèm vào ứng dụng gỡ lỗi có phiên bản lớn trùng khớp và phiên bản nhỏ hơn hoặc bằng. Bạn có thể lấy danh sách phiên bản giao thức tại đây.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 96 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Tách trình gỡ lỗi khỏi mục tiêu đã cho.
Tham số
-
mục tiêu
Gỡ lỗi mục tiêu mà bạn muốn tách ra.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 96 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Trả về danh sách các mục tiêu gỡ lỗi có sẵn.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result: TargetInfo[]) => void
-
kết quả
Mảng gồm các đối tượng TargetInfo tương ứng với các mục tiêu gỡ lỗi có sẵn.
-
Giá trị trả về
-
Promise<TargetInfo[]>
Chrome 96 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Gửi lệnh đã cho đến mục tiêu gỡ lỗi.
Tham số
-
mục tiêu
Gỡ lỗi đích mà bạn muốn gửi lệnh đến.
-
method
string
Tên phương thức. Phải là một trong các phương thức được xác định bằng giao thức gỡ lỗi từ xa.
-
commandParams
đối tượng không bắt buộc
Đối tượng JSON có tham số yêu cầu. Đối tượng này phải tuân thủ lược đồ thông số gỡ lỗi từ xa cho phương thức nhất định.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result?: object) => void
-
kết quả
đối tượng không bắt buộc
Đối tượng JSON có phản hồi. Cấu trúc của phản hồi thay đổi tuỳ theo tên phương thức và được xác định bằng thuộc tính "returns" của phần mô tả lệnh trong giao thức gỡ lỗi từ xa.
-
Giá trị trả về
-
Promise<object | undefined>
Chrome 96 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
Sự kiện
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Được kích hoạt khi trình duyệt chấm dứt phiên gỡ lỗi cho thẻ. Điều này xảy ra khi thẻ đang đóng hoặc Công cụ của Chrome cho nhà phát triển đang được gọi cho thẻ đính kèm.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(source: Debuggee, reason: DetachReason) => void
-
nguồn
-
lý do
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Được kích hoạt bất cứ khi nào sự kiện đo lường vấn đề về mục tiêu gỡ lỗi.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(source: DebuggerSession, method: string, params?: object) => void
-
nguồn
-
method
string
-
params
đối tượng không bắt buộc
-