chrome.debugger

คำอธิบาย

chrome.debugger API ทำหน้าที่เป็นช่องทางการนำส่งสำรองสำหรับโปรโตคอลการแก้ไขข้อบกพร่องระยะไกลของ Chrome ใช้ chrome.debugger เพื่อแนบกับแท็บอย่างน้อย 1 แท็บเพื่อวัดการโต้ตอบของเครือข่าย แก้ไขข้อบกพร่อง JavaScript เปลี่ยน DOM และ CSS และอื่นๆ ใช้พร็อพเพอร์ตี้ Debuggee tabId เพื่อกําหนดเป้าหมายแท็บด้วย sendCommand และกำหนดเส้นทางเหตุการณ์ตาม tabId จาก onEvent callbacks

สิทธิ์

debugger

คุณต้องประกาศสิทธิ์ "debugger" ในไฟล์ Manifest ของส่วนขยายเพื่อใช้ API นี้

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

แนวคิดและการใช้งาน

เมื่อแนบแล้ว chrome.debugger API จะช่วยให้คุณส่งคําสั่ง Chrome DevTools Protocol (CDP) ไปยังเป้าหมายที่ระบุได้ การอธิบาย CDP อย่างละเอียดอยู่นอกขอบเขตของเอกสารประกอบนี้ หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับ CDP โปรดดูเอกสารประกอบอย่างเป็นทางการของ CDP

เป้าหมาย

เป้าหมายแสดงถึงสิ่งที่กำลังแก้ไขข้อบกพร่อง ซึ่งอาจรวมถึงแท็บ, iframe หรือเวิร์กเกอร์ เป้าหมายแต่ละรายการจะระบุด้วย UUID และมีประเภทที่เชื่อมโยง (เช่น iframe, shared_worker และอื่นๆ)

ภายในเป้าหมายหนึ่งๆ อาจมีบริบทการเรียกใช้หลายรายการ เช่น iframe ของกระบวนการเดียวกันจะไม่มีเป้าหมายที่ไม่ซ้ำกัน แต่แสดงเป็นบริบทที่แตกต่างกันซึ่งเข้าถึงได้จากเป้าหมายเดียว

โดเมนที่ถูกจํากัด

chrome.debugger API จะไม่ให้สิทธิ์เข้าถึงโดเมนโปรโตคอลของเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ Chrome ทั้งหมดเนื่องด้วยเหตุผลด้านความปลอดภัย โดเมนที่ใช้ได้ ได้แก่ การช่วยเหลือพิเศษ, การตรวจสอบ, CacheStorage, คอนโซล, CSS, ฐานข้อมูล, โปรแกรมแก้ไขข้อบกพร่อง, DOM, DOMDebugger, DOMSnapshot, การจําลอง, การดึงข้อมูล, IO, อินพุต, เครื่องมือตรวจสอบ, บันทึก, เครือข่าย, การวางซ้อน, หน้าเว็บ, ประสิทธิภาพ, เครื่องมือวิเคราะห์, รันไทม์, พื้นที่เก็บข้อมูล, เป้าหมาย, การติดตาม, WebAudio และ WebAuthn

ทำงานกับเฟรม

ไม่มีการแมปเฟรมกับเป้าหมายแบบ 1:1 ภายในแท็บเดียว เฟรมกระบวนการเดียวกันหลายเฟรมอาจใช้เป้าหมายเดียวกัน แต่ใช้บริบทการเรียกใช้ที่แตกต่างกัน ในทางกลับกัน ระบบอาจสร้างเป้าหมายใหม่สําหรับ iframe นอกกระบวนการ

หากต้องการแนบกับเฟรมทั้งหมด คุณต้องจัดการเฟรมแต่ละประเภทแยกกัน ดังนี้

• คอยฟังเหตุการณ์ Runtime.executionContextCreated เพื่อระบุบริบทการเรียกใช้ใหม่ซึ่งเชื่อมโยงกับเฟรมกระบวนการเดียวกัน

• ทําตามขั้นตอนเพื่อแนบกับเป้าหมายที่เกี่ยวข้องเพื่อระบุเฟรมนอกกระบวนการ

แนบกับเป้าหมายที่เกี่ยวข้อง

หลังจากเชื่อมต่อกับเป้าหมายแล้ว คุณอาจต้องเชื่อมต่อกับเป้าหมายที่เกี่ยวข้องเพิ่มเติม ซึ่งรวมถึงเฟรมย่อยนอกกระบวนการหรือผู้ปฏิบัติงานที่เกี่ยวข้อง

ตั้งแต่ Chrome 125 เป็นต้นไป chrome.debugger API จะรองรับเซสชันแบบ Flat ซึ่งจะช่วยให้คุณเพิ่มเป้าหมายย่อยลงในเซสชันโปรแกรมแก้ไขข้อบกพร่องหลักและส่งข้อความถึงเป้าหมายเหล่านั้นได้โดยไม่ต้องเรียกใช้ chrome.debugger.attach อีกครั้ง แต่คุณสามารถเพิ่มพร็อพเพอร์ตี้ sessionId เมื่อเรียกใช้ chrome.debugger.sendCommand เพื่อระบุเป้าหมายย่อยที่ต้องการส่งคําสั่งได้

หากต้องการแนบกับเฟรมย่อยนอกกระบวนการโดยอัตโนมัติ ให้เพิ่ม Listener ของเหตุการณ์ 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");
  }
});

จากนั้นเปิดใช้การแนบอัตโนมัติโดยส่งคําสั่ง Target.setAutoAttach โดยตั้งค่าตัวเลือก flatten เป็น true

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

การแนบอัตโนมัติจะแนบกับเฟรมที่เป้าหมายรับรู้เท่านั้น ซึ่งจํากัดอยู่ที่เฟรมที่เป็นเฟรมย่อยโดยตรงของเฟรมที่เชื่อมโยงกับเป้าหมาย ตัวอย่างเช่น เมื่อใช้ลําดับชั้นเฟรม A -> B -> C (โดยที่ทั้งหมดมาจากแหล่งที่มาต่างกัน) การเรียกใช้ Target.setAutoAttach สําหรับเป้าหมายที่เชื่อมโยงกับ A จะทําให้เซสชันแนบอยู่กับ B ด้วย แต่การดำเนินการนี้ไม่ใช่แบบเรียกซ้ำ ดังนั้นจึงต้องเรียกใช้ Target.setAutoAttach ด้วยเพื่อให้ B แนบเซสชันกับ C

ตัวอย่าง

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่างโปรแกรมแก้ไขข้อบกพร่อง API จากที่เก็บchrome-extension-samples

ประเภท

Debuggee

ตัวระบุ Debuggee ต้องระบุ tabId, extensionId หรือ targetId อย่างใดอย่างหนึ่ง

พร็อพเพอร์ตี้

• extensionId

  สตริง ไม่บังคับ

  รหัสของส่วนขยายที่คุณต้องการแก้ไขข้อบกพร่อง การแนบกับหน้าพื้นหลังของส่วนขยายจะทําได้ก็ต่อเมื่อใช้สวิตช์บรรทัดคําสั่ง --silent-debugger-extension-api เท่านั้น

• tabId

  ตัวเลข ไม่บังคับ

  รหัสของแท็บที่คุณต้องการแก้ไขข้อบกพร่อง

• targetId

  สตริง ไม่บังคับ

  รหัสแบบทึบของเป้าหมายการแก้ไขข้อบกพร่อง

DebuggerSession

Chrome 125 ขึ้นไป

ตัวระบุเซสชันโปรแกรมแก้ไขข้อบกพร่อง ต้องระบุ tabId, extensionId หรือ targetId อย่างใดอย่างหนึ่ง นอกจากนี้ คุณยังระบุ sessionId ที่ไม่บังคับได้ด้วย หากระบุ sessionId สําหรับอาร์กิวเมนต์ที่ส่งจาก onEvent หมายความว่าเหตุการณ์มาจากเซสชันโปรโตคอลย่อยภายในเซสชันการแก้ไขข้อบกพร่องรูท หากระบุ sessionId เมื่อส่งไปยัง sendCommand การดำเนินการนี้จะกำหนดเป้าหมายไปยังเซสชันโปรโตคอลย่อยภายในเซสชันการแก้ไขข้อบกพร่องรูท

พร็อพเพอร์ตี้

• extensionId

  สตริง ไม่บังคับ

  รหัสของส่วนขยายที่คุณต้องการแก้ไขข้อบกพร่อง การแนบกับหน้าพื้นหลังของส่วนขยายจะทําได้ก็ต่อเมื่อใช้สวิตช์บรรทัดคําสั่ง --silent-debugger-extension-api เท่านั้น

• sessionId

  สตริง ไม่บังคับ

  รหัสที่ไม่โปร่งใสของเซสชันโปรโตคอลเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome ระบุเซสชันย่อยภายในเซสชันรูทที่ระบุโดย tabId, extensionId หรือ targetId

• tabId

  ตัวเลข ไม่บังคับ

  รหัสของแท็บที่คุณต้องการแก้ไขข้อบกพร่อง

• targetId

  สตริง ไม่บังคับ

  รหัสแบบทึบของเป้าหมายการแก้ไขข้อบกพร่อง

DetachReason

Chrome 44 ขึ้นไป

เหตุผลในการสิ้นสุดการเชื่อมต่อ

ค่าแจกแจง

"target_closed"

"canceled_by_user"

TargetInfo

ข้อมูลเป้าหมายการแก้ไขข้อบกพร่อง

พร็อพเพอร์ตี้

• เชื่อมต่อแล้ว

  บูลีน

  จริงหากมีการแนบโปรแกรมแก้ไขข้อบกพร่องอยู่แล้ว

• extensionId

  สตริง ไม่บังคับ

  รหัสส่วนขยายที่กําหนดหาก type = "background_page"

• faviconUrl

  สตริง ไม่บังคับ

  URL ของไอคอน Fav เป้าหมาย

• id

  สตริง

  รหัสเป้าหมาย

• tabId

  ตัวเลข ไม่บังคับ

  รหัสแท็บที่กําหนดหาก type == "page"

• title

  สตริง

  ชื่อหน้าเป้าหมาย

• ประเภท

  TargetInfoType

  ประเภทเป้าหมาย

• URL

  สตริง

  URL เป้าหมาย

TargetInfoType

Chrome 44 ขึ้นไป

ประเภทเป้าหมาย

ค่าแจกแจง

"page"

"background_page"

"worker"

"other"

เมธอด

attach()

สัญญา

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

แนบโปรแกรมแก้ไขข้อบกพร่องกับเป้าหมายที่ระบุ

พารามิเตอร์

• เป้าหมาย

  โปรแกรมที่จะแก้ไขข้อบกพร่อง

  เป้าหมายการแก้ไขข้อบกพร่องที่คุณต้องการแนบ

• requiredVersion

  สตริง

  เวอร์ชันโปรโตคอลการแก้ไขข้อบกพร่องที่จำเป็น ("0.1") คุณจะแนบกับโปรแกรมแก้ไขข้อบกพร่องได้เฉพาะเวอร์ชันหลักที่ตรงกันและเวอร์ชันย่อยที่เท่ากับหรือมากกว่า ดูรายการเวอร์ชันโปรโตคอลได้ที่นี่

• callback

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  () => void

การคืนสินค้า

• Promise<void>

  Chrome 96 ขึ้นไป

  ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

detach()

สัญญา

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

แยกโปรแกรมแก้ไขข้อบกพร่องออกจากเป้าหมายที่ระบุ

พารามิเตอร์

• เป้าหมาย

  โปรแกรมที่จะแก้ไขข้อบกพร่อง

  เป้าหมายการแก้ไขข้อบกพร่องที่ต้องการแยกออก

• callback

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  () => void

การคืนสินค้า

• Promise<void>

  Chrome 96 ขึ้นไป

  ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

getTargets()

สัญญา

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

แสดงรายการเป้าหมายการแก้ไขข้อบกพร่องที่ใช้ได้

พารามิเตอร์

• callback

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (result: TargetInfo[]) => void

  • ผลลัพธ์

    TargetInfo[]

    อาร์เรย์ของออบเจ็กต์ TargetInfo ที่สอดคล้องกับเป้าหมายการแก้ไขข้อบกพร่องที่ใช้ได้

การคืนสินค้า

• Promise<TargetInfo[]>

  Chrome 96 ขึ้นไป

  ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

sendCommand()

สัญญา

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

ส่งคําสั่งที่ระบุไปยังเป้าหมายการแก้ไขข้อบกพร่อง

พารามิเตอร์

• เป้าหมาย

  DebuggerSession

  เป้าหมายการแก้ไขข้อบกพร่องที่คุณต้องการส่งคําสั่ง

• method

  สตริง

  ชื่อเมธอด ควรเป็นวิธีการใดวิธีการหนึ่งที่กำหนดโดยโปรโตคอลการแก้ไขข้อบกพร่องจากระยะไกล

• commandParams

  ออบเจ็กต์ ไม่บังคับ

  ออบเจ็กต์ JSON ที่มีพารามิเตอร์คำขอ ออบเจ็กต์นี้ต้องเป็นไปตามรูปแบบพารามิเตอร์การแก้ไขข้อบกพร่องระยะไกลสําหรับเมธอดที่ระบุ

• callback

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (result?: object) => void

  • ผลลัพธ์

    ออบเจ็กต์ ไม่บังคับ

    ออบเจ็กต์ JSON ที่มีคำตอบ โครงสร้างของการตอบกลับจะแตกต่างกันไปตามชื่อเมธอดและกำหนดโดยแอตทริบิวต์ "returns" ของคำอธิบายคำสั่งในโปรโตคอลการแก้ไขข้อบกพร่องระยะไกล

การคืนสินค้า

• Promise<object | undefined>

  Chrome 96 ขึ้นไป

  ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

กิจกรรม

onDetach

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

เริ่มทํางานเมื่อเบราว์เซอร์สิ้นสุดเซสชันการแก้ไขข้อบกพร่องสําหรับแท็บ กรณีนี้จะเกิดขึ้นเมื่อมีการปิดแท็บหรือเรียกใช้เครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ Chrome สำหรับแท็บที่แนบอยู่

พารามิเตอร์

• callback

  ฟังก์ชัน

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (source: Debuggee, reason: DetachReason) => void

  • source

    โปรแกรมที่จะแก้ไขข้อบกพร่อง

  • เหตุผล

    DetachReason

onEvent

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

เริ่มทํางานทุกครั้งที่แก้ไขข้อบกพร่องเหตุการณ์เครื่องมือวัดผลของเป้าหมาย

พารามิเตอร์

• callback

  ฟังก์ชัน

  พารามิเตอร์ callback จะมีลักษณะดังนี้

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

  • source

    DebuggerSession

  • method

    สตริง

  • params

    ออบเจ็กต์ ไม่บังคับ