chrome.alarms

คำอธิบาย

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

สิทธิ์

alarms

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

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

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

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

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

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

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

โดยทั่วไปแล้ว การปลุกจะยังคงอยู่จนกว่าจะมีการอัปเดตส่วนขยาย อย่างไรก็ตาม ไม่มีการรับประกันว่าระบบจะล้างสัญญาณเตือน เมื่อรีสตาร์ทเบราว์เซอร์ ดังนั้น โปรดตรวจสอบว่ามีอยู่ทุกครั้งที่ 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 }) => {
  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

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

  • ชื่อ

    สตริง

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

  • periodInMinutes

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

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

  • scheduledTime

    ตัวเลข

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

AlarmCreateInfo

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

  • delayInMinutes

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

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

  • periodInMinutes

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

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

  • เมื่อใด

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

    เวลาที่ควรปลุกเป็นมิลลิวินาทีหลังจาก 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>

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

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