chrome.debugger

Mô tả

API chrome.debugger đóng vai trò là một 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 đến các thẻ bằng sendCommand và định tuyến các sự kiện theo 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 được đính kèm, API chrome.debugger cho phép bạn gửi các lệnh Giao thức Chrome DevTools (CDP) đến 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 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 thứ đang được gỡ lỗi – mục tiêu này 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 được liên kết (chẳng hạn như iframe, shared_worker, v.v.).

Trong một đích đến, có thể có nhiều bối cảnh thực thi – ví dụ: các iframe có cùng quy trình không nhận được đích đến duy nhất mà thay vào đó được biểu thị dưới dạng các bối cảnh khác nhau có thể truy cập từ một đích đến 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ả các miền giao thức Chrome DevTools. Các miền có sẵn là: Accessibility (Khả năng hỗ trợ), Audits (Kiểm tra), CacheStorage (Bộ nhớ đệm), Console (Bảng điều khiển), CSS (CSS), Database (Cơ sở dữ liệu), Debugger (Trình gỡ lỗi), DOM (DOM), DOMDebugger (Trình gỡ lỗi DOM), DOMSnapshot (Ảnh chụp nhanh DOM), Emulation (Mô phỏng), Fetch (Tìm nạp), IO (IO), Input (Đầu vào), Inspector (Trình kiểm tra), Log (Nhật ký), Network (Mạng), Overlay (Lớp phủ), Page (Trang), Performance (Hiệu suất), Profiler (Trình phân tích tài nguyên), Runtime (Thời gian chạy), Storage (Bộ nhớ), Target (Mục tiêu), Tracing (Theo dõi), WebAudio (WebAudio) và WebAuthn (WebAuthn).

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

Không có mối liên kết một đối một giữa khung hình và mục tiêu. Trong một thẻ duy nhất, nhiều khung quy trình giống nhau có thể dùng chung cùng một mục tiêu nhưng sử dụng một ngữ cảnh thực thi khác. Mặt khác, bạn có thể tạo một đích đến mới cho iframe ngoài quy trình.

Để đính kèm vào tất cả cá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 bối cảnh thực thi mới đượ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ào các mục tiêu liên quan nhằm xác định các khung hình 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 các worker được liên kết.

Kể từ Chrome 125, API chrome.debugger sẽ hỗ trợ các phiên phẳng. Thao tác này cho phép bạn thêm các mục tiêu khác làm mục tiêu con vào phiên 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 đế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 một 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 lựa 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 những khung hình mà mục tiêu nhận biết được, tức là chỉ giới hạn ở những khung hình là thành phần con trực tiếp của một khung hình đượ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à nguồn gốc chéo), việc gọi Target.setAutoAttach cho mục tiêu được liên kết với A sẽ dẫn đến việc phiên cũng được đính kèm vào B. Tuy nhiên, phương thức này không đệ quy, vì vậy, bạn cũng cần gọi Target.setAutoAttach cho 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 gỡ lỗi trong kho lưu trữ chrome-extension-samples.

Loại

Debuggee

Mã nhận dạng chương trình cần 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ã nhận dạng của tiện ích mà bạn dự định gỡ lỗi. Bạn chỉ có thể đính kèm vào trang nền của tiện ích khi dùng công tắc dòng lệnh --silent-debugger-extension-api.

  • tabId

    number không bắt buộc

    Mã của thẻ mà bạn dự định gỡ lỗi.

  • targetId

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

    Mã nhận dạng 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ì có nghĩa 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 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ã nhận dạng của tiện ích mà bạn dự định gỡ lỗi. Bạn chỉ có thể đính kèm vào trang nền của tiện ích khi dùng công tắc dòng lệnh --silent-debugger-extension-api.

  • sessionId

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

    Mã nhận dạng không rõ ràng 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

    number không bắt buộc

    Mã của thẻ mà bạn dự định gỡ lỗi.

  • targetId

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

    Mã nhận dạng 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 gỡ lỗi về mục tiêu

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ã nhận dạng tiện ích, được xác định nếu type = "background_page".

  • faviconUrl

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

    URL biểu tượng trang web mục tiêu.

  • id

    chuỗi

    Mã mục tiêu.

  • tabId

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

TargetInfoType

Chrome 44 trở lên

Loại mục tiêu.

Enum

"page"

"background_page"

"worker"

"other"

Phương thức

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

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

Thông số

  • mục tiêu

    Debuggee

    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 chương trình cần gỡ lỗi có phiên bản chính trùng 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.

Giá trị trả về

  • Promise<void>

    Chrome 96 trở lên

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

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

Thông số

  • mục tiêu

    Debuggee

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

Giá trị trả về

  • Promise<void>

    Chrome 96 trở lên

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

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

Giá trị trả về

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

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 đến.

  • method

    chuỗi

    Tên phương thức. Phải là một trong những 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ó các tham số yêu cầu. Đối tượng này phải tuân thủ sơ đồ tham số gỡ lỗi từ xa cho phương thức đã cho.

Giá trị trả về

  • Promise<object | undefined>

    Chrome 96 trở lên

Sự kiện

onDetach

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

Được kích hoạt khi trình duyệt kết thúc phiên gỡ lỗi cho thẻ. Điều này xảy ra khi thẻ đang đóng hoặc Chrome DevTools đ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 sự kiện đo lường vấn đề về mục tiêu gỡ lỗi.

Thông số

  • callback

    hàm

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

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

    • method

      chuỗi

    • params

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