chrome.alarms

คำอธิบาย

ใช้ chrome.alarms API เพื่อกำหนดเวลาให้โค้ดทำงานเป็นระยะๆ หรือในเวลาที่ระบุในอนาคต

สิทธิ์

alarms

ไฟล์ Manifest

หากต้องการใช้ chrome.alarms API ให้ประกาศสิทธิ์ "alarms" ในไฟล์ Manifest ดังนี้

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

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงวิธีใช้และตอบสนองต่อการปลุก หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง Alarm API จากที่เก็บ chrome-extension-samples

ตั้งปลุก

ตัวอย่างต่อไปนี้จะตั้งปลุกใน Service Worker เมื่อมีการติดตั้งส่วนขยาย

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  if (reason !== 'install') {
    return;
  }

  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1
  });
});

ตอบสนองต่อการปลุก

ตัวอย่างต่อไปนี้จะตั้งค่าไอคอนแถบเครื่องมือการดำเนินการ ตามชื่อการปลุกที่ดังขึ้น

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

ประเภท

Alarm

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

  • name

    สตริง

    ชื่อของการปลุกนี้

  • periodInMinutes

    ตัวเลข ไม่บังคับ

    หากไม่ใช่ค่า Null การปลุกนี้จะเป็นการปลุกซ้ำและจะดังขึ้นอีกครั้งใน periodInMinutes นาที

  • persistAcrossSessions

    บูลีน

    Chrome 150 ขึ้นไป

    ระบุว่าการปลุกควรคงอยู่ข้ามเซสชัน (การรีสตาร์ทเบราว์เซอร์) หรือไม่

  • scheduledTime

    ตัวเลข

    เวลาเป็นมิลลิวินาทีหลัง Epoch (เช่น Date.now() + n) ที่กำหนดเวลาให้การปลุกนี้ดังขึ้น ทั้งนี้การปลุกอาจล่าช้ากว่าเวลาที่กำหนดไว้เล็กน้อยด้วยเหตุผลด้านประสิทธิภาพ

AlarmCreateInfo

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

  • delayInMinutes

    ตัวเลข ไม่บังคับ

    ระยะเวลาเป็นนาทีหลังจากนั้นเหตุการณ์ onAlarm ควรดังขึ้น

  • name

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

    Chrome 152 ขึ้นไป

    ชื่อของการปลุกนี้

  • periodInMinutes

    ตัวเลข ไม่บังคับ

    หากตั้งค่าไว้ เหตุการณ์ onAlarm ควรดังขึ้นทุกๆ periodInMinutes นาทีหลังจากเหตุการณ์เริ่มต้นที่ระบุโดย when หรือ delayInMinutes หากไม่ได้ตั้งค่าไว้ การปลุกจะดังขึ้นเพียงครั้งเดียว

  • persistAcrossSessions

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

    Chrome 150 ขึ้นไป

    ระบุว่าการปลุกควรคงอยู่ข้ามเซสชัน (การรีสตาร์ทเบราว์เซอร์) หรือไม่ ใน Chrome ค่าเริ่มต้นจะเป็น "จริง" เพื่อให้สอดคล้องกับลักษณะการทำงานในอดีต แต่คุณควรตั้งค่านี้อย่างชัดเจนเพื่อเพิ่มความเข้ากันได้สูงสุดในเบราว์เซอร์ต่างๆ

  • when

    ตัวเลข ไม่บังคับ

    เวลาเป็นมิลลิวินาทีหลัง Epoch (เช่น Date.now() + n) ที่การปลุกควรดังขึ้น

เมธอด

clear()

Promise 
chrome.alarms.clear(
  name?: string,
  callback?: function,
): Promise<boolean>

ล้างการปลุกที่มีชื่อที่ระบุ

พารามิเตอร์

  • name

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

    ชื่อการปลุกที่จะล้าง ค่าเริ่มต้นจะเป็นสตริงว่าง

  • callback

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

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

    (wasCleared: boolean) => void

    • wasCleared

      บูลีน

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

ล้างการปลุกทั้งหมด

พารามิเตอร์

  • callback

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

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

    (wasCleared: boolean) => void

    • wasCleared

      บูลีน

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

create()

Promise 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): Promise<void>

สร้างการปลุก เหตุการณ์ onAlarm จะดังขึ้นใกล้กับเวลาที่ระบุโดย alarmInfo หากมีการปลุกอื่นที่มีชื่อเดียวกัน (หรือไม่มีชื่อหากไม่ได้ระบุ) ระบบจะยกเลิกการปลุกนั้นและแทนที่ด้วยการปลุกนี้

Chrome จำกัดการปลุกไว้ที่อย่างน้อยทุกๆ 30 วินาที แต่ระบบอาจหน่วงเวลาการปลุกออกไปอีกเล็กน้อยเพื่อลดภาระงานในเครื่องของผู้ใช้ นั่นคือ การตั้งค่า delayInMinutes หรือ periodInMinutes ให้น้อยกว่า 0.5 จะไม่มีผลและจะทำให้เกิดคำเตือน คุณตั้งค่า when ให้น้อยกว่า 30 วินาทีหลังจาก "ตอนนี้" ได้โดยไม่มีคำเตือน แต่การปลุกจะไม่ดังขึ้นจริงอย่างน้อย 30 วินาที

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

พารามิเตอร์

  • name

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

    ชื่อที่ไม่บังคับเพื่อระบุการปลุกนี้ ค่าเริ่มต้นจะเป็นสตริงว่าง

  • alarmInfo

    AlarmCreateInfo

    อธิบายเวลาที่การปลุกควรดังขึ้น คุณต้องระบุเวลาเริ่มต้นด้วย when หรือ delayInMinutes อย่างใดอย่างหนึ่ง (แต่ไม่ใช่ทั้ง 2 อย่าง) หากตั้งค่า periodInMinutes ไว้ การปลุกจะดังซ้ำทุกๆ periodInMinutes นาทีหลังจากเหตุการณ์เริ่มต้น หากไม่ได้ตั้งค่า when หรือ delayInMinutes สำหรับการปลุกซ้ำ ระบบจะใช้ periodInMinutes เป็นค่าเริ่มต้นสำหรับ delayInMinutes

  • callback

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

    Chrome 111 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 111 ขึ้นไป

    Promise ที่แสดงผลเมื่อสร้างการปลุกแล้ว

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

get()

Promise 
chrome.alarms.get(
  name?: string,
  callback?: function,
): Promise<Alarm | undefined>

ดึงข้อมูลรายละเอียดเกี่ยวกับการปลุกที่ระบุ

พารามิเตอร์

  • name

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

    ชื่อการปลุกที่จะดึงข้อมูล ค่าเริ่มต้นจะเป็นสตริงว่าง

  • callback

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

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

    (alarm?: Alarm) => void

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

  • Promise<Alarm | undefined>

    Chrome 91 ขึ้นไป

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

รับอาร์เรย์ของการปลุกทั้งหมด

พารามิเตอร์

  • callback

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

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

    (alarms: Alarm[]) => void

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

  • Promise<Alarm[]>

    Chrome 91 ขึ้นไป

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

ดังขึ้นเมื่อการปลุกหมดเวลา มีประโยชน์สำหรับหน้ากิจกรรม

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (alarm: Alarm) => void