chrome.alarms

คำอธิบาย

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

สิทธิ์

alarms

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

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

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

คุณควรทำความเข้าใจลักษณะการทำงานของ 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-sample

ตั้งปลุก

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

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

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

  • ชื่อ

    string

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

  • periodInMinutes

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

    หากไม่มีค่า Null การปลุกจะเป็นการตั้งปลุกซ้ำและจะเล่นอีกครั้งใน periodInMinutes นาที

  • scheduledTime

    ตัวเลข

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

AlarmCreateInfo

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

  • delayInMinutes

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

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

  • periodInMinutes

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

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

  • เมื่อใด

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

    เวลาที่การปลุกควรเริ่มทำงานเป็นมิลลิวินาทีหลังจาก Epoch (เช่น 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 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

clearAll()

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

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

พารามิเตอร์

  • Callback

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

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

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

  • Promise<boolean>

    Chrome 91 ขึ้นไป

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

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

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

  • Promise<void>

    Chrome 111 ขึ้นไป

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

get()

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

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

พารามิเตอร์

  • ชื่อ

    string ไม่บังคับ

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

  • Callback

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

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

    (alarm?: Alarm)=>void

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

  • สัญญา<นาฬิกาปลุก|undefined>

    Chrome 91 ขึ้นไป

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

getAll()

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

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

พารามิเตอร์

  • Callback

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

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

    (alarms: Alarm[])=>void

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

  • สัญญา<Alarm[]>

    Chrome 91 ขึ้นไป

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

กิจกรรม

onAlarm

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (alarm: Alarm)=>void