คำอธิบาย
ใช้ 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
อธิบายว่าสัญญาณเตือนควรเริ่มทำงานเมื่อใด เวลาเริ่มต้นต้องระบุด้วย
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,
)
ดึงรายละเอียดเกี่ยวกับการปลุกที่ระบุ
พารามิเตอร์
การคืนสินค้า
-
Promise<Alarm | undefined>
Chrome 91 ขึ้นไปManifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
getAll()
chrome.alarms.getAll(
callback?: function,
)
รับอาร์เรย์ของการปลุกทั้งหมด
พารามิเตอร์
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(alarms: Alarm[]) => void
-
การปลุก
-
การคืนสินค้า
-
สัญญา<Alarm[]>
Chrome 91 ขึ้นไปManifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ