browser.devtools.inspectedWindow

คำอธิบาย

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

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

พร็อพเพอร์ตี้ tabId จะระบุตัวระบุแท็บที่คุณใช้กับการเรียก API browser.tabs.* ได้ อย่างไรก็ตาม browser.tabs.* API จะไม่แสดงในหน้าส่วนขยายเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์เนื่องจากข้อควรพิจารณาด้านความปลอดภัย คุณจะต้องส่งรหัสแท็บไปยังหน้าพื้นหลังและเรียกใช้ฟังก์ชัน browser.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 ไม่ได้ใช้ Isolated World สำหรับโค้ดที่กำลังประเมิน ดังนั้นโค้ดจึงเข้าถึงสถานะ JavaScript ของหน้าต่างที่ตรวจสอบได้ ใช้วิธีนี้เมื่อจำเป็นต้องเข้าถึงสถานะ JavaScript ของหน้าที่ตรวจสอบ
  • บริบทการดำเนินการของโค้ดที่ประเมินรวมถึง API คอนโซลเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ เช่น โค้ดสามารถใช้ inspect และ $0
  • โค้ดที่ประเมินอาจแสดงผลค่าที่ส่งไปยัง Callback ของส่วนขยาย ค่าที่แสดงผลต้องเป็นออบเจ็กต์ JSON ที่ถูกต้อง (อาจมีเฉพาะประเภท JavaScript พื้นฐานและการอ้างอิงแบบอะไซคลิกไปยังออบเจ็กต์ JSON อื่นๆ) โปรดใช้ความระมัดระวังเป็นพิเศษขณะประมวลผลข้อมูลที่ได้รับจากหน้าที่ตรวจสอบ เนื่องจากบริบทการดำเนินการจะควบคุมโดยหน้าที่ตรวจสอบเป็นหลัก หน้าเว็บที่เป็นอันตรายอาจส่งผลต่อข้อมูลที่ส่งกลับไปยังส่วนขยาย

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

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

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

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

ตัวอย่าง

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

browser.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

    void

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

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

    () => {...}

    • returns

      Promise<object>

      Chrome 151 ขึ้นไป browser.* ตั้งแต่ Chrome 152

      ฟังก์ชันที่รับเนื้อหาทรัพยากรเมื่อคำขอเสร็จสมบูรณ์

  • setContent

    void

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

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

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

    • เนื้อหา

      สตริง

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

    • คอมมิต

      บูลีน

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

    • returns

      Promise<object>

      Chrome 151 ขึ้นไป browser.* ตั้งแต่ Chrome 152

      ฟังก์ชันที่เรียกใช้เมื่อคำขอเสร็จสมบูรณ์

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

tabId

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

ประเภท

ตัวเลข

เมธอด

eval()

browser.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
): Promise<object>

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

พารามิเตอร์

  • นิพจน์

    สตริง

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

  • ตัวเลือก

    object ไม่บังคับ

    พารามิเตอร์ options มีตัวเลือกได้มากกว่า 1 รายการ

    • frameURL

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

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

    • scriptExecutionContext

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

      Chrome 107 ขึ้นไป browser.* ตั้งแต่ Chrome 152

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

    • useContentScriptContext

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

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

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

  • Promise<object>

    Chrome 151 ขึ้นไป browser.* ตั้งแต่ Chrome 152

    ฟังก์ชันที่เรียกใช้เมื่อการประเมินเสร็จสมบูรณ์

getResources()

browser.devtools.inspectedWindow.getResources(): Promise<Resource[]>

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

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

  • Promise<Resource[]>

    Chrome 151 ขึ้นไป browser.* ตั้งแต่ Chrome 152

    ฟังก์ชันที่รับรายการทรัพยากรเมื่อคำขอเสร็จสมบูรณ์

reload()

browser.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

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

พารามิเตอร์

  • reloadOptions

    object ไม่บังคับ

    • ignoreCache

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

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

    • injectedScript

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

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

    • userAgent

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

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

กิจกรรม

onResourceAdded

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (resource: Resource) => void

onResourceContentCommitted

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

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