chrome.alarms

คำอธิบาย

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

สิทธิ์

alarms

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

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

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

คุณควรทำความเข้าใจลักษณะการทํางานของ API เพื่อให้มั่นใจว่า API จะทํางานอย่างถูกต้อง

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

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

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

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

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 หากไม่ได้ตั้งค่าไว้ การปลุกจะทำงานเพียงครั้งเดียว

  • เมื่อใด

    ตัวเลข ไม่บังคับ

    เวลาที่ตั้งปลุกไว้เป็นมิลลิวินาทีนับจาก Epoch (เช่น Date.now() + n)

เมธอด

clear()

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

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

พารามิเตอร์

  • ชื่อ

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

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

  • Callback

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

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

    (wasCleared: boolean) => void

    • wasCleared

      บูลีน

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

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

clearAll()

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

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

พารามิเตอร์

  • Callback

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

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

    (wasCleared: boolean) => void

    • wasCleared

      บูลีน

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

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

create()

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

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

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

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

พารามิเตอร์

  • ชื่อ

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

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

  • alarmInfo

    AlarmCreateInfo

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

  • Callback

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

    Chrome 111 ขึ้นไป

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

    () => void

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

  • Promise<void>

    Chrome 111 ขึ้นไป

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

get()

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

ดึงข้อมูลรายละเอียดเกี่ยวกับการปลุกที่ระบุ

พารามิเตอร์

  • ชื่อ

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

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

  • Callback

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

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

    (alarm?: Alarm) => void

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

  • Promise<Alarm | undefined>

    Chrome 91 ขึ้นไป

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

getAll()

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

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

พารามิเตอร์

  • Callback

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

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

    (alarms: Alarm[]) => void

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

  • Promise<Alarm[]>

    Chrome 91 ขึ้นไป

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

กิจกรรม

onAlarm

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (alarm: Alarm) => void