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 นาที

  • persistAcrossSessions

    บูลีน

    Chrome 150 ขึ้นไป

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

  • scheduledTime

    ตัวเลข

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

AlarmCreateInfo

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

  • delayInMinutes

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

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

  • periodInMinutes

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

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

  • persistAcrossSessions

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

    Chrome 150 ขึ้นไป

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

  • เมื่อใด

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

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

เมธอด

clear()

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

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

พารามิเตอร์

  • ชื่อ

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

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

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (wasCleared: boolean) => void

    • wasCleared

      บูลีน

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

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

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

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

พารามิเตอร์

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (wasCleared: boolean) => void

    • wasCleared

      บูลีน

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

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

create()

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

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

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

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

พารามิเตอร์

  • ชื่อ

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

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

  • alarmInfo

    AlarmCreateInfo

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

  • callback

    ฟังก์ชัน ไม่บังคับ

    Chrome 111 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 111 ขึ้นไป

    Promise ที่จะทำงานเมื่อสร้างการปลุกแล้ว

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

get()

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

ดึงรายละเอียดเกี่ยวกับสัญญาณเตือนที่ระบุ

พารามิเตอร์

  • ชื่อ

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

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

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (alarm?: Alarm) => void

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

  • Promise<Alarm | undefined>

    Chrome 91 ขึ้นไป

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

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

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

พารามิเตอร์

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (alarms: Alarm[]) => void

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

  • Promise<Alarm[]>

    Chrome 91 ขึ้นไป

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

กิจกรรม

onAlarm

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (alarm: Alarm) => void