chrome.devtools.inspectedWindow

คำอธิบาย

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

ดูสรุป API ของเครื่องมือสำหรับนักพัฒนาเว็บสำหรับข้อมูลเบื้องต้นทั่วไปเกี่ยวกับการใช้ 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 ที่แตกต่างกันหลายรายการ แต่ละเฟรมจะมีบริบทของตัวเอง รวมถึงบริบทเพิ่มเติมสำหรับส่วนขยายแต่ละรายการที่มี Content Script ทำงานในเฟรมนั้น

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

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

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

ตัวอย่าง

โค้ดต่อไปนี้จะตรวจสอบเวอร์ชันของ 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

    สตริง

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

  • getContent

    เป็นโมฆะ

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

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

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

    • callback

      ฟังก์ชัน

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

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

      • content

        สตริง

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

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

        สตริง

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

  • setContent

    เป็นโมฆะ

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

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

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

    • content

      สตริง

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

    • คอมมิต

      บูลีน

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

    • callback

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

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

      (error?: object) => void

      • ข้อผิดพลาด

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

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

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

tabId

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

ประเภท

ตัวเลข

เมธอด

eval()

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

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

พารามิเตอร์

  • นิพจน์

    สตริง

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

  • ตัวเลือก

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

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

    • frameURL

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

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

    • scriptExecutionContext

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

      Chrome 107 ขึ้นไป

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

    • useContentScriptContext

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

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

  • callback

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

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

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

    • ผลลัพธ์

      ออบเจ็กต์

      ผลการประเมิน

    • exceptionInfo

      ออบเจ็กต์

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

      • รหัส

        สตริง

        ตั้งค่าหากเกิดข้อผิดพลาดในฝั่ง DevTools ก่อนที่จะมีการประเมินนิพจน์

      • คำอธิบาย

        สตริง

        ตั้งค่าหากเกิดข้อผิดพลาดในฝั่ง DevTools ก่อนที่จะมีการประเมินนิพจน์

      • รายละเอียด

        any[]

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

      • isError

        บูลีน

        ตั้งค่าหากเกิดข้อผิดพลาดในฝั่ง DevTools ก่อนที่จะมีการประเมินนิพจน์

      • isException

        บูลีน

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

      • value

        สตริง

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

getResources()

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (resources: Resource[]) => void

reload()

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

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

พารามิเตอร์

  • reloadOptions

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

    • ignoreCache

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

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

    • injectedScript

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

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

    • userAgent

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

      หากระบุ สตริงจะลบล้างค่าของUser-Agentส่วนหัว HTTP ที่ส่งขณะโหลดทรัพยากรของหน้าเว็บที่ตรวจสอบ สตริงจะลบล้างค่าของพร็อพเพอร์ตี้ 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