chrome.debugger

คำอธิบาย

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

สิทธิ์

debugger

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

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

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

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

เป้าหมาย

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

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

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

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

ใช้งานเฟรม

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

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

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

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

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

ตั้งแต่ Chrome 125 เป็นต้นไป API ของ chrome.debugger จะรองรับเซสชันแบบคงที่ ช่วงเวลานี้ ช่วยให้คุณเพิ่มเป้าหมายเพิ่มเติมในฐานะผู้เผยแพร่โฆษณาย่อยในเซสชันโปรแกรมแก้ไขข้อบกพร่องหลัก และ ส่งข้อความถึงผู้ใช้ได้โดยไม่ต้องโทรหา 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 }]
});

ตัวอย่าง

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

ประเภท

Debuggee

ตัวระบุ Debuggee ต้องระบุ TabId, รหัสส่วนขยาย หรือ targetId

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

  • extensionId

    string ไม่บังคับ

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

  • tabId

    หมายเลข ไม่บังคับ

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

  • targetId

    string ไม่บังคับ

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

DebuggerSession

Chrome 125 ขึ้นไป

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

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

  • extensionId

    string ไม่บังคับ

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

  • sessionId

    string ไม่บังคับ

    รหัสที่คลุมเครือของเซสชัน Chrome DevTools Protocol ระบุเซสชันย่อยภายในเซสชันรูทที่ระบุโดย TabId, extensionsId หรือรหัส targetId

  • tabId

    หมายเลข ไม่บังคับ

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

  • targetId

    string ไม่บังคับ

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

DetachReason

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"target_closed"

"canceled_by_user"

TargetInfo

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

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

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

    boolean

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

  • extensionId

    string ไม่บังคับ

    รหัสส่วนขยายที่กำหนดหากประเภท = 'background_page'

  • faviconUrl

    string ไม่บังคับ

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

  • id

    สตริง

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

  • tabId

    หมายเลข ไม่บังคับ

    รหัสแท็บ กำหนดหากประเภท == 'page'

  • title

    สตริง

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

  • ประเภท

    TargetInfoType

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

  • URL

    สตริง

    URL เป้าหมาย

TargetInfoType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"page"

"background_page"

"ผู้ปฏิบัติงาน"

"อื่นๆ"

เมธอด

attach()

สัญญา 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

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

พารามิเตอร์

  • เป้าหมาย

    Debuggee

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

  • requiredVersion

    สตริง

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

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 96 ขึ้นไป

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

detach()

สัญญา 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

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

พารามิเตอร์

  • เป้าหมาย

    Debuggee

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

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 96 ขึ้นไป

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

getTargets()

สัญญา 
chrome.debugger.getTargets(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (result: TargetInfo[]) => void

    • ผลลัพธ์

      TargetInfo[]

      อาร์เรย์ของออบเจ็กต์ TargetInfo ที่ตรงกับเป้าหมายการแก้ไขข้อบกพร่องที่มีอยู่

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

  • Promise&lt;TargetInfo[]&gt;

    Chrome 96 ขึ้นไป

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

sendCommand()

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

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

พารามิเตอร์

  • เป้าหมาย

    DebuggerSession

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

  • method

    สตริง

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

  • commandParams

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

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

  • Callback

    ไม่บังคับ

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

    (result?: object) => void

    • ผลลัพธ์

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

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

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

  • Promise&lt;object | ไม่ระบุ>

    Chrome 96 ขึ้นไป

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

กิจกรรม

onDetach

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

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

onEvent

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

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

    • method

      สตริง

    • พารามิเตอร์

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