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 ในแท็บใหม่ (ตามการออกแบบ chrome:// URL ไม่สามารถลิงก์ได้)

  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 ใน 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[] ไม่บังคับ

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

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

พารามิเตอร์

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

    WorldProperties

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

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

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

getScripts()

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

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

พารามิเตอร์

  • ตัวกรอง

    UserScriptFilter ไม่บังคับ

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

  • Callback

    ไม่บังคับ

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

    (scripts: RegisteredUserScript[]) => void

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

  • Promise&lt;RegisteredUserScript[]&gt;

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

register()

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

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

พารามิเตอร์

  • สคริปต์

    RegisteredUserScript[]

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

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

พารามิเตอร์

  • สคริปต์

    RegisteredUserScript[]

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

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

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