Nội dung mô tả
Sử dụng API chrome.alarms
để lên lịch chạy mã theo định kỳ hoặc vào một thời điểm nhất định trong tương lai.
Quyền
alarms
Để sử dụng API chrome.alarms
, hãy khai báo quyền "alarms"
trong tệp kê khai:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
Khái niệm và cách sử dụng
Để đảm bảo hành vi đáng tin cậy, bạn cần hiểu rõ cách hoạt động của API.
Chế độ ngủ của thiết bị
Chuông báo sẽ tiếp tục chạy khi thiết bị ở chế độ ngủ. Tuy nhiên, chuông báo sẽ không đánh thức thiết bị. Khi thiết bị bật, mọi chuông báo bị bỏ lỡ sẽ kích hoạt. Chuông báo lặp lại sẽ kích hoạt tối đa một lần, sau đó được lên lịch lại bằng cách sử dụng khoảng thời gian đã chỉ định bắt đầu từ khi thiết bị đánh thức, không tính đến bất kỳ thời điểm nào đã trôi qua kể từ lúc chuông báo ban đầu được đặt để chạy.
Khả năng lưu trữ dài lâu
Chuông báo thường tồn tại cho đến khi tiện ích được cập nhật. Tuy nhiên, điều này không được đảm bảo và chuông báo có thể bị xoá khi trình duyệt khởi động lại. Do đó, hãy cân nhắc đặt một giá trị trong bộ nhớ khi tạo chuông báo và đảm bảo giá trị này tồn tại mỗi khi trình chạy dịch vụ của bạn khởi động. Ví dụ:
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();
Ví dụ
Các ví dụ sau đây minh hoạ cách sử dụng và phản hồi một chuông báo. Để dùng thử API này, hãy cài đặt ví dụ về Alarm API trong kho lưu trữ chrome-extension-samples.
Đặt chuông báo
Ví dụ sau đây đặt chuông báo trong trình chạy dịch vụ khi tiện ích được cài đặt:
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
});
});
Phản hồi chuông báo
Ví dụ sau đây đặt biểu tượng thanh công cụ thao tác dựa trên tên của chuông báo đã kêu.
service-worker.js:
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
Loại
Alarm
Thuộc tính
-
tên
string
Tên của chuông báo này.
-
periodInMinutes
số không bắt buộc
Nếu giá trị này không rỗng, thì chuông báo này là chuông báo lặp lại và sẽ kích hoạt lại sau
periodInMinutes
phút. -
scheduledTime
number
Thời gian mà vào lúc đó chuông báo này được lên lịch kích hoạt, tính bằng mili giây trước thời gian bắt đầu của hệ thống (ví dụ:
Date.now() + n
). Vì lý do về hiệu suất, chuông báo có thể đã bị trễ một khoảng thời gian tuỳ ý vượt quá khoảng thời gian này.
AlarmCreateInfo
Thuộc tính
-
delayInMinutes
số không bắt buộc
Khoảng thời gian tính bằng phút mà sau đó sự kiện
onAlarm
sẽ kích hoạt. -
periodInMinutes
số không bắt buộc
Nếu bạn đặt chính sách này, thì sự kiện onAlarm sẽ kích hoạt mỗi
periodInMinutes
phút sau sự kiện ban đầu dowhen
hoặcdelayInMinutes
chỉ định. Nếu bạn không đặt chính sách này, thì chuông báo sẽ chỉ kích hoạt một lần. -
khi
số không bắt buộc
Thời gian mà chuông báo sẽ kích hoạt, tính bằng mili giây trước thời gian bắt đầu của hệ thống (ví dụ:
Date.now() + n
).
Phương thức
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
Xoá chuông báo có tên đã đặt.
Tham số
-
tên
chuỗi không bắt buộc
Tên của chuông báo cần xoá. Giá trị mặc định là chuỗi trống.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Giá trị trả về
-
Promise<boolean>
Chrome 91 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
Xoá tất cả chuông báo.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Giá trị trả về
-
Promise<boolean>
Chrome 91 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
Tạo chuông báo. Khi gần đến(các) thời gian do alarmInfo
chỉ định, sự kiện onAlarm
sẽ được kích hoạt. Nếu có báo thức khác trùng tên (hoặc không có tên nếu không có tên nào được chỉ định), báo thức đó sẽ bị hủy và thay thế bằng báo thức này.
Để giảm tải cho máy của người dùng, Chrome sẽ giới hạn chuông báo ở mức tối đa 30 giây một lần nhưng có thể trì hoãn thêm một thời gian tuỳ ý. Tức là việc đặt delayInMinutes
hoặc periodInMinutes
thành giá trị nhỏ hơn 0.5
sẽ không được chấp nhận và sẽ tạo ra cảnh báo. Bạn có thể đặt when
thành chưa đến 30 giây sau "bây giờ" mà không cảnh báo, nhưng sẽ không thực sự khiến chuông báo kích hoạt trong ít nhất 30 giây.
Để giúp bạn gỡ lỗi ứng dụng hoặc tiện ích, khi bạn tải ứng dụng hoặc tiện ích đã giải nén, sẽ không có giới hạn về tần suất chuông báo có thể kích hoạt.
Tham số
-
tên
chuỗi không bắt buộc
Tên không bắt buộc để xác định chuông báo này. Giá trị mặc định là chuỗi trống.
-
alarmInfo
Mô tả thời điểm chuông báo sẽ kích hoạt. Thời gian ban đầu phải được chỉ định bằng
when
hoặcdelayInMinutes
(nhưng không được chỉ định cả hai). Nếu bạn đặtperiodInMinutes
, chuông báo sẽ lặp lạiperiodInMinutes
phút một lần sau sự kiện đầu tiên. Nếu bạn không đặtwhen
hoặcdelayInMinutes
cho chuông báo lặp lại, thìperiodInMinutes
sẽ được dùng làm chế độ mặc định chodelayInMinutes
. -
số gọi lại
hàm không bắt buộc
Chrome 111 trở lênTham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 111 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Truy xuất thông tin chi tiết về chuông báo đã chỉ định.
Tham số
-
tên
chuỗi không bắt buộc
Tên của chuông báo cần nhận. Giá trị mặc định là chuỗi trống.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(alarm?: Alarm) => void
-
chuông báo
Chuông báo không bắt buộc
-
Giá trị trả về
-
Promise<Alarm | undefined>
Chrome 91 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getAll()
chrome.alarms.getAll(
callback?: function,
)
Lấy một loạt tất cả chuông báo.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(alarms: Alarm[]) => void
-
các báo thức
-
Giá trị trả về
-
Hứa<Chuông báo[]>
Chrome 91 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
Sự kiện
onAlarm
chrome.alarms.onAlarm.addListener(
callback: function,
)
Được kích hoạt khi chuông báo đã trôi qua. Hữu ích cho các trang sự kiện.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(alarm: Alarm) => void
-
chuông báo
-