chrome.debugger

Mô tả

API chrome.debugger đóng vai trò là phương thức 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 hoạt độ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 đính kèm, API chrome.debugger cho phép bạn gửi các lệnh Giao thức công cụ phát triển của Chrome (CDP) đến một mục tiêu nhất định. Tài liệu này không giải thích chi tiết về CDP. Để 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 đang được gỡ lỗi, có thể bao gồm một thẻ, một iframe hoặc một worker. 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.v.).

Trong một mục tiêu, có thể có nhiều ngữ cảnh thực thi – ví dụ: cùng một khung hiển thị nội dung trong quá trình không nhận được một mục tiêu duy nhất mà được biểu thị dưới dạng nhiều ngữ cảnh 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 cấp quyền truy cập vào tất cả Miền giao thức Chrome DevTools. 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.

Làm việc với khung hình

Không có mối liên kết một với một giữa các khung với các mục tiêu. Trong một thẻ, nhiều khung quy trình giống nhau có thể chia sẻ cùng một mục tiêu nhưng sử dụng ngữ cảnh thực thi khác nhau. Mặt khác, bạn có thể tạo một mục tiêu mới 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 ngữ cảnh thực thi mới 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ào các mục tiêu có 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 có thể muốn kết nối với các mục tiêu liên quan khác, bao gồm cả các khung con ngoài quy trình hoặc worker được liên kết.

Kể từ Chrome 125, API chrome.debugger hỗ trợ các phiên phẳng. Điều này cho phép bạn thêm các mục tiêu bổ sung dưới dạng mục tiêu con vào phiên trình gỡ lỗi chính và gửi thông báo cho các mục tiêu đó mà không cần gọi lại 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 }]
});

Tính năng tự động đính kèm chỉ đính kèm vào các khung mà mục tiêu nhận biết được, bị giới hạn ở các khung là phần tử con trực tiếp của một khung được liên kết với mục tiêu đó. Ví dụ: với hệ phân cấp khung A -> B -> C (trong đó tất cả đều là nhiều nguồn gốc), việc gọi Target.setAutoAttach cho mục tiêu liên kết với A sẽ dẫn đến phiên cũng được đính kèm vào B. Tuy nhiên, đây không phải là hàm đệ quy, vì vậy, bạn cũng cần gọi Target.setAutoAttach để B đính kèm phiên vào C.

Ví dụ

Để dùng thử API này, hãy cài đặt ví dụ về API trình gỡ lỗi từ kho lưu trữ chrome-extension-samples.

Loại

Debuggee

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

Thuộc tính

  • extensionId

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

    Mã của phần mở rộng 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ã mờ 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 giá trị tabId, extensionId 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ì tức là sự kiện đó đế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 được truyền đến sendCommand, thì sessionId 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 phần mở rộng 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ã nhận dạng mờ của phiên Giao thức Chrome DevTools. Xác định một 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ã mờ 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_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 type = "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

    chuỗi

    Mã mục tiêu.

  • tabId

    số không bắt buộc

    Mã nhận dạng thẻ, được xác định nếu type == "page".

  • tiêu đề

    chuỗi

    Tiêu đề trang đích.

  • Loại mục tiêu.

  • url

    chuỗi

    URL đích.

TargetInfoType

Chrome 44 trở lên

Loại mục tiêu.

Enum

"page"

"background_page"

"worker"

"other"

Phương thức

attach()

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

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

Thông số

  • Mục tiêu gỡ lỗi mà bạn muốn đính kèm.

  • requiredVersion

    chuỗi

    Phiên bản giao thức gỡ lỗi bắt buộc ("0.1"). Bạn chỉ có thể đính kèm vào đối tượng gỡ lỗi có phiên bản chính khớp và phiên bản phụ lớn hơn hoặc bằng. Bạn có thể xem danh sách các phiên bản giao thức tại đây.

  • callback

    hàm không bắt buộc

    Tham số callback 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 Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

detach()

Promise 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

Tách trình gỡ lỗi khỏi mục tiêu đã cho.

Thông số

  • Mục tiêu gỡ lỗi mà bạn muốn tách.

  • callback

    hàm không bắt buộc

    Tham số callback 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 Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getTargets()

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

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

Thông số

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (result: TargetInfo[]) => void

    • kết quả

      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 Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

sendCommand()

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

Gửi lệnh đã cho đến mục tiêu gỡ lỗi.

Thông số

  • mục tiêu

    DebuggerSession

    Mục tiêu gỡ lỗi mà bạn muốn gửi lệnh.

  • method

    chuỗi

    Tên phương thức. Phải là một trong các phương thức do 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 đồ tham số gỡ lỗi từ xa cho phương thức đã cho.

  • callback

    hàm không bắt buộc

    Tham số callback 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ỳ thuộc vào tên phương thức và được xác định bằng thuộc tính "returns" (trả về) của nội dung 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 Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ 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ụ phát triển Chrome đang được gọi cho thẻ đính kèm.

Thông số

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

Được kích hoạt bất cứ khi nào gỡ lỗi sự kiện đo lường vấn đề mục tiêu.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (source: DebuggerSession, method: string, params?: object) => void

    • nguồn

      DebuggerSession

    • method

      chuỗi

    • tham số

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