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
  });
});

หมายเหตุ: ตั้งแต่ Chrome 117 เป็นต้นไป จำนวนการปลุกที่ทำงานอยู่จะถูกจำกัดไว้ที่ 500 รายการ เมื่อถึงขีดจำกัดนี้แล้ว chrome.alarms.create() จะดำเนินการไม่สำเร็จ เมื่อใช้ Callback ระบบจะตั้งค่า chrome.runtime.lastError เมื่อใช้การให้สัญญา ระบบจะปฏิเสธคำสัญญา

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

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

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

  • การตั้งปลุก

    การปลุก