browser.alarms

คำอธิบาย

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

สิทธิ์

alarms

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

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

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

การทำความเข้าใจลักษณะการทำงานของ API จะช่วยให้มั่นใจได้ว่าลักษณะการทำงานจะเชื่อถือได้

อุปกรณ์เข้าสู่โหมดสลีป

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

ความต่อเนื่อง

คุณควบคุมความต่อเนื่องของการปลุกได้ในเวลาที่สร้างโดยใช้แฟล็ก persistAcrossSessions โดยสามารถตั้งค่าเป็น true (คงอยู่จนกว่าส่วนขยายจะอัปเดต) หรือ false (ล้างออกหากโหลดส่วนขยายซ้ำหรือรีสตาร์ทเบราว์เซอร์ และเมื่อใดก็ตามที่ส่วนขยายอัปเดต)

เบราว์เซอร์อื่นๆ และ Chrome เวอร์ชันก่อนหน้า

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

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

  if (!alarm) {
    await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

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

ตัวอย่าง

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

ตั้งปลุก

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

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

ตอบสนองต่อสัญญาณเตือน

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

service-worker.js:

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

ประเภท

Alarm

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

• name

  สตริง

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

• periodInMinutes

  number ไม่บังคับ

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

• persistAcrossSessions

  บูลีน

  Chrome 150 ขึ้นไป

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

• scheduledTime

  ตัวเลข

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

AlarmCreateInfo

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

• delayInMinutes

  number ไม่บังคับ

  ระยะเวลาเป็นนาทีหลังจากที่เหตุการณ์ onAlarm ควรเริ่มทำงาน

• name

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

  Chrome 152 ขึ้นไป

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

• periodInMinutes

  number ไม่บังคับ

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

• persistAcrossSessions

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

  Chrome 150 ขึ้นไป

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

• เมื่อใด

  number ไม่บังคับ

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

เมธอด

clear()

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

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

พารามิเตอร์

• name

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

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

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

• Promise<boolean>

  Chrome 91 ขึ้นไป

clearAll()

chrome.alarms.clearAll(): Promise<boolean | undefined>

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

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

• Promise<boolean | undefined>

  Chrome 91 ขึ้นไป

create()

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

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

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

พารามิเตอร์

• name

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

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

• alarmInfo

  AlarmCreateInfo

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

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

• Promise<void>

  Chrome 111 ขึ้นไป

  Promise ที่จะได้รับการแก้ไขเมื่อสร้างการปลุกแล้ว

get()

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

เรียกดูรายละเอียดเกี่ยวกับการปลุกที่ระบุ

พารามิเตอร์

• name

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

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

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

• Promise<Alarm | undefined>

  Chrome 91 ขึ้นไป

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

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

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

• Promise<Alarm[]>

  Chrome 91 ขึ้นไป

กิจกรรม

onAlarm

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

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

  (alarm: Alarm) => void

  • การตั้งปลุก

    การปลุก