คำอธิบาย
ใช้ 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
ในแท็บใหม่ (ตามการออกแบบchrome://
URL ไม่สามารถลิงก์ได้) เปิดใช้โหมดนักพัฒนาซอฟต์แวร์โดยคลิกสวิตช์เปิด/ปิดข้างโหมดนักพัฒนาซอฟต์แวร์
หน้าส่วนขยาย (chrome://extensions)
คุณสามารถตรวจสอบว่ามีการเปิดใช้งานโหมดนักพัฒนาซอฟต์แวร์หรือไม่โดยตรวจสอบว่า 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
ใน Service Worker ของส่วนขยาย ตอบกลับเฉพาะเหตุผล "update"
รายการที่ส่งไปยัง Callback ของเหตุการณ์
ตัวอย่าง
ตัวอย่างนี้มาจากตัวอย่าง userScript ในที่เก็บตัวอย่างของเรา
ลงทะเบียนสคริปต์
ตัวอย่างต่อไปนี้แสดงการเรียกใช้ register()
แบบพื้นฐาน อาร์กิวเมนต์แรกคืออาร์เรย์ของออบเจ็กต์ที่กำหนดสคริปต์ที่จะลงทะเบียน มีตัวเลือกมากกว่าที่แสดงอยู่ที่นี่
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
ประเภท
ExecutionWorld
โลก JavaScript ที่สคริปต์ผู้ใช้จะเรียกใช้งาน
ค่าแจกแจง
"MAIN"
ระบุสภาพแวดล้อมการดำเนินการของ DOM ซึ่งเป็นสภาพแวดล้อมการดำเนินการที่แชร์กับ JavaScript ของหน้าโฮสต์
"USER_script"
ระบุสภาพแวดล้อมการดำเนินการที่มีเฉพาะในสคริปต์ของผู้ใช้และได้รับการยกเว้นจาก CSP ของหน้าเว็บ
RegisteredUserScript
พร็อพเพอร์ตี้
-
allFrames
บูลีน ไม่บังคับ
หากเป็น "จริง" ระบบจะแทรกลงในเฟรมทั้งหมดแม้ว่าเฟรมจะไม่ใช่เฟรมบนสุดในแท็บ แต่ละเฟรมจะได้รับการตรวจสอบแยกกันสำหรับข้อกําหนดของ URL ระบบจะไม่แทรกเฟรมย่อยหากไม่เป็นไปตามข้อกำหนดของ URL ค่าเริ่มต้นคือ "เท็จ" ซึ่งหมายความว่าระบบจะจับคู่เฉพาะเฟรมบนสุดเท่านั้น
-
excludeGlobs
string[] ไม่บังคับ
ระบุรูปแบบไวลด์การ์ดสำหรับหน้าที่จะไม่มีการแทรกสคริปต์ของผู้ใช้นี้ลงไป
-
excludeMatches
string[] ไม่บังคับ
ยกเว้นหน้าที่จะแทรกสคริปต์ของผู้ใช้นี้ลงไป ดูรูปแบบการจับคู่สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับไวยากรณ์ของสตริงเหล่านี้
-
id
สตริง
รหัสของสคริปต์ผู้ใช้ที่ระบุในการเรียก 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
พร็อพเพอร์ตี้
-
รหัส
string[] ไม่บังคับ
getScripts
จะแสดงผลสคริปต์ที่มีรหัสที่ระบุไว้ในรายการนี้เท่านั้น
WorldProperties
พร็อพเพอร์ตี้
-
CSP
string ไม่บังคับ
ระบุ CSP ของโลก ค่าเริ่มต้นคือ
`ISOLATED`
World CSS -
ข้อความ
บูลีน ไม่บังคับ
ระบุว่าจะแสดง API การรับส่งข้อความหรือไม่ โดยมีค่าเริ่มต้นเป็น
false
เมธอด
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
กำหนดค่าสภาพแวดล้อมการดำเนินการของ `USER_SCRIPT`
พารามิเตอร์
-
พร็อพเพอร์ตี้
ประกอบด้วยการกำหนดค่าโลกของสคริปต์ของผู้ใช้
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
คำมั่นสัญญา<โมฆะ>
รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
แสดงสคริปต์ผู้ใช้ที่ลงทะเบียนแบบไดนามิกทั้งหมดสำหรับส่วนขยายนี้
พารามิเตอร์
-
ตัวกรอง
UserScriptFilter ไม่บังคับ
หากระบุ เมธอดนี้จะส่งคืนเฉพาะสคริปต์ผู้ใช้ที่ตรงกันเท่านั้น
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(scripts: RegisteredUserScript[]) => void
-
สคริปต์
-
การคืนสินค้า
-
Promise<RegisteredUserScript[]>
รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
ลงทะเบียนสคริปต์ผู้ใช้อย่างน้อย 1 รายการสำหรับส่วนขยายนี้
พารามิเตอร์
-
สคริปต์
ประกอบด้วยรายการสคริปต์ของผู้ใช้ที่จะลงทะเบียน
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
คำมั่นสัญญา<โมฆะ>
รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
ยกเลิกการลงทะเบียนสคริปต์ผู้ใช้ที่ลงทะเบียนแบบไดนามิกทั้งหมดสำหรับส่วนขยายนี้
พารามิเตอร์
-
ตัวกรอง
UserScriptFilter ไม่บังคับ
หากระบุ วิธีนี้จะยกเลิกการลงทะเบียนเฉพาะสคริปต์ผู้ใช้ที่ตรงกันเท่านั้น
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
คำมั่นสัญญา<โมฆะ>
รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
อัปเดตสคริปต์ผู้ใช้อย่างน้อย 1 รายการสำหรับส่วนขยายนี้
พารามิเตอร์
-
สคริปต์
มีรายการสคริปต์ของผู้ใช้ที่จะอัปเดต ระบบจะอัปเดตคุณสมบัติสำหรับสคริปต์ที่มีอยู่ก็ต่อเมื่อมีการระบุไว้ในออบเจ็กต์นี้ หากมีข้อผิดพลาดระหว่างการแยกวิเคราะห์สคริปต์/การตรวจสอบไฟล์ หรือหากรหัสที่ระบุไม่ตรงกับสคริปต์ที่ลงทะเบียนอย่างสมบูรณ์ ก็จะไม่มีการอัปเดตสคริปต์
-
Callback
ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
คำมั่นสัญญา<โมฆะ>
รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback