chrome.devtools.inspectedWindow

คำอธิบาย

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

ดูข้อมูลเบื้องต้นเกี่ยวกับการใช้ Developer Tools API ได้ที่สรุป DevTools API

พร็อพเพอร์ตี้ tabId จะระบุตัวระบุแท็บที่คุณใช้กับการเรียก chrome.tabs.* API ได้ อย่างไรก็ตาม โปรดทราบว่าระบบไม่ได้แสดง 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 ของหน้าที่ตรวจสอบ
  • บริบทการดำเนินการของโค้ดที่กำลังประเมินรวมถึง DevTools Console API ตัวอย่างเช่น โค้ดสามารถใช้ inspect และ $0 ได้
  • โค้ดที่ประเมินอาจแสดงผลค่าที่ส่งผ่านไปยัง Callback ของส่วนขยาย ค่าที่แสดงผลต้องเป็นออบเจ็กต์ 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 ของเครื่องมือสำหรับนักพัฒนาเว็บจากที่เก็บ chrome-extension-samples

ประเภท

Resource

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

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

  • URL

    สตริง

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

  • getContent

    void

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

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

    () => {...}

    • returns

      Promise<object>

      Chrome 151+

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

  • setContent

    void

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

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

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

    • เนื้อหา

      สตริง

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

    • คอมมิต

      บูลีน

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

    • returns

      Promise<object>

      Chrome 151+

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

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

tabId

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

ประเภท

ตัวเลข

เมธอด

eval()

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

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

พารามิเตอร์

  • นิพจน์

    สตริง

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

  • ตัวเลือก

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

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

    • frameURL

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

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

    • scriptExecutionContext

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

      Chrome 107+

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

    • useContentScriptContext

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

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

returns

  • Promise<object>

    Chrome 151+

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

getResources()

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

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

returns

  • Promise<Resource[]>

    Chrome 151+

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

reload()

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

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

พารามิเตอร์

  • reloadOptions

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

    • ignoreCache

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

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

    • injectedScript

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

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

    • userAgent

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

      หากระบุไว้ สตริงจะลบล้างค่าของส่วนหัว 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

    • ทรัพยากร

      Resource

    • เนื้อหา

      สตริง