chrome.userScripts

คำอธิบาย

ใช้ 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 120 ขึ้นไป MV3 ขึ้นไป

แนวคิดและการใช้งาน

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

โหมดนักพัฒนาซอฟต์แวร์สำหรับผู้ใช้ส่วนขยาย

ในฐานะนักพัฒนาส่วนขยาย คุณได้เปิดใช้โหมดนักพัฒนาซอฟต์แวร์ในการติดตั้ง Chrome แล้ว สำหรับส่วนขยายสคริปต์ของผู้ใช้ ผู้ใช้ของคุณจะต้องเปิดใช้โหมดนักพัฒนาซอฟต์แวร์ด้วย ซึ่งคุณจะคัดลอกและวางลงในเอกสารของตัวเองได้โดยทำดังนี้

  1. ไปที่หน้าส่วนขยายโดยป้อน chrome://extensions ในแท็บใหม่ (ออกแบบมาให้ลิงก์ URL chrome:// รายการไม่ได้)

  2. เปิดใช้โหมดนักพัฒนาซอฟต์แวร์โดยคลิกสวิตช์เปิด/ปิดข้างโหมดนักพัฒนาซอฟต์แวร์

    หน้าส่วนขยาย

    หน้าส่วนขยาย (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 ในโปรแกรมทำงานของบริการส่วนขยาย ตอบเฉพาะ"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[] ไม่บังคับ

    ระบุรูปแบบไวลด์การ์ดสำหรับหน้าที่จะแทรกสคริปต์ของผู้ใช้นี้

  • รายการออบเจ็กต์ 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`

พารามิเตอร์

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

    WorldProperties

    ประกอบด้วยการกำหนดค่าโลกแห่งสคริปต์ผู้ใช้

  • Callback

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

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

    ()=>void

การคืนสินค้า

  • Promise<void>

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getScripts()

สัญญา 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

แสดงสคริปต์ผู้ใช้ที่ลงทะเบียนแบบไดนามิกทั้งหมดสำหรับส่วนขยายนี้

พารามิเตอร์

  • ฟิลเตอร์

    UserScriptFilter ไม่บังคับ

    หากระบุไว้ เมธอดนี้จะแสดงผลเฉพาะสคริปต์ผู้ใช้ที่ตรงกันเท่านั้น

  • Callback

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

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

    (scripts: RegisteredUserScript[])=>void

การคืนสินค้า

  • Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

register()

สัญญา 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

ลงทะเบียนสคริปต์ผู้ใช้อย่างน้อยหนึ่งรายการสำหรับส่วนขยายนี้

พารามิเตอร์

  • สคริปต์

    RegisteredUserScript[]

    มีรายการสคริปต์ผู้ใช้ที่จะลงทะเบียน

  • 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 รายการสำหรับส่วนขยายนี้

พารามิเตอร์

  • สคริปต์

    RegisteredUserScript[]

    มีรายการสคริปต์ผู้ใช้ที่จะอัปเดต พร็อพเพอร์ตี้จะได้รับการอัปเดตสำหรับสคริปต์ที่มีอยู่เฉพาะเมื่อระบุไว้ในออบเจ็กต์นี้เท่านั้น หากมีข้อผิดพลาดระหว่างการแยกวิเคราะห์สคริปต์/การตรวจสอบไฟล์ หรือหากรหัสที่ระบุไม่ตรงกับสคริปต์ที่ลงทะเบียนโดยสมบูรณ์ แสดงว่าไม่มีการอัปเดตสคริปต์

  • Callback

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

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

    ()=>void

การคืนสินค้า

  • Promise<void>

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ