คำอธิบาย
ใช้ 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
เรียกใช้โค้ดในหน้าต่างที่ตรวจสอบ
เมธอด 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
-
แหล่งข้อมูล
-
คอนเทนต์
string
-