chrome.devtools.inspectedWindow

คำอธิบาย

ใช้ chrome.devtools.inspectedWindow API เพื่อโต้ตอบกับหน้าต่างที่ตรวจสอบ ซึ่งได้แก่ รับรหัสแท็บสำหรับหน้าที่ตรวจสอบ ประเมินโค้ดในบริบทของหน้าต่างที่ตรวจสอบ โหลดหน้าเว็บซ้ำ หรือรับรายการทรัพยากรภายในหน้า

ไฟล์ Manifest

คุณต้องประกาศคีย์ต่อไปนี้ในไฟล์ Manifest เพื่อใช้ API นี้

"devtools_page"

ใช้ chrome.devtools.inspectedWindow เพื่อโต้ตอบกับหน้าต่างที่ตรวจสอบ: ดูรหัสแท็บสำหรับ หน้าเว็บที่ตรวจสอบ ประเมินโค้ดในบริบทของหน้าต่างที่ตรวจสอบ โหลดหน้าเว็บซ้ำ หรือ รายการทรัพยากรภายในหน้า

ดูข้อมูลสรุปเกี่ยวกับ DevTools API สำหรับข้อมูลเบื้องต้นเกี่ยวกับการใช้ API เครื่องมือสำหรับนักพัฒนาซอฟต์แวร์

ภาพรวม

พร็อพเพอร์ตี้ tabId มีตัวระบุแท็บที่คุณใช้ร่วมกับ chrome.tabs.* ได้ การเรียก API อย่างไรก็ตาม โปรดทราบว่า chrome.tabs.* API ไม่มีอยู่ในเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ หน้าส่วนขยายเนื่องจากข้อควรพิจารณาด้านความปลอดภัย คุณจะต้องส่งรหัสแท็บไปยังพื้นหลัง และเรียกใช้ฟังก์ชัน chrome.tabs.* API จากที่นั่น

ระบบอาจใช้เมธอด reload เพื่อโหลดหน้าที่ตรวจสอบซ้ำ นอกจากนี้ ผู้โทรยังระบุ การลบล้างสำหรับสตริง User Agent สคริปต์ที่จะแทรกเข้ามาในช่วงแรกๆ เมื่อโหลดหน้าเว็บ หรือ เพื่อบังคับให้โหลดทรัพยากรที่แคชไว้อีกครั้ง

ใช้การเรียก getResources และเหตุการณ์ onResourceContent เพื่อรับรายการทรัพยากร (เอกสาร สไตล์ชีต สคริปต์ รูปภาพ ฯลฯ) ภายในหน้าเว็บที่ตรวจสอบ getContent และ setContentเมธอดของคลาส Resource พร้อมด้วยเหตุการณ์ onResourceContentCommitted อาจ ใช้เพื่อรองรับการแก้ไขเนื้อหาทรัพยากร เช่น โดยเครื่องมือแก้ไขภายนอก

การเรียกใช้โค้ดในหน้าต่างที่ตรวจสอบ

เมธอด eval ทำให้ส่วนขยายเรียกใช้โค้ด JavaScript ได้ในบริบทของ หน้าเว็บที่ตรวจสอบ วิธีการนี้มีประสิทธิภาพอย่างยิ่งเมื่อใช้ในบริบทที่เหมาะสมและเป็นอันตรายเมื่อใช้ อย่างไม่เหมาะสม ใช้เมธอด tabs.executeScript เว้นแต่คุณต้องการฟังก์ชันเฉพาะ ที่เมธอด eval มีให้

ความแตกต่างหลักระหว่างเมธอด eval และ tabs.executeScript มีดังนี้

  • เมธอด eval ไม่ได้ใช้โลกที่แยกต่างหากสำหรับโค้ดที่ได้รับการประเมิน ดังนั้น JavaScript โค้ดจะเข้าถึงสถานะของหน้าต่างที่ตรวจสอบได้ ใช้วิธีนี้เมื่อเข้าถึง ต้องระบุสถานะ JavaScript ของหน้าที่ตรวจสอบ
  • บริบทการดำเนินการของโค้ดที่กำลังประเมินมี Developer Tools Console API เช่น โค้ดอาจใช้ inspect และ $0
  • โค้ดที่ประเมินอาจแสดงค่าที่ส่งไปยัง Callback ของส่วนขยาย ค่าผลลัพธ์ ต้องเป็นออบเจ็กต์ JSON ที่ถูกต้อง (อาจมีเฉพาะประเภท JavaScript พื้นฐานและ acyclic เท่านั้น อ้างอิงถึงออบเจ็กต์ JSON อื่นๆ) โปรดระมัดระวังเป็นพิเศษขณะประมวลผลข้อมูลที่ได้รับ จากหน้าเว็บที่ตรวจสอบ ซึ่งโดยส่วนใหญ่แล้วบริบทของการดำเนินการจะควบคุมโดยหน้าเว็บที่ตรวจสอบ CANNOT TRANSLATE หน้าเว็บที่เป็นอันตรายอาจส่งผลต่อข้อมูลที่ส่งไปยังส่วนขยาย

โปรดทราบว่าหน้าเว็บอาจมีบริบทการดำเนินการ JavaScript ที่แตกต่างกันหลายบริบท โดยแต่ละเฟรมจะมี ของตัวเอง รวมถึงบริบทเพิ่มเติมสำหรับแต่ละส่วนขยายที่มีสคริปต์เนื้อหาทำงานอยู่ เฟรม

โดยค่าเริ่มต้น เมธอด eval จะทำงานในบริบทของเฟรมหลักของหน้าเว็บที่ตรวจสอบ

เมธอด eval จะใช้อาร์กิวเมนต์ที่ 2 (ไม่บังคับ) ซึ่งใช้ระบุบริบท โค้ดจะได้รับการประเมิน ออบเจ็กต์ตัวเลือกนี้สามารถประกอบด้วยคีย์ต่อไปนี้อย่างน้อย 1 รายการ

frameURL
ใช้เพื่อระบุเฟรมอื่นนอกเหนือจากเฟรมหลักของหน้าที่ตรวจสอบ
contextSecurityOrigin
ใช้เพื่อเลือกบริบทภายในเฟรมที่ระบุตามต้นทางเว็บ
useContentScriptContext
หากเป็นจริง ให้เรียกใช้สคริปต์ในบริบทเดียวกันกับสคริปต์เนื้อหาของส่วนขยาย (เทียบเท่ากับ ระบุเว็บ orgin ของส่วนขยายเป็นต้นทางของความปลอดภัยตามบริบท) การตั้งค่านี้สามารถใช้เพื่อ แลกเปลี่ยนข้อมูลกับสคริปต์เนื้อหากัน

ตัวอย่าง

การตรวจสอบโค้ดต่อไปนี้สำหรับเวอร์ชันของ jQuery ที่ใช้โดยหน้าเว็บที่ตรวจสอบ

chrome.devtools.inspectedWindow.eval(
  "jQuery.fn.jquery",
  function(result, isException) {
    if (isException) {
      console.log("the page is not using jQuery");
    } else {
      console.log("The page is using jQuery v" + result);
    }
  }
);

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

ประเภท

Resource

ทรัพยากรภายในหน้าที่ตรวจสอบ เช่น เอกสาร สคริปต์ หรือรูปภาพ

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

  • URL

    สตริง

    URL ของทรัพยากร

  • getContent

    เป็นโมฆะ

    รับเนื้อหาของทรัพยากร

    ฟังก์ชัน getContent มีลักษณะดังนี้ 

    (callback: function) => {...}

    • Callback

      ฟังก์ชัน

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

      (content: string, encoding: string) => void

      • เนื้อหา

        สตริง

        เนื้อหาของทรัพยากร (อาจเข้ารหัส)

      • การเข้ารหัส

        สตริง

        เว้นว่างไว้หากเนื้อหาไม่ได้เข้ารหัส หรือใช้ชื่อการเข้ารหัส ปัจจุบันรองรับเฉพาะ base64

  • ตั้งค่าเนื้อหา

    เป็นโมฆะ

    ตั้งค่าเนื้อหาของทรัพยากร

    ฟังก์ชัน setContent มีลักษณะดังนี้ 

    (content: string, commit: boolean, callback?: function) => {...}

    • เนื้อหา

      สตริง

      เนื้อหาใหม่ของทรัพยากร ขณะนี้รองรับเฉพาะทรัพยากรที่มีประเภทข้อความเท่านั้น

    • คอมมิต

      boolean

      เป็นจริงหากผู้ใช้แก้ไขทรัพยากรเสร็จแล้ว และเนื้อหาใหม่ของทรัพยากรควรคงอยู่ เท็จ หากนี่เป็นการเปลี่ยนแปลงเล็กน้อยที่ส่งมาในขณะที่ผู้ใช้แก้ไขทรัพยากร

    • Callback

      ไม่บังคับ

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

      (error?: object) => void

      • ข้อผิดพลาด

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

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

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

tabId

รหัสของแท็บที่กำลังตรวจสอบ รหัสนี้ใช้ได้กับ chrome.tabs* API

ประเภท

ตัวเลข

เมธอด

eval()

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
)

ประเมินนิพจน์ JavaScript ในบริบทของเฟรมหลักของหน้าเว็บที่ตรวจสอบ นิพจน์จะต้องประเมินเป็นออบเจ็กต์ที่สอดคล้องกับ JSON ไม่เช่นนั้นจะมีข้อยกเว้น ฟังก์ชันการประเมินสามารถรายงานข้อผิดพลาดด้านเครื่องมือสำหรับนักพัฒนาเว็บหรือข้อยกเว้น JavaScript ที่เกิดขึ้นระหว่างการประเมิน ไม่ว่ากรณีใด พารามิเตอร์ result ของ Callback จะเป็น undefined ในกรณีที่เกิดข้อผิดพลาดเกี่ยวกับเครื่องมือสำหรับนักพัฒนาเว็บ พารามิเตอร์ isException จะไม่ใช่ค่าว่าง และตั้งค่า isError เป็น "จริง" และตั้งค่า code เป็นรหัสข้อผิดพลาด ในกรณีที่เกิดข้อผิดพลาด JavaScript ระบบจะตั้งค่า isException เป็น "จริง" และตั้งค่า value เป็นค่าสตริงของออบเจ็กต์ที่ส่ง

พารามิเตอร์

  • นิพจน์

    สตริง

    นิพจน์ที่จะประเมิน

  • ตัวเลือก

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

    พารามิเตอร์ตัวเลือกมีได้ตั้งแต่ 1 ตัวเลือกขึ้นไป

    • frameURL

      string ไม่บังคับ

      หากระบุไว้ ระบบจะประเมินนิพจน์ใน iframe โดยมี URL ตรงกับที่ระบุไว้ โดยค่าเริ่มต้น ระบบจะประเมินนิพจน์ในกรอบบนสุดของหน้าที่ตรวจสอบ

    • scriptExecutionContext

      string ไม่บังคับ

      Chrome เวอร์ชัน 107 ขึ้นไป

      ประเมินนิพจน์ในบริบทของสคริปต์เนื้อหาของส่วนขยายที่ตรงกับต้นทางที่ระบุ หากกำหนดไว้ ScriptExecutionContext จะลบล้างค่า "true" ใน useContentScriptContext

    • useContentScriptContext

      บูลีน ไม่บังคับ

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

  • Callback

    ไม่บังคับ

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

    (result: object, exceptionInfo: object) => void

    • ผลลัพธ์

      ออบเจ็กต์

      ผลของการประเมิน

    • exceptionInfo

      ออบเจ็กต์

      ออบเจ็กต์ที่ระบุรายละเอียดหากเกิดข้อยกเว้นขณะประเมินนิพจน์

      • รหัส

        สตริง

        กำหนดว่าข้อผิดพลาดเกิดขึ้นในฝั่งเครื่องมือสำหรับนักพัฒนาเว็บก่อนที่จะประเมินนิพจน์หรือไม่

      • คำอธิบาย

        สตริง

        กำหนดว่าข้อผิดพลาดเกิดขึ้นในฝั่งเครื่องมือสำหรับนักพัฒนาเว็บก่อนที่จะประเมินนิพจน์หรือไม่

      • รายละเอียด

        ทั้งหมด[]

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

      • isError

        boolean

        กำหนดว่าข้อผิดพลาดเกิดขึ้นในฝั่งเครื่องมือสำหรับนักพัฒนาเว็บก่อนที่จะประเมินนิพจน์หรือไม่

      • isException

        boolean

        กำหนดว่าโค้ดที่ประเมินจะสร้างข้อยกเว้นที่ไม่มีการจัดการหรือไม่

      • value

        สตริง

        กำหนดว่าโค้ดที่ประเมินจะสร้างข้อยกเว้นที่ไม่มีการจัดการหรือไม่

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
)

เรียกข้อมูลรายการทรัพยากรจากหน้าที่ตรวจสอบ

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (resources: Resource[]) => void

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
)

โหลดหน้าเว็บที่ตรวจสอบซ้ำ

พารามิเตอร์

  • reloadOptions

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

    • ignoreCache

      บูลีน ไม่บังคับ

      เมื่อเป็นจริง ตัวโหลดจะข้ามแคชสำหรับทรัพยากรของหน้าที่ตรวจสอบทั้งหมดซึ่งโหลดก่อนที่เหตุการณ์ load จะเริ่มทำงาน ผลที่ได้จะคล้ายกับการกด Ctrl+Shift+R ในหน้าต่างที่ตรวจสอบหรือภายในหน้าต่างเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์

    • injectedScript

      string ไม่บังคับ

      หากระบุไว้ ระบบจะแทรกสคริปต์ลงในทุกเฟรมของหน้าที่ตรวจสอบทันทีที่โหลด ก่อนสคริปต์ใดๆ ของเฟรม ทั้งนี้ จะไม่มีการแทรกสคริปต์หลังจากการโหลดซ้ำที่ตามมา เช่น หากผู้ใช้กด Ctrl+R

    • userAgent

      string ไม่บังคับ

      หากระบุ สตริงจะลบล้างค่าของส่วนหัว HTTP User-Agent ที่ส่งขณะโหลดทรัพยากรของหน้าที่ตรวจสอบ นอกจากนี้ สตริงจะลบล้างค่าของพร็อพเพอร์ตี้ navigator.userAgent ที่ส่งคืนไปยังสคริปต์ที่ทำงานอยู่ภายในหน้าที่ตรวจสอบ

กิจกรรม

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

เริ่มทำงานเมื่อมีการเพิ่มทรัพยากรใหม่ไปยังหน้าที่ตรวจสอบแล้ว

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (resource: Resource) => void

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

เริ่มทำงานเมื่อมีการคอมมิตการแก้ไขทรัพยากรใหม่ (เช่น ผู้ใช้บันทึกเวอร์ชันที่แก้ไขแล้วของทรัพยากรในเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์)

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (resource: Resource, content: string) => void