chrome.alarms

คำอธิบาย

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

สิทธิ์

alarms

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

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

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

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

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

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

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

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

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

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

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

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

checkAlarmState();

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

ตัวอย่าง

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

ตั้งปลุก

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

service-worker.js:

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

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

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

service-worker.js:

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

ประเภท

Alarm

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

  • ชื่อ

    สตริง

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

  • periodInMinutes

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

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

  • persistAcrossSessions

    บูลีน

    รอดำเนินการ

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

  • scheduledTime

    ตัวเลข

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

AlarmCreateInfo

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

  • delayInMinutes

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

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

  • periodInMinutes

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

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

  • persistAcrossSessions

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

    รอดำเนินการ

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

  • เมื่อใด

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

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

เมธอด

clear()

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

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

พารามิเตอร์

  • ชื่อ

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

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

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

clearAll()

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

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

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

create()

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

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

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

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

พารามิเตอร์

  • ชื่อ

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

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

  • alarmInfo

    AlarmCreateInfo

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

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

  • Promise<void>

    Chrome 111 ขึ้นไป

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

get()

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

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

พารามิเตอร์

  • ชื่อ

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

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

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

  • 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