chrome.alarms

คำอธิบาย

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

สิทธิ์

alarms

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

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

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

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

โหมดสลีปของอุปกรณ์

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

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

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

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

    if (!alarm) {
      await chrome.alarms.create({ 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

    ตัวเลข

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

AlarmCreateInfo

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

  • delayInMinutes

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

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

  • periodInMinutes

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

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

  • เมื่อใด

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

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

เมธอด

clear()

สัญญา 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

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

พารามิเตอร์

  • ชื่อ

    string ไม่บังคับ

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

  • Callback

    ไม่บังคับ

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

    (wasCleared: boolean) => void

    • wasCleared

      boolean

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

clearAll()

สัญญา 
chrome.alarms.clearAll(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (wasCleared: boolean) => void

    • wasCleared

      boolean

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

create()

สัญญา 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

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

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

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

พารามิเตอร์

  • ชื่อ

    string ไม่บังคับ

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

  • alarmInfo

    AlarmCreateInfo

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

  • Callback

    ไม่บังคับ

    Chrome 111 ขึ้นไป

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 111 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

get()

สัญญา 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

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

พารามิเตอร์

  • ชื่อ

    string ไม่บังคับ

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

  • Callback

    ไม่บังคับ

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

    (alarm?: Alarm) => void

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

  • Promise&lt;Alarm | ไม่ระบุ>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

getAll()

สัญญา 
chrome.alarms.getAll(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (alarms: Alarm[]) => void

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

  • สัญญา <นาฬิกาปลุก[]>

    Chrome 91 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

กิจกรรม

onAlarm

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (alarm: Alarm) => void