browser.runtime

คำอธิบาย

ใช้ chrome.runtime API เพื่อดึงข้อมูล Service Worker แสดงรายละเอียดเกี่ยวกับไฟล์ Manifest รวมถึงรับฟังและตอบสนองต่อเหตุการณ์ในวงจรส่วนขยาย นอกจากนี้ คุณยังใช้ API นี้เพื่อแปลงเส้นทางแบบสัมพัทธ์ของ URL เป็น URL แบบเต็มที่ถูกต้องได้ด้วย

สมาชิกส่วนใหญ่ของ API นี้ไม่ต้องมีสิทธิ์ใดๆ สิทธิ์นี้จำเป็นสำหรับ connectNative(), sendNativeMessage() และ onNativeConnect

ตัวอย่างต่อไปนี้แสดงวิธีประกาศสิทธิ์ "nativeMessaging" ในไฟล์ Manifest

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

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

Runtime API มีเมธอดที่รองรับหลายส่วนที่ส่วนขยายของคุณ ใช้ได้ ดังนี้

การส่งผ่านข้อความ
ส่วนขยายของคุณสามารถสื่อสารกับบริบทต่างๆ ภายในส่วนขยาย รวมถึงกับส่วนขยายอื่นๆ ได้โดยใช้วิธีการและเหตุการณ์ต่อไปนี้ connect() onConnect onConnectExternal sendMessage() onMessage และ onMessageExternal นอกจากนี้ ส่วนขยายยังส่งข้อความไปยังแอปพลิเคชันเนทีฟในอุปกรณ์ของผู้ใช้ได้โดยใช้ connectNative() และ sendNativeMessage()
การเข้าถึงข้อมูลเมตาของส่วนขยายและแพลตฟอร์ม
วิธีเหล่านี้ช่วยให้คุณดึงข้อมูลเมตาที่เฉพาะเจาะจงหลายรายการเกี่ยวกับส่วนขยายและแพลตฟอร์มได้ วิธีการในหมวดหมู่นี้ ได้แก่ getManifest() และ getPlatformInfo()
การจัดการวงจรและตัวเลือกของส่วนขยาย
พร็อพเพอร์ตี้เหล่านี้ช่วยให้คุณดำเนินการเมตาบางอย่างในส่วนขยายและแสดงหน้าตัวเลือกได้ วิธีการและเหตุการณ์ในหมวดหมู่นี้ ได้แก่ onInstalled onStartup openOptionsPage() reload() requestUpdateCheck() และ setUninstallURL()
ยูทิลิตีตัวช่วย
เมธอดเหล่านี้มีประโยชน์ เช่น การแปลงการแสดงทรัพยากรภายในเป็น รูปแบบภายนอก วิธีการในหมวดหมู่นี้ ได้แก่ getURL()
ยูทิลิตีโหมดคีออสก์
วิธีการเหล่านี้ใช้ได้เฉพาะใน ChromeOS และมีไว้เพื่อรองรับการใช้งานคีออสก์เป็นหลัก เมธอดในหมวดหมู่นี้ ได้แก่ restart() และ restartAfterDelay()`

ลักษณะการทำงานของส่วนขยายที่ไม่ได้แพ็ก

เมื่อโหลดซ้ำส่วนขยายที่คลายการแพคข้อมูล ระบบจะถือว่าเป็นการอัปเดต ซึ่งหมายความว่าเหตุการณ์ browser.runtime.onInstalled จะเริ่มทํางานด้วยเหตุผล "update" ซึ่งรวมถึงเมื่อโหลดส่วนขยายซ้ำด้วย browser.runtime.reload()

กรณีการใช้งาน

เพิ่มรูปภาพลงในหน้าเว็บ

หากต้องการให้หน้าเว็บเข้าถึงชิ้นงานที่โฮสต์ในโดเมนอื่นได้ หน้าเว็บนั้นต้องระบุ URL แบบเต็มของทรัพยากร (เช่น <img src="https://example.com/logo.png">) เช่นเดียวกับการรวมชิ้นงานส่วนขยายใน หน้าเว็บ ความแตกต่าง 2 อย่างคือต้องเปิดเผยชิ้นงานของส่วนขยายเป็นทรัพยากรที่เข้าถึงได้จากเว็บ และโดยปกติแล้ว สคริปต์เนื้อหาจะมีหน้าที่แทรกชิ้นงานของส่วนขยาย

ในตัวอย่างนี้ ส่วนขยายจะเพิ่ม logo.png ลงในหน้าที่ content script ถูกแทรกโดยใช้ runtime.getURL() เพื่อสร้าง URL ที่มีคุณสมบัติครบถ้วน แต่ก่อนอื่นต้องประกาศชิ้นงานเป็นทรัพยากรที่เข้าถึงได้บนเว็บในไฟล์ Manifest

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = browser.runtime.getURL('logo.png');
  document.body.append(img);
}

ส่งข้อมูลจาก Content Script ไปยัง Service Worker

โดยปกติแล้ว สคริปต์เนื้อหาของส่วนขยายจะต้องใช้ข้อมูลที่จัดการโดยส่วนอื่นๆ ของส่วนขยาย เช่น Service Worker บริบททั้ง 2 นี้ไม่สามารถเข้าถึงค่าของกันและกันได้โดยตรง เช่นเดียวกับหน้าต่างเบราว์เซอร์ 2 หน้าต่างที่เปิดไปยังหน้าเว็บเดียวกัน แต่ส่วนขยายจะใช้การส่งผ่านข้อความเพื่อประสานงานในบริบทต่างๆ เหล่านี้แทน

ในตัวอย่างนี้ Content Script ต้องการข้อมูลบางอย่างจาก Service Worker ของส่วนขยายเพื่อ เริ่มต้น UI หากต้องการรับข้อมูลนี้ ระบบจะส่งget-user-dataข้อความ ที่นักพัฒนาแอปกำหนดไปยัง Service Worker และ Service Worker จะตอบกลับด้วยสำเนาข้อมูลของผู้ใช้

content.js:

// 1. Send a message to the service worker requesting the user's data
browser.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

รวบรวมความคิดเห็นเกี่ยวกับการถอนการติดตั้ง

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

background.js:

browser.runtime.onInstalled.addListener(details => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    browser.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

ตัวอย่าง

ดูตัวอย่าง Runtime API เพิ่มเติมได้ที่ตัวอย่าง Manifest V3 - ทรัพยากรที่เข้าถึงได้จากเว็บ

ประเภท

ContextFilter

Chrome 114 ขึ้นไป

ตัวกรองที่ใช้จับคู่กับบริบทของส่วนขยายบางอย่าง บริบทที่ตรงกันต้องตรงกับตัวกรองที่ระบุทั้งหมด ส่วนตัวกรองที่ไม่ได้ระบุจะตรงกับบริบทที่มีอยู่ทั้งหมด ดังนั้น ตัวกรอง `{}` จะตรงกับบริบทที่มีอยู่ทั้งหมด

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

  • contextIds

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

  • contextTypes

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

  • documentIds

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

  • documentOrigins

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

  • documentUrls

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

  • frameIds

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

  • ไม่ระบุตัวตน

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

  • tabIds

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

  • windowIds

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

ContextType

Chrome 114 ขึ้นไป

ค่าแจกแจง

"TAB"
ระบุประเภทบริบทเป็นแท็บ

"POPUP"
ระบุประเภทบริบทเป็นหน้าต่างป๊อปอัปของส่วนขยาย

"BACKGROUND"
ระบุประเภทบริบทเป็น Service Worker

"OFFSCREEN_DOCUMENT"
ระบุประเภทบริบทเป็นเอกสารนอกหน้าจอ

"SIDE_PANEL"
ระบุประเภทบริบทเป็นแผงด้านข้าง

"DEVELOPER_TOOLS"
ระบุประเภทบริบทเป็นเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์

ExtensionContext

Chrome 114 ขึ้นไป

ส่วนขยายที่โฮสต์เนื้อหาบริบท

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

  • contextId

    สตริง

    ตัวระบุที่ไม่ซ้ำกันสำหรับบริบทนี้

  • contextType

    ContextType

    ประเภทบริบทที่สอดคล้องกับข้อมูลนี้

  • documentId

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

    UUID สำหรับเอกสารที่เชื่อมโยงกับบริบทนี้ หรือไม่ระบุหากบริบทนี้ไม่ได้โฮสต์ในเอกสาร

  • documentOrigin

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

    ต้นทางของเอกสารที่เชื่อมโยงกับบริบทนี้ หรือไม่ระบุหากบริบทไม่ได้โฮสต์ในเอกสาร

  • documentUrl

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

    URL ของเอกสารที่เชื่อมโยงกับบริบทนี้ หรือไม่ระบุหากบริบทไม่ได้โฮสต์ในเอกสาร

  • frameId

    ตัวเลข

    รหัสของเฟรมสำหรับบริบทนี้ หรือ -1 หากบริบทนี้ไม่ได้โฮสต์ในเฟรม

  • ไม่ระบุตัวตน

    บูลีน

    บริบทเชื่อมโยงกับโปรไฟล์ไม่ระบุตัวตนหรือไม่

  • tabId

    ตัวเลข

    รหัสของแท็บสำหรับบริบทนี้ หรือ -1 หากบริบทนี้ไม่ได้โฮสต์ในแท็บ

  • windowId

    ตัวเลข

    รหัสของหน้าต่างสำหรับบริบทนี้ หรือ -1 หากบริบทนี้ไม่ได้โฮสต์ในหน้าต่าง

MessageSender

ออบเจ็กต์ที่มีข้อมูลเกี่ยวกับบริบทของสคริปต์ที่ส่งข้อความหรือคำขอ

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

  • documentId

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

    Chrome 106 ขึ้นไป

    UUID ของเอกสารที่เปิดการเชื่อมต่อ

  • documentLifecycle

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

    Chrome 106 ขึ้นไป

    วงจรของเอกสารที่เปิดการเชื่อมต่อในขณะที่สร้างพอร์ต โปรดทราบว่าสถานะวงจรของเอกสารอาจมีการเปลี่ยนแปลงตั้งแต่สร้างพอร์ต

  • frameId

    หมายเลข ไม่บังคับ

    เฟรมที่เปิดการเชื่อมต่อ 0 สำหรับเฟรมระดับบนสุด ค่าบวกสำหรับเฟรมย่อย ระบบจะตั้งค่านี้เมื่อตั้งค่า tab เท่านั้น

  • id

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

    รหัสของส่วนขยายที่เปิดการเชื่อมต่อ (หากมี)

  • nativeApplication

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

    Chrome 74 ขึ้นไป

    ชื่อของแอปพลิเคชันแบบเนทีฟที่เปิดการเชื่อมต่อ (หากมี)

  • origin

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

    Chrome 80 ขึ้นไป

    ต้นทางของหน้าเว็บหรือเฟรมที่เปิดการเชื่อมต่อ ซึ่งอาจแตกต่างจากพร็อพเพอร์ตี้ URL (เช่น about:blank) หรืออาจทึบแสง (เช่น iframe ที่แซนด์บ็อกซ์) ซึ่งจะเป็นประโยชน์ในการระบุว่าแหล่งที่มาเชื่อถือได้หรือไม่ในกรณีที่เราไม่สามารถบอกได้ทันทีจาก URL

  • แท็บ

    แท็บ ไม่บังคับ

    tabs.Tab ที่เปิดการเชื่อมต่อ (หากมี) พร็อพเพอร์ตี้นี้จะแสดงเฉพาะเมื่อเปิดการเชื่อมต่อจากแท็บ (รวมถึง Content Script) และเฉพาะในกรณีที่ตัวรับเป็นส่วนขยาย ไม่ใช่แอป

  • tlsChannelId

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

    รหัสช่อง TLS ของหน้าเว็บหรือเฟรมที่เปิดการเชื่อมต่อ หากส่วนขยายขอและหากมี

  • URL

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

    URL ของหน้าเว็บหรือเฟรมที่เปิดการเชื่อมต่อ หากผู้ส่งอยู่ใน iframe จะเป็น URL ของ iframe ไม่ใช่ URL ของหน้าที่โฮสต์ iframe

OnInstalledReason

Chrome 44 ขึ้นไป

เหตุผลที่ส่งเหตุการณ์นี้

ค่าแจกแจง

"install"
ระบุเหตุผลของเหตุการณ์เป็นการติดตั้ง

"update"
ระบุเหตุผลของเหตุการณ์เป็นการอัปเดตส่วนขยาย

"chrome_update"
ระบุเหตุผลของเหตุการณ์เป็นการอัปเดต Chrome

"shared_module_update"
ระบุเหตุผลของเหตุการณ์เป็นการอัปเดตโมดูลที่แชร์

OnRestartRequiredReason

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"app_update"
ระบุเหตุผลของเหตุการณ์เป็นการอัปเดตแอป

"os_update"
ระบุเหตุผลของเหตุการณ์เป็นการอัปเดตระบบปฏิบัติการ

"periodic"
ระบุเหตุผลของเหตุการณ์เป็นการรีสตาร์ทแอปเป็นระยะๆ

PlatformArch

Chrome 44 ขึ้นไป

สถาปัตยกรรมของตัวประมวลผลของเครื่อง

ค่าแจกแจง

"arm"
ระบุสถาปัตยกรรมของโปรเซสเซอร์เป็น arm

"arm64"
ระบุสถาปัตยกรรมของโปรเซสเซอร์เป็น arm64

"x86-32"
ระบุสถาปัตยกรรมของโปรเซสเซอร์เป็น x86-32

"x86-64"
ระบุสถาปัตยกรรมของโปรเซสเซอร์เป็น x86-64

"mips"
ระบุสถาปัตยกรรมของโปรเซสเซอร์เป็น mips

"mips64"
ระบุสถาปัตยกรรมของโปรเซสเซอร์เป็น mips64

"riscv64"
ระบุสถาปัตยกรรมของโปรเซสเซอร์เป็น riscv64

PlatformInfo

ออบเจ็กต์ที่มีข้อมูลเกี่ยวกับแพลตฟอร์มปัจจุบัน

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

  • โค้ง

    PlatformArch

    สถาปัตยกรรมของตัวประมวลผลของเครื่อง

  • nacl_arch

    PlatformNaclArch ไม่บังคับ

    เลิกใช้งานตั้งแต่ Chrome 149

    เราเลิกใช้งานแอตทริบิวต์นี้หลังจากนำ Native Client ออกทั้งหมด

    สถาปัตยกรรมไคลเอ็นต์เนทีฟ ซึ่งอาจแตกต่างจาก arch ในบางแพลตฟอร์ม

  • ระบบปฏิบัติการที่ Chrome ทำงานอยู่

PlatformNaclArch

Chrome 44 ขึ้นไป เลิกใช้งานตั้งแต่ Chrome 149

เลิกใช้งานการแจงนับนี้แล้วหลังจากนำ Native Client ออกโดยสมบูรณ์

สถาปัตยกรรมไคลเอ็นต์เนทีฟ ซึ่งอาจแตกต่างจาก arch ในบางแพลตฟอร์ม

ค่าแจกแจง

"arm"
ระบุสถาปัตยกรรมไคลเอ็นต์ดั้งเดิมเป็น arm

"x86-32"
ระบุสถาปัตยกรรมไคลเอ็นต์ดั้งเดิมเป็น x86-32

"x86-64"
ระบุสถาปัตยกรรมไคลเอ็นต์ดั้งเดิมเป็น x86-64

"mips"
ระบุสถาปัตยกรรมไคลเอ็นต์ดั้งเดิมเป็น mips

"mips64"
ระบุสถาปัตยกรรมไคลเอ็นต์ดั้งเดิมเป็น mips64

PlatformOs

Chrome 44 ขึ้นไป

ระบบปฏิบัติการที่ Chrome ทำงานอยู่

ค่าแจกแจง

"mac"
ระบุระบบปฏิบัติการ MacOS

"win"
ระบุระบบปฏิบัติการ Windows

"android"
ระบุระบบปฏิบัติการ Android

"cros"
ระบุระบบปฏิบัติการ Chrome

"linux"
ระบุระบบปฏิบัติการ Linux

"openbsd"
ระบุระบบปฏิบัติการ OpenBSD

Port

ออบเจ็กต์ที่อนุญาตให้มีการสื่อสารแบบ 2 ทางกับหน้าอื่นๆ ดูข้อมูลเพิ่มเติมได้ที่การเชื่อมต่อที่ใช้งานได้นาน

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

  • name

    สตริง

    ชื่อพอร์ตตามที่ระบุในการเรียกใช้ runtime.connect

  • onDisconnect

    Event<functionvoidvoid>

    ทริกเกอร์เมื่อพอร์ตถูกตัดการเชื่อมต่อจากปลายทางอื่นๆ ระบบอาจตั้งค่า runtime.lastError หากพอร์ตถูกตัดการเชื่อมต่อเนื่องจากข้อผิดพลาด หากปิดพอร์ตผ่านยกเลิกการเชื่อมต่อ ระบบจะทริกเกอร์เหตุการณ์นี้เฉพาะที่ปลายทางอีกด้าน ระบบจะทริกเกอร์เหตุการณ์นี้อย่างมาก 1 ครั้ง (ดูอายุการใช้งานพอร์ตด้วย)

    ฟังก์ชัน onDisconnect.addListener มีลักษณะดังนี้ 

    (callback: function) => {...}

    • callback

      ฟังก์ชัน

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

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    เหตุการณ์นี้จะทริกเกอร์เมื่อปลายทางอีกด้านของพอร์ตเรียกใช้ postMessage

    ฟังก์ชัน onMessage.addListener มีลักษณะดังนี้ 

    (callback: function) => {...}

    • callback

      ฟังก์ชัน

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

      (message: any, port: Port) => void

  • ผู้ส่ง

    MessageSender ไม่บังคับ

    พร็อพเพอร์ตี้นี้จะปรากฏเฉพาะในพอร์ตที่ส่งไปยัง Listener onConnect / onConnectExternal / onConnectNative

  • ตัดการเชื่อมต่อ

    เป็นโมฆะ

    ถอดพอร์ตออกทันที การเรียก disconnect() ในพอร์ตที่ยกเลิกการเชื่อมต่อแล้วจะไม่มีผล เมื่อยกเลิกการเชื่อมต่อพอร์ต ระบบจะไม่ส่งเหตุการณ์ใหม่ไปยังพอร์ตนี้

    ฟังก์ชัน disconnect มีลักษณะดังนี้ 

    () => {...}

  • postMessage

    เป็นโมฆะ

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

    ฟังก์ชัน postMessage มีลักษณะดังนี้ 

    (message: any) => {...}

    • ข้อความ

      ใดๆ

      Chrome 52 ขึ้นไป

      ข้อความที่จะส่ง ออบเจ็กต์นี้ควรแปลงเป็น JSON ได้

RequestUpdateCheckStatus

Chrome 44 ขึ้นไป

ผลการตรวจสอบการอัปเดต

ค่าแจกแจง

"ถูกจำกัด"
ระบุว่าการตรวจสอบสถานะถูกจำกัด ปัญหานี้อาจเกิดขึ้นหลังจากตรวจสอบซ้ำๆ ในระยะเวลาอันสั้น

"no_update"
ระบุว่าไม่มีการอัปเดตที่พร้อมให้ติดตั้ง

"update_available"
ระบุว่ามีการอัปเดตที่พร้อมติดตั้ง

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

id

รหัสของส่วนขยาย/แอป

ประเภท

สตริง

lastError

มีข้อความแสดงข้อผิดพลาดหากการเรียกฟังก์ชัน API ไม่สำเร็จ หรือไม่เช่นนั้นจะเป็น "ไม่ระบุ" โดยจะกำหนดไว้ภายในขอบเขตของ Callback ของฟังก์ชันนั้นเท่านั้น หากเกิดข้อผิดพลาด แต่ไม่ได้เข้าถึง runtime.lastError ภายในโค้ดเรียกกลับ ระบบจะบันทึกข้อความไปยังคอนโซลซึ่งแสดงฟังก์ชัน API ที่ทำให้เกิดข้อผิดพลาด ฟังก์ชัน API ที่แสดงผล Promise จะไม่ตั้งค่าพร็อพเพอร์ตี้นี้

ประเภท

ออบเจ็กต์

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

  • ข้อความ

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

    รายละเอียดเกี่ยวกับข้อผิดพลาดที่เกิดขึ้น

เมธอด

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
): Port

พยายามเชื่อมต่อ Listener ภายในส่วนขยาย (เช่น หน้าพื้นหลัง) หรือส่วนขยาย/แอปอื่นๆ ซึ่งมีประโยชน์สำหรับ Content Script ที่เชื่อมต่อกับกระบวนการของส่วนขยาย การสื่อสารระหว่างแอป/ส่วนขยาย และการรับส่งข้อความบนเว็บ โปรดทราบว่าการดำเนินการนี้ไม่ได้เชื่อมต่อกับ Listener ใดๆ ใน Content Script ส่วนขยายอาจเชื่อมต่อกับ Content Script ที่ฝังอยู่ในแท็บผ่าน tabs.connect

พารามิเตอร์

  • extensionId

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

    รหัสของส่วนขยายที่จะเชื่อมต่อ หากไม่ระบุ ระบบจะพยายามเชื่อมต่อกับส่วนขยายของคุณเอง ต้องระบุหากส่งข้อความจากหน้าเว็บสำหรับการรับส่งข้อความบนเว็บ

  • connectInfo

    ออบเจ็กต์ ไม่บังคับ

    • includeTlsChannelId

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

      ว่าจะส่งรหัสช่อง TLS ไปยัง onConnectExternal สำหรับกระบวนการที่รอรับฟังเหตุการณ์การเชื่อมต่อหรือไม่

    • name

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

      จะส่งไปยัง onConnect สำหรับกระบวนการที่รอเหตุการณ์การเชื่อมต่อ

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

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

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

เชื่อมต่อกับแอปพลิเคชันแบบเนทีฟในเครื่องโฮสต์ วิธีนี้ต้องใช้สิทธิ์ "nativeMessaging" ดูข้อมูลเพิ่มเติมได้ที่การรับส่งข้อความดั้งเดิม

พารามิเตอร์

  • แอปพลิเคชัน

    สตริง

    ชื่อของแอปพลิเคชันที่ลงทะเบียนเพื่อเชื่อมต่อ

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

  • พอร์ตที่ใช้รับส่งข้อความกับแอปพลิเคชัน

getBackgroundPage()

เฉพาะเบื้องหน้า เลิกใช้งานตั้งแต่ Chrome 133
chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

หน้าพื้นหลังไม่มีอยู่ในส่วนขยาย MV3

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

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

  • Promise<Window | undefined>

    Chrome 99 ขึ้นไป

getContexts()

Chrome 116 ขึ้นไป MV3 ขึ้นไป 
chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

ดึงข้อมูลเกี่ยวกับบริบทที่ใช้งานอยู่ซึ่งเชื่อมโยงกับส่วนขยายนี้

พารามิเตอร์

  • ตัวกรอง

    ContextFilter

    ตัวกรองเพื่อค้นหาบริบทที่ตรงกัน บริบทจะตรงกันหากตรงกับช่องที่ระบุทั้งหมดในตัวกรอง ฟิลด์ที่ไม่ได้ระบุในตัวกรองจะตรงกับบริบททั้งหมด

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

  • Promise<ExtensionContext[]>

    Promise ที่จะแก้ไขด้วยบริบทที่ตรงกัน หากมี

getManifest()

chrome.runtime.getManifest(): object

แสดงรายละเอียดเกี่ยวกับแอปหรือส่วนขยายจากไฟล์ Manifest ออบเจ็กต์ที่ส่งคืนคือการซีเรียลไลซ์ไฟล์ Manifest แบบเต็ม

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

  • ออบเจ็กต์

    รายละเอียดไฟล์ Manifest

getPackageDirectoryEntry()

เบื้องหน้าเท่านั้น 
chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

แสดงผล DirectoryEntry สำหรับไดเรกทอรีแพ็กเกจ

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

  • Promise<DirectoryEntry>

    Chrome 122 ขึ้นไป

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

แสดงข้อมูลเกี่ยวกับแพลตฟอร์มปัจจุบัน

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

  • Promise<PlatformInfo>

    Chrome 99 ขึ้นไป

    Promise ที่จะแสดงข้อมูลเกี่ยวกับแพลตฟอร์มปัจจุบัน

getURL()

chrome.runtime.getURL(
  path: string,
): string

แปลงเส้นทางแบบสัมพัทธ์ภายในไดเรกทอรีการติดตั้งแอป/ส่วนขยายเป็น URL แบบเต็มที่ถูกต้อง

พารามิเตอร์

  • เส้นทาง

    สตริง

    เส้นทางไปยังทรัพยากรภายในแอป/ส่วนขยายที่แสดงเทียบกับไดเรกทอรีการติดตั้ง

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

  • สตริง

    URL ที่สมบูรณ์ในตัวเองของทรัพยากร

getVersion()

Chrome 143 ขึ้นไป 
chrome.runtime.getVersion(): string

แสดงผลเวอร์ชันของส่วนขยายตามที่ประกาศไว้ในไฟล์ Manifest

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

  • สตริง

    เวอร์ชันของส่วนขยาย

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise<void>

เปิดหน้าตัวเลือกของส่วนขยาย หากทำได้

ลักษณะการทำงานที่แน่นอนอาจขึ้นอยู่กับคีย์ options_ui หรือ options_page ของไฟล์ Manifest หรือสิ่งที่ Chrome รองรับในขณะนั้น เช่น ระบบอาจเปิดหน้าเว็บในแท็บใหม่ ภายใน chrome://extensions ภายในแอป หรืออาจเพียงแค่โฟกัสหน้าตัวเลือกที่เปิดอยู่ และจะไม่ทำให้หน้าเว็บที่เรียกใช้โหลดซ้ำ

หากส่วนขยายไม่ได้ประกาศหน้าตัวเลือก หรือ Chrome สร้างหน้าตัวเลือกไม่ได้ด้วยเหตุผลอื่นๆ การเรียกกลับจะตั้งค่า lastError

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

  • Promise<void>

    Chrome 99 ขึ้นไป

reload()

chrome.runtime.reload(): void

โหลดแอปหรือส่วนขยายซ้ำ โหมดคีออสก์ไม่รองรับวิธีนี้ สำหรับโหมดคีออสก์ ให้ใช้วิธี chrome.runtime.restart()

requestUpdateCheck()

chrome.runtime.requestUpdateCheck(): Promise<object>

ขอให้ตรวจสอบการอัปเดตแอป/ส่วนขยายนี้ทันที

สำคัญ: ส่วนขยาย/แอปส่วนใหญ่ไม่ควรใช้วิธีนี้ เนื่องจาก Chrome จะตรวจสอบโดยอัตโนมัติทุก 2-3 ชั่วโมงอยู่แล้ว และคุณสามารถรอรับเหตุการณ์ runtime.onUpdateAvailable ได้โดยไม่ต้องเรียกใช้ requestUpdateCheck

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

หมายเหตุ: เมื่อเรียกใช้ด้วย Callback ฟังก์ชันนี้จะส่งคืนพร็อพเพอร์ตี้ 2 รายการเป็นอาร์กิวเมนต์แยกต่างหากที่ส่งไปยัง Callback แทนที่จะส่งคืนออบเจ็กต์

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

  • Promise<object>

    Chrome 109 ขึ้นไป

restart()

chrome.runtime.restart(): void

รีสตาร์ทอุปกรณ์ ChromeOS เมื่อแอปทํางานในโหมดคีออสก์ ไม่เช่นนั้นจะไม่มีการดำเนินการใดๆ

restartAfterDelay()

Chrome 53 ขึ้นไป 
chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

รีสตาร์ทอุปกรณ์ ChromeOS เมื่อแอปทํางานในโหมดคีออสก์หลังจากผ่านไปตามจำนวนวินาทีที่ระบุ หากมีการเรียกใช้ฟังก์ชันอีกครั้งก่อนหมดเวลา ระบบจะเลื่อนการรีบูต หากเรียกใช้ด้วยค่า -1 ระบบจะยกเลิกการรีบูต ซึ่งจะไม่มีผลในโหมดที่ไม่ใช่โหมดคีออสก์ อนุญาตให้เรียกใช้ซ้ำๆ ได้โดยส่วนขยายแรกเท่านั้นเพื่อเรียกใช้ API นี้

พารามิเตอร์

  • วินาที

    ตัวเลข

    เวลารอเป็นวินาทีก่อนรีบูตอุปกรณ์ หรือ -1 เพื่อยกเลิกการรีบูตที่กำหนดเวลาไว้

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

  • Promise<void>

    Chrome 99 ขึ้นไป

    Promise ที่จะแก้ไขเมื่อกำหนดเวลาคำขอรีสตาร์ทใหม่เรียบร้อยแล้ว

sendMessage()

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

ส่งข้อความเดียวไปยังเครื่องมือฟังเหตุการณ์ภายในส่วนขยายหรือส่วนขยาย/แอปอื่น คล้ายกับ runtime.connect แต่จะส่งข้อความเดียวเท่านั้น โดยมีการตอบกลับที่ไม่บังคับ หากส่งไปยังส่วนขยาย ระบบจะทริกเกอร์เหตุการณ์ runtime.onMessage ในทุกเฟรมของส่วนขยาย (ยกเว้นเฟรมของผู้ส่ง) หรือ runtime.onMessageExternal หากเป็นส่วนขยายอื่น โปรดทราบว่าส่วนขยายไม่สามารถส่งข้อความไปยัง Content Script โดยใช้วิธีนี้ได้ หากต้องการส่งข้อความไปยัง Content Script ให้ใช้ tabs.sendMessage

พารามิเตอร์

  • extensionId

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

    รหัสของส่วนขยายที่จะส่งข้อความถึง หากไม่ระบุ ระบบจะส่งข้อความไปยังส่วนขยาย/แอปของคุณเอง ต้องระบุหากส่งข้อความจากหน้าเว็บสำหรับการรับส่งข้อความบนเว็บ

  • ข้อความ

    ใดๆ

    ข้อความที่จะส่ง ข้อความนี้ควรเป็นออบเจ็กต์ที่แปลงเป็น JSON ได้

  • ตัวเลือก

    ออบเจ็กต์ ไม่บังคับ

    • includeTlsChannelId

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

      ระบุว่าจะส่งรหัสช่อง TLS ไปยัง onMessageExternal สำหรับกระบวนการที่รอรับเหตุการณ์การเชื่อมต่อหรือไม่

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

  • Promise<any>

    Chrome 99 ขึ้นไป

    เราได้เพิ่มการรองรับ Promise สำหรับบริบทของส่วนขยายใน Chrome 99 เมื่อสื่อสารจากหน้าเว็บไปยังส่วนขยาย สัญญาจะพร้อมใช้งานจาก Chrome 118

sendNativeMessage()

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

ส่งข้อความเดียวไปยังแอปพลิเคชันแบบเนทีฟ วิธีนี้ต้องใช้สิทธิ์ "nativeMessaging"

พารามิเตอร์

  • แอปพลิเคชัน

    สตริง

    ชื่อของโฮสต์การรับส่งข้อความในเครื่อง หรือรายละเอียดเป้าหมาย

  • ข้อความ

    ออบเจ็กต์

    ข้อความที่จะส่งไปยังโฮสต์การรับส่งข้อความในเครื่อง

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

  • Promise<any>

    Chrome 99 ขึ้นไป

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

ตั้งค่า URL ที่จะเข้าชมเมื่อถอนการติดตั้ง ซึ่งอาจใช้เพื่อล้างข้อมูลฝั่งเซิร์ฟเวอร์ ทำการวิเคราะห์ และใช้แบบสำรวจ สูงสุด 1,023 อักขระ

พารามิเตอร์

  • URL

    สตริง

    URL ที่จะเปิดหลังจากถอนการติดตั้งส่วนขยาย URL นี้ต้องมีรูปแบบ http: หรือ https: ตั้งค่าสตริงว่างเพื่อไม่ให้เปิดแท็บใหม่เมื่อถอนการติดตั้ง

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

  • Promise<void>

    Chrome 99 ขึ้นไป

    Promise ที่จะทำงานเมื่อตั้งค่า URL การถอนการติดตั้ง หาก URL ที่ระบุไม่ถูกต้อง ระบบจะปฏิเสธสัญญา

กิจกรรม

onBrowserUpdateAvailable

เลิกใช้งานแล้ว
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

โปรดใช้ runtime.onRestartRequired

ทริกเกอร์เมื่อมีการอัปเดต Chrome แต่ไม่ได้ติดตั้งทันทีเนื่องจากต้องรีสตาร์ทเบราว์เซอร์

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

ทริกเกอร์เมื่อมีการเชื่อมต่อจากกระบวนการของส่วนขยายหรือ Content Script (โดย runtime.connect)

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (port: Port) => void

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

ทริกเกอร์เมื่อมีการเชื่อมต่อจากส่วนขยายอื่น (โดย runtime.connect) หรือจากเว็บไซต์ที่เชื่อมต่อภายนอกได้

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (port: Port) => void

onConnectNative

Chrome 76 ขึ้นไป 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

ทริกเกอร์เมื่อมีการเชื่อมต่อจากแอปพลิเคชันแบบเนทีฟ กิจกรรมนี้ต้องใช้สิทธิ์ "nativeMessaging" โดยรองรับเฉพาะใน ChromeOS

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (port: Port) => void

onEnabled

Chrome 155 ขึ้นไป 
chrome.runtime.onEnabled.addListener(
  callback: function,
)

ทริกเกอร์เมื่อส่วนขยายเปลี่ยนจากสถานะปิดใช้เป็นสถานะเปิดใช้

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    () => void

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

ทริกเกอร์เมื่อติดตั้งส่วนขยายเป็นครั้งแรก เมื่ออัปเดตส่วนขยายเป็นเวอร์ชันใหม่ และเมื่ออัปเดต Chrome เป็นเวอร์ชันใหม่

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (details: object) => void

    • รายละเอียด

      ออบเจ็กต์

      • id

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

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

      • previousVersion

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

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

      • เหตุผล

        OnInstalledReason

        เหตุผลที่ส่งเหตุการณ์นี้

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

ทริกเกอร์เมื่อมีการส่งข้อความจาก runtime.sendMessage หรือ tabs.sendMessage

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

    • ข้อความ

      ใดๆ

    • ผู้ส่ง

      MessageSender

    • sendResponse

      ฟังก์ชัน

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

      (response?: any) => void

      • การตอบกลับ

        ไม่บังคับ

        การตอบกลับที่จะส่งคืนให้ผู้ส่งข้อความ

    • returns

      boolean | Promise<any> | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

ทริกเกอร์เมื่อมีการส่งข้อความจากส่วนขยายอื่น (โดย runtime.sendMessage) ใช้ใน Content Script ไม่ได้

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

    • ข้อความ

      ใดๆ

    • ผู้ส่ง

      MessageSender

    • sendResponse

      ฟังก์ชัน

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

      (response?: any) => void

      • การตอบกลับ

        ไม่บังคับ

        การตอบกลับที่จะส่งคืนให้ผู้ส่งข้อความ

    • returns

      boolean | Promise<any> | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

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

พารามิเตอร์

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

ส่งหลังจาก onSuspend เพื่อระบุว่าระบบจะไม่นำแอปออก

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

ทริกเกอร์เมื่อมีการอัปเดต แต่ไม่ได้ติดตั้งทันทีเนื่องจากแอปกำลังทำงานอยู่ หากคุณไม่ดำเนินการใดๆ ระบบจะติดตั้งการอัปเดตในครั้งถัดไปที่หน้าพื้นหลังถูกยกเลิกการโหลด หากต้องการให้ติดตั้งเร็วขึ้น คุณสามารถเรียกใช้ chrome.runtime.reload() อย่างชัดเจนได้ หากส่วนขยายใช้หน้าพื้นหลังแบบถาวร หน้าพื้นหลังจะไม่ถูกยกเลิกการโหลด ดังนั้นหากคุณไม่เรียกใช้ chrome.runtime.reload() ด้วยตนเองเพื่อตอบสนองต่อเหตุการณ์นี้ ระบบจะไม่ติดตั้งการอัปเดตจนกว่า Chrome จะรีสตาร์ทในครั้งถัดไป หากไม่มีตัวแฮนเดิลที่รอรับฟังเหตุการณ์นี้ และส่วนขยายมีหน้าพื้นหลังแบบถาวร ส่วนขยายจะทำงานราวกับว่ามีการเรียกใช้ chrome.runtime.reload() เพื่อตอบสนองต่อเหตุการณ์นี้

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (details: object) => void

    • รายละเอียด

      ออบเจ็กต์

      • เวอร์ชัน

        สตริง

        หมายเลขเวอร์ชันของการอัปเดตที่พร้อมใช้งาน

onUserScriptConnect

Chrome 115 ขึ้นไป MV3 ขึ้นไป 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (port: Port) => void

onUserScriptMessage

Chrome 115 ขึ้นไป MV3 ขึ้นไป 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • ข้อความ

      ใดๆ

    • ผู้ส่ง

      MessageSender

    • sendResponse

      ฟังก์ชัน

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

      (response?: any) => void

      • การตอบกลับ

        ไม่บังคับ

        การตอบกลับที่จะส่งคืนให้ผู้ส่งข้อความ

    • returns

      บูลีน | ไม่ระบุ