chrome.debugger

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.

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

Chrome 125 trở lên

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

Chrome 44 trở lên

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 mục tiêu.

  • url

    string

    URL mục tiêu.

TargetInfoType

Chrome 44 trở lên

Loại mục tiêu.

Liệt kê

"background_page"

"worker"

"other"

Phương thức

attach()

Cam kết 
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

    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ê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 để 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()

Cam kết 
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

    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ê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 để 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()

Cam kết 
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ả

      TargetInfo[]

      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ê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 để 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()

Cam kết 
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

    DebuggerSession

    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ê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 để 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ố

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

      DebuggerSession

    • method

      string

    • params

      đối tượng không bắt buộc