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