chrome.debugger

說明

chrome.debugger API 可做為 Chrome 遠端偵錯通訊協定的替代傳輸方式。使用 chrome.debugger 附加至一或多個分頁，即可監控網路互動、偵錯 JavaScript、變更 DOM 和 CSS 等等。使用 Debuggee 屬性 tabId，以 sendCommand 為目標分頁，並透過 onEvent 回呼中的 tabId 轉送事件。

權限

debugger

安全注意事項

基於安全考量，chrome.debugger API 不會提供所有 Chrome DevTools 通訊協定網域的存取權。可用網域包括：Accessibility、Audits、CacheStorage、Console、CSS、Database、Debugger、DOM、DOMDebugger、DOMSnapshot、Emulation、Fetch、IO、Input、Inspector、Log、Network、Overlay、Page、Performance、Profiler、Runtime、Storage、Target、Tracing、WebAudio 和 WebAuthn。

資訊清單

如要使用這項 API，必須在擴充功能的資訊清單中聲明 "debugger"` 權限。

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

範例

如要試用這項 API，請從 chrome-extension-samples 存放區安裝偵錯工具 API 範例。

類型

Debuggee

偵錯目標 ID。必須指定 tabId、extensionId 或 targetId

屬性

  • extensionId

    字串 選填

    您要偵錯的擴充功能 ID。只有在使用 --silent-debugger-extension-api 指令列切換時，才能附加至擴充功能背景頁面。

  • tabId

    號碼 選填

    您要偵錯的分頁 ID。

  • targetId

    字串 選填

    偵錯目標的不透明 ID。

DebuggerSession

Chrome 125 以上版本

偵錯工具工作階段 ID。必須指定 tabId、extensionId 或 targetId 其中一個。此外，您也可以提供選用的 sessionId。如果為從 onEvent 傳送的引數指定 sessionId，表示事件來自根偵錯工具工作階段內的子通訊協定工作階段。如果將 sessionId 傳遞至 sendCommand 時指定了該 ID，則會以根偵錯對象工作階段中的子項通訊協定工作階段為目標。

屬性

  • extensionId

    字串 選填

    您要偵錯的擴充功能 ID。只有在使用 --silent-debugger-extension-api 指令列切換時，才能附加至擴充功能背景頁面。

  • sessionId

    字串 選填

    Chrome 開發人員工具通訊協定工作階段的不透明 ID。識別由 tabId、extensionId 或 targetId 識別的根工作階段中的子工作階段。

  • tabId

    號碼 選填

    您要偵錯的分頁 ID。

  • targetId

    字串 選填

    偵錯目標的不透明 ID。

DetachReason

Chrome 44 以上版本

連線終止原因。

列舉

「target_closed」

"canceled_by_user"

TargetInfo

偵錯目標資訊

屬性

  • 已連結

    布林值

    如果已附加偵錯工具，則為 True。

  • extensionId

    字串 選填

    擴充功能 ID，如果 type = 'background_page'，則會定義這個 ID。

  • faviconUrl

    字串 選填

    目標網站小圖示網址。

  • id

    字串

    目標 ID。

  • tabId

    號碼 選填

    分頁 ID，如果 type == 'page'，則會定義這個 ID。

  • title

    字串

    目標網頁標題。

  • 目標類型。

  • 網址

    字串

    目標網址。

TargetInfoType

Chrome 44 以上版本

目標類型。

列舉

「page」

「background_page」

「worker」

「other」

方法

attach()

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

將偵錯工具附加至指定目標。

參數

  • 目標

    Debuggee

    要附加的偵錯目標。

  • requiredVersion

    字串

    必要偵錯通訊協定版本 (「0.1」)。您只能附加至主要版本相符，且次要版本大於或等於的偵錯目標。如要查看通訊協定版本清單，請按這裡。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

detach()

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

從指定目標中分離偵錯工具。

參數

  • 目標

    Debuggee

    要中斷連結的偵錯目標。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getTargets()

Promise 
chrome.debugger.getTargets(
  callback?: function,
): Promise<TargetInfo[]>

傳回可用的偵錯目標清單。

參數

  • callback

    函式 選用

    callback 參數如下： 

    (result: TargetInfo[]) => void

    • 結果

      TargetInfo[]

      與可用偵錯目標對應的 TargetInfo 物件陣列。

傳回

  • Promise<TargetInfo[]>

    Chrome 96 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

sendCommand()

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

將指定指令傳送至偵錯目標。

參數

  • 要將指令傳送至的偵錯目標。

  • method

    字串

    方法名稱。應為遠端偵錯通訊協定定義的方法之一。

  • commandParams

    object 選填

    含有要求參數的 JSON 物件。這個物件必須符合指定方法的遠端偵錯參數架構。

  • callback

    函式 選用

    callback 參數如下： 

    (result?: object) => void

    • 結果

      object 選填

      含有回應的 JSON 物件。回應結構會因方法名稱而異，並由遠端偵錯通訊協定中指令說明的「returns」屬性定義。

傳回

  • Promise<object | undefined>

    Chrome 96 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onDetach

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

瀏覽器終止分頁的偵錯工作階段時觸發。當您關閉分頁或為附加的分頁叫用 Chrome 開發人員工具時，就會發生這種情況。

參數

onEvent

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

每當偵錯目標發出事件，就會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

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