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 ใน Service Worker ของส่วนขยาย ตอบสนองต่อเหตุผล "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 ค่าเริ่มต้นคือเท็จ ซึ่งหมายความว่าระบบจะจับคู่เฉพาะเฟรมด้านบน

  • excludeGlobs

    string[] ไม่บังคับ

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

  • excludeMatches

    string[] ไม่บังคับ

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

  • id

    สตริง

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

  • includeGlobs

    string[] ไม่บังคับ

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

  • js

    ScriptSource[] ไม่บังคับ

    รายการออบเจ็กต์ ScriptSource ที่กําหนดแหล่งที่มาของสคริปต์ที่จะแทรกลงในหน้าเว็บที่ตรงกัน คุณต้องระบุพร็อพเพอร์ตี้นี้สำหรับ ${ref:register} และเมื่อระบุแล้ว ต้องเป็นอาร์เรย์ที่ไม่ใช่ค่าว่าง

  • ตรงกับ

    string[] ไม่บังคับ

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

  • runAt

    RunAt ไม่บังคับ

    ระบุเวลาที่ระบบจะแทรกไฟล์ JavaScript ลงในหน้าเว็บ ค่าที่แนะนำและค่าเริ่มต้นคือ document_idle

  • โลก

    ExecutionWorld ไม่บังคับ

    สภาพแวดล้อมการเรียกใช้ JavaScript เพื่อเรียกใช้สคริปต์ โดยมีค่าเริ่มต้นเป็น `USER_SCRIPT`

  • worldId

    สตริง ไม่บังคับ

    รอดำเนินการ

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

ScriptSource

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

  • รหัส

    สตริง ไม่บังคับ

    สตริงที่มีโค้ด JavaScript ที่จะแทรก ต้องระบุ file หรือ code อย่างใดอย่างหนึ่งที่แน่นอน

  • ไฟล์

    สตริง ไม่บังคับ

    เส้นทางของไฟล์ JavaScript ที่จะแทรกซึ่งสัมพันธ์กับไดเรกทอรีรูทของส่วนขยาย ต้องระบุ file หรือ code อย่างใดอย่างหนึ่งที่แน่นอน

UserScriptFilter

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

  • ids

    string[] ไม่บังคับ

    getScripts จะแสดงเฉพาะสคริปต์ที่มีรหัสที่ระบุไว้ในรายการนี้

WorldProperties

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

  • csp

    สตริง ไม่บังคับ

    ระบุ csp ทั่วโลก ค่าเริ่มต้นคือ `ISOLATED` world csp

  • ส่งข้อความ

    บูลีน ไม่บังคับ

    ระบุว่าจะแสดง API การรับส่งข้อความหรือไม่ โดยมีค่าเริ่มต้นเป็น false

  • worldId

    สตริง ไม่บังคับ

    รอดำเนินการ

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

เมธอด

configureWorld()

สัญญา 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

กําหนดค่าสภาพแวดล้อมการดําเนินการของ `USER_SCRIPT`

พารามิเตอร์

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

    WorldProperties

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

  • Callback

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

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

    () => void

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

  • Promise<void>

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

getScripts()

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

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

พารามิเตอร์

  • ตัวกรอง

    UserScriptFilter ไม่บังคับ

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

  • Callback

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

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

    (scripts: RegisteredUserScript[]) => void

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

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

getWorldConfigurations()

สัญญา รอดำเนินการ
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

ดึงข้อมูลการกำหนดค่าโลกที่ลงทะเบียนไว้ทั้งหมด

พารามิเตอร์

  • Callback

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

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

    (worlds: WorldProperties[]) => void

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

  • Promise<WorldProperties[]>

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

register()

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

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

พารามิเตอร์

  • สคริปต์

    RegisteredUserScript[]

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

  • Callback

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

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

    () => void

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

  • Promise<void>

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

resetWorldConfiguration()

สัญญา รอดำเนินการ
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

พารามิเตอร์

  • worldId

    สตริง ไม่บังคับ

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

  • Callback

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

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

    () => void

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

  • Promise<void>

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

unregister()

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

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

พารามิเตอร์

  • ตัวกรอง

    UserScriptFilter ไม่บังคับ

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

  • Callback

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

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

    () => void

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

  • Promise<void>

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

update()

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

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

พารามิเตอร์

  • สคริปต์

    RegisteredUserScript[]

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

  • Callback

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

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

    () => void

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

  • Promise<void>

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