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

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

  • ชื่อ

    สตริง

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

  • 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 ขึ้นไป

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

clearAll()

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

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (wasCleared: boolean) => void

    • wasCleared

      boolean

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ 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 ขึ้นไป

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

get()

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

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

พารามิเตอร์

  • ชื่อ

    string ไม่บังคับ

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

  • Callback

    ไม่บังคับ

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

    (alarm?: Alarm) => void

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

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

    Chrome 91 ขึ้นไป

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

getAll()

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

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (alarms: Alarm[]) => void

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

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

    Chrome 91 ขึ้นไป

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

กิจกรรม

onAlarm

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (alarm: Alarm) => void