Trang này được dịch bởi Cloud Translation API.

chrome.debugger

Mô tả

API chrome.debugger đóng vai trò là một phương tiện 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ẻ nhằm đ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 các sự kiện bằng tabId từ các 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 đính kèm, API chrome.debugger sẽ cho phép bạn gửi Giao thức Công cụ của Chrome cho nhà phát triển (CDP) cho một mục tiêu nhất định. Việc giải thích chi tiết về CDP nằm ngoài phạm vi cho tài liệu này—để tìm hiểu thêm về CDP, hãy xem tài liệu CDP chính thức.

Mục tiêu

Mục tiêu biểu thị một mục đang được gỡ lỗi—có thể bao gồm một thẻ, iframe hoặc một worker. Mỗi mục tiêu được xác định bằng một UUID và có liên kết loại (chẳng hạn như iframe, shared_worker, v.v.).

Trong một mục tiêu, có thể có nhiều ngữ cảnh thực thi, ví dụ như cùng một iframe của quá trình không nhận được mục tiêu duy nhất mà thay vào đó đượ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.

Miền bị hạn chế

Vì lý do bảo mật, API chrome.debugger không cấp quyền truy cập vào tất cả Công cụ của Chrome cho nhà phát triển Miền giao thức. Các miền hiện có là: Hỗ trợ tiếp cận, Kiểm tra, CacheStorage, Bảng điều khiển, CSS, Cơ sở dữ liệu, Trình gỡ lỗi, DOM, DOMDebugger, DOMSnapshot, Mô phỏng, Tìm nạp, IO, Đầu vào, Trình kiểm tra, Nhật ký, Mạng, Lớp phủ, Trang, Hiệu suất, Trình phân tích tài nguyên, Thời gian chạy, Bộ nhớ, Mục tiêu, Theo dõi, WebAudio và WebAuthn.

Thao tác với khung

Không có mối liên kết 1-1 giữa khung với mục tiêu. Trong một thẻ, nhiều khung quy trình giống nhau có thể có cùng mục tiêu nhưng sử dụng một ngữ cảnh thực thi. Mặt khác, mục tiêu mới có thể là được tạo cho 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 những người dùng mới ngữ cảnh thực thi được liên kết với cùng một khung quy trình.
Làm theo các bước để đính kèm với các mục tiêu liên quan nhằm xác định khung hình ngoài quy trình.

Đính kèm vào các mục tiêu liên quan

Sau khi kết nối với một mục tiêu, bạn có thể muốn kết nối với các mục tiêu khác có liên quan hơn bao gồm cả khung con ngoài quy trình hoặc worker liên kết.

Kể từ Chrome 125, API chrome.debugger sẽ hỗ trợ các phiên cố định. Chiến dịch này cho phép bạn thêm các mục tiêu khác dưới dạng phần tử con vào phiên trình gỡ lỗi chính và nhắn tin cho họ mà không cần gọi lại cho chrome.debugger.attach. Thay vào đó, bạn có thể thêm thuộc tính sessionId khi gọi chrome.debugger.sendCommand đến 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 kèm 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 chrome-extension-samples kho lưu trữ.

Loại

Debuggee

Giá trị nhận dạng người được gỡ lỗi. Bạn phải chỉ định tabId, extensionsId hoặc targetId

Thuộc tính

extensionId

chuỗi không bắt buộc

Mã 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

Chrome 125 trở lên

Giá trị nhận dạng phiên của trình gỡ lỗi. Bạn phải chỉ định một trong các trường tabId, extensionsId hoặc targetId. Ngoài ra, bạn có thể cung cấp một sessionId không bắt buộc. Nếu sessionId được chỉ định cho các đối số được gửi từ onEvent, thì sự kiện này đến từ một phiên giao thức con trong phiên ứng dụng được gỡ lỗi gốc. Nếu sessionId được chỉ định khi truyền đến sendCommand, thì mã đó sẽ nhắm đến một phiên giao thức con trong phiên của ứng dụng được gỡ lỗi gốc.

Thuộc tính

extensionId

chuỗi không bắt buộc

Mã 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 một phiên con trong phiên gốc được xác định bằng tabId, extensionsId 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

Chrome 44 trở lên

Lý do chấm dứt kết nối.

Enum

"target_close"

"canceled_by_user"

TargetInfo

Thông tin về mục tiêu gỡ lỗi

Thuộc tính

được đí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 của 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'.
tiêu đề

string

Tiêu đề trang mục tiêu.
loại

TargetInfoType

Loại mục tiêu.
url

string

URL mục tiêu.

TargetInfoType

Chrome 44 trở lên

Loại mục tiêu.

Enum

"trang"

"background_page"

"worker"

"khác"

Phương thức

attach()

Lời hứa

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

Đính kèm trình gỡ lỗi vào mục tiêu đã cho.

Tham số

mục tiêu

Người gỡ lỗi

Gỡ lỗi mục tiêu 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 tệp chỉ có thể đính kèm vào ứng dụng được gỡ lỗi có phiên bản lớn trùng khớp và phiên bản phụ lớn hơn hoặc bằng nhau. Bạn có thể xem danh sách các phiên bản của 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ề

Lời hứa<vô hiệu>

Chrome 96 trở lên

Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

detach()

Lời hứa

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

Người gỡ lỗi

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ề

Lời hứa<vô hiệu>

Chrome 96 trở lên

Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getTargets()

Lời hứa

chrome.debugger.getTargets(
  callback?: function,
)

Trả về danh sách các mục tiêu gỡ lỗi hiện có.

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 quả
  
  TargetInfo[]
  
  Mảng 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ên

Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

sendCommand()

Lời hứa

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

Gửi lệnh đã cho đến đích gỡ lỗi.

Tham số

mục tiêu

DebuggerSession

Đích gỡ lỗi 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 giao thức gỡ lỗi từ xa xác định.
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 đã cho.
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 quả
  
  đố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 sẽ thay đổi tuỳ thuộc vào tên phương thức và được xác định bằng lệnh "trả về" của phần mô tả lệnh trong giao thức gỡ lỗi từ xa.

Giá trị trả về

Promise<object | không xác định>

Chrome 96 trở lên

Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng 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ẻ này. Điều này xảy ra khi thẻ đang bị đó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
  
  Người gỡ lỗi
- lý do
  
  DetachReason

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 khi 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
  
  DebuggerSession
- method
  
  string
- tham số
  
  đối tượng không bắt buộc