คำอธิบาย
ใช้ userScripts
API เพื่อเรียกใช้สคริปต์ผู้ใช้ในบริบทสคริปต์ของผู้ใช้
สิทธิ์
userScripts
หากต้องการใช้ chrome.userScripts
API ให้เพิ่มสิทธิ์ "userScripts"
ลงในไฟล์ Manifest.json และ "host_permissions"
สําหรับเว็บไซต์ที่คุณต้องการเรียกใช้สคริปต์
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
ความพร้อมใช้งาน
แนวคิดและการใช้งาน
สคริปต์ผู้ใช้คือโค้ดที่แทรกลงในหน้าเว็บเพื่อแก้ไขลักษณะหรือลักษณะการทำงาน สคริปต์อาจสร้างขึ้นโดยผู้ใช้หรือดาวน์โหลดจากที่เก็บสคริปต์หรือส่วนขยายสคริปต์ของผู้ใช้
โหมดนักพัฒนาซอฟต์แวร์สำหรับผู้ใช้ส่วนขยาย
ในฐานะนักพัฒนาส่วนขยาย คุณได้เปิดใช้โหมดนักพัฒนาซอฟต์แวร์ในการติดตั้ง Chrome แล้ว สำหรับส่วนขยายสคริปต์ของผู้ใช้ ผู้ใช้ของคุณจะต้องเปิดใช้โหมดนักพัฒนาซอฟต์แวร์ด้วย ซึ่งคุณจะคัดลอกและวางลงในเอกสารของตัวเองได้โดยทำดังนี้
- ไปที่หน้าส่วนขยายโดยป้อน
chrome://extensions
ในแท็บใหม่ (ออกแบบมาให้ลิงก์ URLchrome://
รายการไม่ได้) เปิดใช้โหมดนักพัฒนาซอฟต์แวร์โดยคลิกสวิตช์เปิด/ปิดข้างโหมดนักพัฒนาซอฟต์แวร์
คุณสามารถตรวจสอบว่าได้เปิดใช้โหมดนักพัฒนาซอฟต์แวร์อยู่หรือไม่ โดยตรวจสอบว่า chrome.userScripts
แสดงข้อผิดพลาดหรือไม่ เช่น
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
ทำงานในโลกที่โดดเดี่ยว
ทั้งสคริปต์ของผู้ใช้และเนื้อหาสามารถทำงานในโลกที่แยกออกไปหรือในโลกหลักได้ โลกที่แยกเป็นอิสระคือสภาพแวดล้อมการดำเนินการที่หน้าโฮสต์หรือส่วนขยายอื่นๆ ไม่สามารถเข้าถึงได้ วิธีนี้ช่วยให้สคริปต์ของผู้ใช้เปลี่ยนสภาพแวดล้อม JavaScript ได้โดยไม่ส่งผลกระทบต่อหน้าโฮสต์หรือสคริปต์เนื้อหาของส่วนขยายหรือผู้ใช้และสคริปต์เนื้อหาของส่วนขยายอื่นๆ ในทางกลับกัน สคริปต์ผู้ใช้ (และสคริปต์เนื้อหา) จะมองไม่เห็นในหน้าโฮสต์ หรือสคริปต์ผู้ใช้และเนื้อหาของส่วนขยายอื่นๆ หน้าที่โฮสต์และส่วนขยายอื่นๆ จะเข้าถึงสคริปต์ที่ทำงานในโลกหลักได้ รวมถึงหน้าเว็บที่โฮสต์และส่วนขยายอื่นๆ มองเห็นได้ หากต้องการเลือกทั่วโลก ให้ส่งบัตร "USER_SCRIPT"
หรือ "MAIN"
เมื่อโทรไปที่ userScripts.register()
หากต้องการกำหนดค่านโยบายรักษาความปลอดภัยเนื้อหาสำหรับโลก USER_SCRIPT
ให้เรียก userScripts.configureWorld()
:
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
การรับส่งข้อความ
เช่นเดียวกับสคริปต์เนื้อหาและเอกสารนอกหน้าจอ สคริปต์ของผู้ใช้จะสื่อสารกับส่วนอื่นๆ ของส่วนขยายโดยใช้การรับส่งข้อความ (หมายความว่าสามารถเรียกใช้ runtime.sendMessage()
และ runtime.connect()
เหมือนกับส่วนอื่นๆ ของส่วนขยายได้) แต่จะใช้เครื่องจัดการเหตุการณ์เฉพาะ (หมายความว่าไม่ได้ใช้ onMessage
หรือ onConnect
) เครื่องจัดการเหล่านี้เรียกว่า runtime.onUserScriptMessage
และ runtime.onUserScriptConnect
ตัวแฮนเดิลเฉพาะช่วยให้ระบุข้อความจากสคริปต์ผู้ใช้ได้ง่ายขึ้น ซึ่งเป็นบริบทที่ไม่น่าเชื่อถือ
ก่อนที่จะส่งข้อความ คุณต้องเรียกใช้ configureWorld()
โดยตั้งค่าอาร์กิวเมนต์ messaging
เป็น true
โปรดทราบว่าคุณสามารถส่งได้ทั้งอาร์กิวเมนต์ csp
และ messaging
ในเวลาเดียวกัน
chrome.userScripts.configureWorld({
messaging: true
});
การอัปเดตส่วนขยาย
ระบบจะล้างสคริปต์ผู้ใช้ออกเมื่อมีการอัปเดตส่วนขยาย คุณสามารถเพิ่มกลับเข้าไปใหม่ได้โดยเรียกใช้โค้ดในเครื่องจัดการเหตุการณ์ runtime.onInstalled
ในโปรแกรมทำงานของบริการส่วนขยาย ตอบเฉพาะ"update"
เหตุผลที่ส่งไปยังโค้ดเรียกกลับของเหตุการณ์
ตัวอย่าง
ตัวอย่างนี้มาจากตัวอย่าง userScript ในที่เก็บตัวอย่างของเรา
ลงทะเบียนสคริปต์
ตัวอย่างต่อไปนี้แสดงการเรียกใช้พื้นฐานไปยัง register()
อาร์กิวเมนต์แรกคืออาร์เรย์ของออบเจ็กต์ที่กำหนดสคริปต์ที่จะลงทะเบียน มีตัวเลือกมากกว่าที่แสดงที่นี่
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
ประเภท
ExecutionWorld
โลกของ JavaScript สำหรับสคริปต์ของผู้ใช้ที่จะเรียกใช้ภายใน
ค่าแจกแจง
"MAIN"
ระบุสภาพแวดล้อมการดำเนินการของ DOM ซึ่งเป็นสภาพแวดล้อมการดำเนินการที่แชร์กับ JavaScript ของหน้าโฮสต์
"USER_script"
ระบุสภาพแวดล้อมการดำเนินการที่มีไว้สำหรับสคริปต์ของผู้ใช้โดยเฉพาะ และได้รับการยกเว้นจาก CSP ของหน้าเว็บ
RegisteredUserScript
พร็อพเพอร์ตี้
-
allFrames
บูลีน ไม่บังคับ
หาก "จริง" ก็จะแทรกลงในเฟรมทั้งหมด แม้ว่าเฟรมจะไม่ใช่เฟรมบนสุดในแท็บก็ตาม แต่ละเฟรมจะได้รับการตรวจสอบแยกกันสำหรับข้อกำหนด URL โดยจะไม่แทรกลงในเฟรมย่อยหากไม่เป็นไปตามข้อกำหนด URL ค่าเริ่มต้นคือ false ซึ่งหมายความว่าระบบจับคู่เฉพาะเฟรมด้านบนเท่านั้น
-
excludeGlobs
string[] ไม่บังคับ
ระบุรูปแบบไวลด์การ์ดสำหรับหน้าเว็บที่สคริปต์ผู้ใช้นี้จะไม่แทรกเข้าไป
-
excludeMatches
string[] ไม่บังคับ
ยกเว้นหน้าที่ระบบอาจแทรกสคริปต์ผู้ใช้นี้เข้าไป ดูรายละเอียดเพิ่มเติมเกี่ยวกับไวยากรณ์ของสตริงเหล่านี้ที่การจับคู่รูปแบบ
-
id
string
รหัสของสคริปต์ผู้ใช้ที่ระบุในการเรียก API พร็อพเพอร์ตี้นี้ต้องไม่ขึ้นต้นด้วย '_' เนื่องจากระบบสงวนไว้เป็นคำนำหน้าสำหรับรหัสสคริปต์ที่สร้างขึ้น
-
includeGlobs
string[] ไม่บังคับ
ระบุรูปแบบไวลด์การ์ดสำหรับหน้าที่จะแทรกสคริปต์ของผู้ใช้นี้
-
js
รายการออบเจ็กต์ ScriptSource ที่ระบุแหล่งที่มาของสคริปต์ที่จะแทรกลงในหน้าที่ตรงกัน
-
ตรงกัน
string[] ไม่บังคับ
ระบุหน้าที่จะแทรกสคริปต์ผู้ใช้นี้เข้าไป ดูรายละเอียดเพิ่มเติมเกี่ยวกับไวยากรณ์ของสตริงเหล่านี้ที่การจับคู่รูปแบบ ต้องระบุพร็อพเพอร์ตี้นี้สำหรับ ${ref:register}
-
runAt
RunAt ไม่บังคับ
ระบุเวลาที่แทรกไฟล์ JavaScript ลงในหน้าเว็บ ค่าที่ต้องการและค่าเริ่มต้นคือ
document_idle
-
ต่างประเทศ
ExecutionWorld ไม่บังคับ
สภาพแวดล้อมการดำเนินการ JavaScript ที่จะเรียกใช้สคริปต์ โดยมีค่าเริ่มต้นเป็น
`USER_SCRIPT`
ScriptSource
พร็อพเพอร์ตี้
-
รหัส
string ไม่บังคับ
สตริงที่มีโค้ด JavaScript สำหรับแทรก ต้องระบุ
file
หรือcode
อย่างใดอย่างหนึ่ง -
ไฟล์
string ไม่บังคับ
เส้นทางของไฟล์ JavaScript ที่จะแทรกโดยสัมพันธ์กับไดเรกทอรีรากของส่วนขยาย ต้องระบุ
file
หรือcode
อย่างใดอย่างหนึ่ง
UserScriptFilter
พร็อพเพอร์ตี้
-
ids
string[] ไม่บังคับ
โดย
getScripts
จะแสดงผลสคริปต์ที่มีรหัสที่ระบุไว้ในรายการนี้เท่านั้น
WorldProperties
พร็อพเพอร์ตี้
-
CSP
string ไม่บังคับ
ระบุ CSS ทั่วโลก ค่าเริ่มต้นคือ
`ISOLATED`
World CSP -
การรับส่งข้อความ
บูลีน ไม่บังคับ
ระบุว่าจะให้แสดง API การรับส่งข้อความหรือไม่ โดยมีค่าเริ่มต้นเป็น
false
วิธีการ
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
กำหนดค่าสภาพแวดล้อมการดำเนินการ `USER_SCRIPT`
พารามิเตอร์
-
พร็อพเพอร์ตี้
ประกอบด้วยการกำหนดค่าโลกแห่งสคริปต์ผู้ใช้
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
แสดงสคริปต์ผู้ใช้ที่ลงทะเบียนแบบไดนามิกทั้งหมดสำหรับส่วนขยายนี้
พารามิเตอร์
-
ฟิลเตอร์
UserScriptFilter ไม่บังคับ
หากระบุไว้ เมธอดนี้จะแสดงผลเฉพาะสคริปต์ผู้ใช้ที่ตรงกันเท่านั้น
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(scripts: RegisteredUserScript[]) => void
-
สคริปต์
-
การคืนสินค้า
-
Promise<RegisteredUserScript[]>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
ลงทะเบียนสคริปต์ผู้ใช้อย่างน้อยหนึ่งรายการสำหรับส่วนขยายนี้
พารามิเตอร์
-
สคริปต์
มีรายการสคริปต์ผู้ใช้ที่จะลงทะเบียน
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
ยกเลิกการลงทะเบียนสคริปต์ผู้ใช้ที่ลงทะเบียนแบบไดนามิกทั้งหมดสำหรับส่วนขยายนี้
พารามิเตอร์
-
ฟิลเตอร์
UserScriptFilter ไม่บังคับ
หากระบุไว้ วิธีนี้จะยกเลิกการลงทะเบียนเฉพาะสคริปต์ผู้ใช้ที่ตรงกันเท่านั้น
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
อัปเดตสคริปต์ผู้ใช้อย่างน้อย 1 รายการสำหรับส่วนขยายนี้
พารามิเตอร์
-
สคริปต์
มีรายการสคริปต์ผู้ใช้ที่จะอัปเดต พร็อพเพอร์ตี้จะได้รับการอัปเดตสำหรับสคริปต์ที่มีอยู่เฉพาะเมื่อระบุไว้ในออบเจ็กต์นี้เท่านั้น หากมีข้อผิดพลาดระหว่างการแยกวิเคราะห์สคริปต์/การตรวจสอบไฟล์ หรือหากรหัสที่ระบุไม่ตรงกับสคริปต์ที่ลงทะเบียนโดยสมบูรณ์ แสดงว่าไม่มีการอัปเดตสคริปต์
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ