คำอธิบาย
ใช้ chrome.alarms API เพื่อตั้งเวลาให้โค้ดทำงานเป็นระยะๆ หรือตามเวลาที่ระบุในอนาคต
สิทธิ์
alarmsหากต้องการใช้ chrome.alarms API ให้ประกาศสิทธิ์ "alarms" ในไฟล์ Manifest ดังนี้
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
แนวคิดและการใช้งาน
คุณควรทำความเข้าใจลักษณะการทำงานของ API เพื่อดูแลให้มีลักษณะการทำงานที่เชื่อถือได้
โหมดสลีปของอุปกรณ์
เสียงปลุกจะทำงานต่อไปขณะที่อุปกรณ์อยู่ในโหมดสลีป อย่างไรก็ตาม การปลุกจะไม่คง ปลุกระบบอุปกรณ์ เมื่ออุปกรณ์ทำงานอยู่ การปลุกที่ไม่ได้เปิดจะเริ่มทำงาน การปลุกซ้ำจะเริ่มทํางานมากที่สุดครั้งเดียว จากนั้นจะมีการตั้งเวลาใหม่โดยใช้ ระยะเวลาที่ระบุนับตั้งแต่เวลาที่อุปกรณ์เริ่มทำงาน โดยไม่คํานึงถึง เวลาใดก็ตามที่ล่วงเลยไปแล้วนับตั้งแต่การปลุกถูกตั้งให้ทำงาน
ความต่อเนื่อง
โดยทั่วไปการปลุกจะยังคงอยู่จนกว่าจะมีการอัปเดตส่วนขยาย อย่างไรก็ตาม เราไม่รับประกันว่าจะเกิดเหตุการณ์เช่นนี้ และการปลุก อาจล้างออกเมื่อรีสตาร์ทเบราว์เซอร์ ดังนั้นให้ลองตั้งค่าในพื้นที่เก็บข้อมูล เมื่อมีการสร้างการปลุก และตรวจสอบให้แน่ใจว่ามีการปลุกทุกครั้งที่โปรแกรมทำงานของบริการเริ่มต้นทำงาน เช่น
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หากไม่ได้ตั้งค่า สัญญาณเตือนจะเริ่มทำงานเพียงครั้งเดียว -
เมื่อใด
หมายเลข ไม่บังคับ
เวลาที่การปลุกควรเริ่มทำงานเป็นมิลลิวินาทีหลังช่วงเวลา (เช่น
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 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
ล้างการปลุกทั้งหมด
พารามิเตอร์
-
Callback
ไม่บังคับ
พารามิเตอร์
callbackมีลักษณะดังนี้(wasCleared: boolean) => void
-
wasCleared
boolean
-
การคืนสินค้า
-
Promise<boolean>
Chrome 91 ขึ้นไปรองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง 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
อธิบายว่าสัญญาณเตือนควรเริ่มทำงานเมื่อใด เวลาเริ่มต้นต้องระบุด้วย
whenหรือdelayInMinutes(ไม่ใช่ทั้ง 2 อย่าง) หากตั้งค่าperiodInMinutesไว้ การปลุกจะเกิดซ้ำทุกperiodInMinutesนาทีหลังจากเหตุการณ์เริ่มต้น หากไม่มีการตั้งค่าwhenหรือdelayInMinutesสำหรับการปลุกซ้ำ ระบบจะใช้periodInMinutesเป็นค่าเริ่มต้นสำหรับdelayInMinutes -
Callback
ไม่บังคับ
Chrome 111 ขึ้นไปพารามิเตอร์
callbackมีลักษณะดังนี้() => void
การคืนสินค้า
-
คำมั่นสัญญา<โมฆะ>
Chrome 111 ขึ้นไปรองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
เรียกดูรายละเอียดเกี่ยวกับการปลุกที่ระบุ
พารามิเตอร์
การคืนสินค้า
-
Promise<Alarm | ไม่ระบุ>
Chrome 91 ขึ้นไปรองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback
getAll()
chrome.alarms.getAll(
callback?: function,
)
รับอาร์เรย์ของการปลุกทั้งหมด
พารามิเตอร์
การคืนสินค้า
-
สัญญา <นาฬิกาปลุก[]>
Chrome 91 ขึ้นไปรองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback