chrome.devtools.inspectedWindow

คำอธิบาย

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

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

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

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

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

ไฟล์ Manifest

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

"devtools_page"

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

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

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

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

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

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

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

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

ตัวอย่าง

โค้ดต่อไปนี้จะตรวจสอบเวอร์ชันของ 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 สำหรับ devtools จากที่เก็บ chrome-extension-samples

ประเภท

Resource

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

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

  • url

    string

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

  • getContent

    void

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

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

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

    • Callback

      ฟังก์ชัน

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

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

      • คอนเทนต์

        string

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

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

        string

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

  • setContent

    void

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

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

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

    • คอนเทนต์

      string

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

    • คอมมิต

      boolean

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

    • Callback

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

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

      (error?: object)=>void

      • error

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

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

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

tabId

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

ประเภท

ตัวเลข

วิธีการ

eval()

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

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

พารามิเตอร์

  • นิพจน์

    string

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

  • ตัวเลือก

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

    พารามิเตอร์ตัวเลือกอาจมีตัวเลือกอย่างน้อย 1 รายการ

    • frameURL

      string ไม่บังคับ

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

    • scriptExecutionContext

      string ไม่บังคับ

      Chrome 107 ขึ้นไป

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

    • useContentScriptContext

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

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

  • Callback

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

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

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

    • ผลลัพธ์

      ออบเจ็กต์

      ผลลัพธ์ของการประเมิน

    • exceptionInfo

      ออบเจ็กต์

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

      • รหัส

        string

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

      • คำอธิบาย

        string

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

      • รายละเอียด

        ทั้งหมด[]

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

      • isError

        boolean

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

      • isException

        boolean

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

      • value

        string

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

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