คำอธิบาย
ใช้ chrome.alarms API เพื่อกำหนดเวลาให้โค้ดทำงานเป็นระยะๆ หรือในเวลาที่ระบุในอนาคต
สิทธิ์
alarmsหากต้องการใช้ chrome.alarms API ให้ประกาศสิทธิ์ "alarms" ในไฟล์ Manifest ดังนี้
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
แนวคิดและการใช้งาน
การทำความเข้าใจลักษณะการทำงานของ API จะช่วยให้มั่นใจได้ว่า API จะทำงานได้อย่างน่าเชื่อถือ
อุปกรณ์เข้าสู่โหมดสลีป
การตั้งปลุกจะยังคงทำงานต่อไปขณะที่อุปกรณ์เข้าสู่โหมดสลีป อย่างไรก็ตาม การตั้งปลุกจะไม่ปลุกอุปกรณ์ เมื่ออุปกรณ์ตื่นขึ้น การตั้งปลุกที่พลาดไปจะเริ่มทำงาน การตั้งปลุกซ้ำจะเริ่มทำงานอย่างน้อย 1 ครั้ง แล้วกำหนดเวลาใหม่โดยใช้ช่วงเวลาที่ระบุโดยเริ่มจากเวลาที่อุปกรณ์ตื่นขึ้น โดยไม่คำนึงถึงเวลาที่ผ่านไปแล้วนับตั้งแต่มีการตั้งปลุกไว้เดิม
ความต่อเนื่อง
คุณสามารถควบคุมความต่อเนื่องของการตั้งปลุกได้ในตอนที่สร้างโดยใช้แฟล็ก persistAcrossSessions โดยตั้งค่าเป็น true (คงอยู่จนกว่าส่วนขยายจะอัปเดต) หรือ false (ล้างหากโหลดส่วนขยายซ้ำหรือเบราว์เซอร์รีสตาร์ท และทุกครั้งที่ส่วนขยายอัปเดต)
เบราว์เซอร์อื่นๆ และ Chrome เวอร์ชันก่อนหน้า
เบราว์เซอร์อื่นๆ (ปัญหา) หรือ Chrome เวอร์ชันก่อน Chrome 150 ไม่รองรับพร็อพเพอร์ตี้นี้ ซึ่งอาจทำให้เกิดลักษณะการทำงานที่ไม่คาดคิด ดังนั้น คุณควรตรวจสอบว่ามีการตั้งปลุกที่สำคัญทุกครั้งที่ Service Worker เริ่มทำงาน เช่น
async function checkAlarmState() {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
}
}
checkAlarmState();
หากสร้างการตั้งปลุกแบบไดนามิกตามการดำเนินการของผู้ใช้ คุณอาจต้องการจัดเก็บข้อมูลว่ามีการสร้างการตั้งปลุกไว้ที่อื่น เพื่อให้ทราบว่าต้องสร้างการตั้งปลุกนั้นขึ้นมาใหม่หากจำเป็น
ตัวอย่าง
ตัวอย่างต่อไปนี้แสดงวิธีใช้และตอบสนองต่อการตั้งปลุก หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง Alarm API จากที่เก็บ chrome-extension-samples
ตั้งปลุก
ตัวอย่างต่อไปนี้จะตั้งปลุกใน Service Worker เมื่อมีการติดตั้งส่วนขยายเวอร์ชันใหม่
service-worker.js:
chrome.runtime.onInstalled.addListener(async ({ reason }) => {
// Create an alarm so we have something to look at in the demo
await chrome.alarms.create('demo-default-alarm', {
delayInMinutes: 1,
periodInMinutes: 1,
persistAcrossSessions: true
});
});
ตอบสนองต่อการตั้งปลุก
ตัวอย่างต่อไปนี้จะตั้งค่าไอคอนแถบเครื่องมือการดำเนินการตามชื่อของการตั้งปลุกที่เริ่มทำงาน
service-worker.js:
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
ประเภท
Alarm
พร็อพเพอร์ตี้
-
name
สตริง
ชื่อของการตั้งปลุกนี้
-
periodInMinutes
ตัวเลข ไม่บังคับ
หากไม่ใช่ค่า Null การตั้งปลุกจะเป็นการตั้งปลุกซ้ำและจะเริ่มทำงานอีกครั้งในอีก
periodInMinutesนาที -
persistAcrossSessions
บูลีน
Chrome 150 ขึ้นไประบุว่าการตั้งปลุกควรคงอยู่ข้ามเซสชัน (เบราว์เซอร์รีสตาร์ท) หรือไม่
-
scheduledTime
ตัวเลข
เวลาเป็นมิลลิวินาทีหลัง Epoch (เช่น
Date.now() + n) ที่กำหนดเวลาให้การตั้งปลุกนี้เริ่มทำงาน ระบบอาจเลื่อนการตั้งปลุกออกไปเป็นระยะเวลาหนึ่งเพื่อประสิทธิภาพ
AlarmCreateInfo
พร็อพเพอร์ตี้
-
delayInMinutes
ตัวเลข ไม่บังคับ
ระยะเวลาเป็นนาทีหลังจากที่เหตุการณ์
onAlarmควรเริ่มทำงาน -
name
สตริง ไม่บังคับ
Chrome 152 ขึ้นไปชื่อของการตั้งปลุกนี้
-
periodInMinutes
ตัวเลข ไม่บังคับ
หากตั้งค่าไว้ เหตุการณ์ onAlarm ควรเริ่มทำงานทุกๆ
periodInMinutesนาทีหลังจากเหตุการณ์เริ่มต้นที่ระบุโดยwhenหรือdelayInMinutesหากไม่ได้ตั้งค่าไว้ การตั้งปลุกจะเริ่มทำงานเพียงครั้งเดียว -
persistAcrossSessions
บูลีน ไม่บังคับ
Chrome 150 ขึ้นไประบุว่าการตั้งปลุกควรคงอยู่ข้ามเซสชัน (เบราว์เซอร์รีสตาร์ท) หรือไม่ ใน Chrome ค่าเริ่มต้นจะเป็น "จริง" เพื่อให้ตรงกับลักษณะการทำงานในอดีต แต่คุณควรตั้งค่านี้อย่างชัดเจนเพื่อเพิ่มความเข้ากันได้สูงสุดในเบราว์เซอร์ต่างๆ
-
when
ตัวเลข ไม่บังคับ
เวลาเป็นมิลลิวินาทีหลัง Epoch (เช่น
Date.now() + n) ที่การตั้งปลุกควรเริ่มทำงาน
เมธอด
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
ล้างการตั้งปลุกที่มีชื่อที่ระบุ
พารามิเตอร์
-
name
สตริง ไม่บังคับ
ชื่อของการตั้งปลุกที่จะล้าง ค่าเริ่มต้นจะเป็นสตริงว่าง
การคืนสินค้า
-
Promise<boolean>
Chrome 91 ขึ้นไป
clearAll()
chrome.alarms.clearAll(): Promise<boolean>
ล้างการตั้งปลุกทั้งหมด
การคืนสินค้า
-
Promise<boolean>
Chrome 91 ขึ้นไป
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
สร้างการตั้งปลุก เหตุการณ์ onAlarm จะเริ่มทำงานใกล้กับเวลาที่ระบุโดย alarmInfo หากมีการตั้งปลุกอื่นที่มีชื่อเดียวกัน (หรือไม่มีชื่อหากไม่ได้ระบุ) ระบบจะยกเลิกการตั้งปลุกนั้นและแทนที่ด้วยการตั้งปลุกนี้
Chrome จำกัดการตั้งปลุกไว้ที่อย่างน้อย 1 ครั้งทุกๆ 30 วินาที แต่ระบบอาจเลื่อนการตั้งปลุกออกไปอีกระยะเวลาหนึ่งเพื่อลดภาระงานในเครื่องของผู้ใช้ นั่นคือ ระบบจะไม่ยอมรับการตั้งค่า delayInMinutes หรือ periodInMinutes ให้น้อยกว่า 0.5 และจะแสดงคำเตือน คุณสามารถตั้งค่า when ให้น้อยกว่า 30 วินาทีหลังจาก "ตอนนี้" ได้โดยไม่มีคำเตือน แต่การตั้งปลุกจะไม่เริ่มทำงานอย่างน้อย 30 วินาที
เมื่อคุณโหลดแอปหรือส่วนขยายแบบคลายการแพคข้อมูลไว้ ระบบจะไม่มีการจำกัดความถี่ที่สัญญาณปลุกจะเริ่มทำงาน เพื่อช่วยคุณในการแก้ไขข้อบกพร่องของแอปหรือส่วนขยาย
พารามิเตอร์
-
name
สตริง ไม่บังคับ
ชื่อที่ไม่บังคับเพื่อระบุการตั้งปลุกนี้ ค่าเริ่มต้นจะเป็นสตริงว่าง
-
alarmInfo
อธิบายเวลาที่การตั้งปลุกควรเริ่มทำงาน คุณต้องระบุเวลาเริ่มต้นด้วย
whenหรือdelayInMinutesอย่างใดอย่างหนึ่ง (แต่ไม่ใช่ทั้ง 2 อย่าง) หากตั้งค่าperiodInMinutesไว้ การตั้งปลุกจะทำซ้ำทุกๆperiodInMinutesนาทีหลังจากเหตุการณ์เริ่มต้น หากไม่ได้ตั้งค่าwhenหรือdelayInMinutesสำหรับการตั้งปลุกซ้ำ ระบบจะใช้periodInMinutesเป็นค่าเริ่มต้นสำหรับdelayInMinutes
การคืนสินค้า
-
Promise<void>
Chrome 111 ขึ้นไปPromise ที่แสดงผลเมื่อมีการสร้างการตั้งปลุก
get()
chrome.alarms.get(
name?: string,
): Promise<Alarm | undefined>
ดึงข้อมูลรายละเอียดเกี่ยวกับการตั้งปลุกที่ระบุ
พารามิเตอร์
-
name
สตริง ไม่บังคับ
ชื่อของการตั้งปลุกที่จะดึงข้อมูล ค่าเริ่มต้นจะเป็นสตริงว่าง
การคืนสินค้า
-
Promise<Alarm | undefined>
Chrome 91 ขึ้นไป
การคืนสินค้า
-
Promise<Alarm[]>
Chrome 91 ขึ้นไป