Deskripsi
Gunakan chrome.alarms
API untuk menjadwalkan kode agar dijalankan secara berkala atau pada waktu yang ditentukan di masa mendatang.
Izin
alarms
Untuk menggunakan chrome.alarms
API, deklarasikan izin "alarms"
dalam manifes:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
Konsep dan penggunaan
Untuk memastikan perilaku yang andal, sebaiknya pahami perilaku API.
Mode tidur perangkat
Alarm akan terus berjalan saat perangkat sedang tidur. Namun, alarm tidak akan mengaktifkan perangkat. Saat perangkat aktif, semua alarm yang terlewat akan berbunyi. Alarm berulang akan terpicu paling banyak satu kali, lalu dijadwalkan ulang menggunakan periode yang ditentukan mulai dari saat perangkat aktif, tidak memperhitungkan waktu yang telah berlalu sejak alarm awalnya disetel untuk berjalan.
Persistensi
Alarm biasanya tetap ada sampai ekstensi diperbarui. Namun, hal ini tidak dijamin, dan alarm dapat dihapus saat browser dimulai ulang. Oleh karena itu, pertimbangkan untuk menyetel nilai dalam penyimpanan saat alarm dibuat, lalu pastikan ada nilai tersebut setiap kali pekerja layanan dimulai. Contoh:
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();
Contoh
Contoh berikut menunjukkan cara menggunakan dan merespons alarm. Untuk mencoba API ini, instal contoh Alarm API dari repositori chrome-extension-samples.
Setel alarm
Contoh berikut menyetel alarm di pekerja layanan bila ekstensi diinstal:
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
});
});
Merespons alarm
Contoh berikut menetapkan ikon toolbar tindakan berdasarkan nama alarm yang berbunyi.
service-worker.js:
chrome.alarms.onAlarm.addListener((alarm) => {
chrome.action.setIcon({
path: getIconPath(alarm.name),
});
});
Jenis
Alarm
Properti
-
name
string
Nama alarm ini.
-
periodInMinutes
nomor opsional
Jika bukan null, alarm adalah alarm berulang dan akan dipicu lagi dalam
periodInMinutes
menit. -
scheduledTime
angka
Waktu saat alarm ini dijadwalkan untuk dipicu, dalam milidetik setelah epoch (misalnya
Date.now() + n
). Untuk alasan performa, alarm mungkin telah tertunda selama jumlah arbitrer melebihi ini.
AlarmCreateInfo
Properti
-
delayInMinutes
nomor opsional
Durasi waktu dalam menit setelah peristiwa
onAlarm
diaktifkan. -
periodInMinutes
nomor opsional
Jika ditetapkan, peristiwa onAlarm akan diaktifkan setiap
periodInMinutes
menit setelah peristiwa awal yang ditentukan olehwhen
ataudelayInMinutes
. Jika tidak disetel, alarm hanya akan dipicu sekali. -
when
nomor opsional
Waktu saat alarm harus dipicu, dalam milidetik setelah epoch (misalnya,
Date.now() + n
).
Metode
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
Menghapus alarm dengan nama yang diberikan.
Parameter
-
name
string opsional
Nama alarm yang akan dihapus. Default-nya adalah string kosong.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Hasil
-
Promise<boolean>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
Menghapus semua alarm.
Parameter
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(wasCleared: boolean) => void
-
wasCleared
boolean
-
Hasil
-
Promise<boolean>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
Membuat alarm. Di dekat waktu yang ditentukan oleh alarmInfo
, peristiwa onAlarm
diaktifkan. Jika ada alarm lain dengan nama yang sama (atau tanpa nama jika tidak ada yang ditentukan), alarm akan dibatalkan dan diganti dengan alarm ini.
Untuk mengurangi beban pada komputer pengguna, Chrome membatasi alarm paling banyak sekali setiap 30 detik, tetapi mungkin menundanya lebih banyak lagi. Artinya, menetapkan delayInMinutes
atau periodInMinutes
ke kurang dari 0.5
tidak akan diterapkan dan akan menyebabkan peringatan. when
dapat disetel ke kurang dari 30 detik setelah "sekarang" tanpa peringatan, tetapi tidak akan benar-benar menyebabkan alarm terpicu selama minimal 30 detik.
Untuk membantu Anda men-debug aplikasi atau ekstensi, setelah Anda memuatnya secara terbuka, tidak ada batasan seberapa sering alarm dapat terpicu.
Parameter
-
name
string opsional
Nama opsional untuk mengidentifikasi alarm ini. Default-nya adalah string kosong.
-
alarmInfo
Menjelaskan kapan alarm harus berbunyi. Waktu awal harus ditentukan oleh
when
ataudelayInMinutes
(tetapi tidak keduanya). JikaperiodInMinutes
disetel, alarm akan berulang setiapperiodInMinutes
menit setelah peristiwa awal. Jikawhen
ataudelayInMinutes
tidak disetel untuk alarm berulang,periodInMinutes
akan digunakan sebagai default untukdelayInMinutes
. -
callback
fungsi opsional
Chrome 111 dan yang lebih baruParameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 111 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
Mengambil detail tentang alarm yang ditentukan.
Parameter
Hasil
-
Promise<Alarm | undefined>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getAll()
chrome.alarms.getAll(
callback?: function,
)
Mendapatkan array semua alarm.
Parameter
Hasil
-
Promise<Alarm[]>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.