chrome.alarms

Deskripsi

Gunakan chrome.alarms API untuk menjadwalkan kode agar berjalan secara berkala atau pada waktu tertentu 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 dalam mode tidur. Namun, alarm tidak akan mengaktifkan perangkat. Saat perangkat aktif, alarm yang terlewat akan berbunyi. Alarm berulang akan berbunyi paling banyak satu kali, lalu dijadwalkan ulang menggunakan periode yang ditentukan, mulai dari saat perangkat aktif, tanpa memperhitungkan waktu yang telah berlalu sejak alarm awalnya disetel untuk berbunyi.

Persistensi

Anda dapat mengontrol persistensi alarm pada waktu pembuatan menggunakan flag persistAcrossSessions. Flag ini dapat disetel ke true (tetap ada hingga ekstensi diupdate) atau false (dihapus jika ekstensi dimuat ulang atau browser dimulai ulang, dan setiap kali ekstensi diupdate).

Browser lain dan Chrome versi sebelumnya

Properti ini tidak didukung di browser lain (masalah) atau di Chrome versi sebelum Chrome 150, yang perilakunya tidak dapat diprediksi. Oleh karena itu, sebaiknya pastikan alarm penting ada setiap kali service worker Anda dimulai. Contoh:

async function checkAlarmState() {
  const alarm = await chrome.alarms.get("my-alarm");

  if (!alarm) {
    await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

Jika alarm dibuat secara dinamis berdasarkan tindakan pengguna, Anda mungkin ingin menyimpan informasi bahwa alarm dibuat di tempat lain sehingga Anda tahu cara membuatnya ulang jika diperlukan.

Contoh

Contoh berikut menunjukkan cara menggunakan dan merespons alarm. Untuk mencoba API ini, instal contoh Alarm API dari repositori chrome-extension-samples.

Menyetel alarm

Contoh berikut menyetel alarm di service worker saat versi baru ekstensi diinstal:

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
  });
});

Merespons alarm

Contoh berikut menyetel 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

  • nama

    string

    Nama alarm ini.

  • periodInMinutes

    angka opsional

    Jika tidak null, alarm adalah alarm berulang dan akan berbunyi lagi dalam periodInMinutes menit.

  • persistAcrossSessions

    boolean

    Chrome 150+

    Apakah alarm harus tetap ada di seluruh sesi (browser dimulai ulang).

  • scheduledTime

    angka

    Waktu saat alarm ini dijadwalkan untuk berbunyi, dalam milidetik setelah epoch (misalnya, Date.now() + n). Karena alasan performa, alarm mungkin tertunda dalam jumlah yang tidak ditentukan di luar waktu ini.

AlarmCreateInfo

Properti

  • delayInMinutes

    angka opsional

    Durasi waktu dalam menit setelah peristiwa onAlarm harus berbunyi.

  • periodInMinutes

    angka opsional

    Jika disetel, peristiwa onAlarm akan berbunyi setiap periodInMinutes menit setelah peristiwa awal yang ditentukan oleh when atau delayInMinutes. Jika tidak disetel, alarm hanya akan berbunyi satu kali.

  • persistAcrossSessions

    boolean opsional

    Chrome 150+

    Apakah alarm harus tetap ada di seluruh sesi (browser dimulai ulang). Di Chrome, nilai defaultnya adalah benar (true) agar sesuai dengan perilaku historis, tetapi Anda harus menetapkannya secara eksplisit untuk memaksimalkan kompatibilitas di seluruh browser.

  • kapan

    angka opsional

    Waktu saat alarm harus berbunyi, dalam milidetik setelah epoch (misalnya, Date.now() + n).

Metode

clear()

chrome.alarms.clear(
  name?: string,
): Promise<boolean>

Menghapus alarm dengan nama yang diberikan.

Parameter

  • nama

    string opsional

    Nama alarm yang akan dihapus. Nilai defaultnya adalah string kosong.

Hasil

  • Promise<boolean>

    Chrome 91+

clearAll()

chrome.alarms.clearAll(): Promise<boolean>

Menghapus semua alarm.

Hasil

  • Promise<boolean>

    Chrome 91+

create()

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

Membuat alarm. Mendekati waktu yang ditentukan oleh alarmInfo, peristiwa onAlarm akan diaktifkan. Jika ada alarm lain dengan nama yang sama (atau tanpa nama jika tidak ada yang ditentukan), alarm tersebut akan dibatalkan dan diganti dengan alarm ini.

Untuk mengurangi beban pada mesin pengguna, Chrome membatasi alarm menjadi paling banyak sekali setiap 30 detik, tetapi mungkin menundanya dalam jumlah yang tidak ditentukan. Artinya, menyetel delayInMinutes atau periodInMinutes ke kurang dari 0.5 tidak akan dipenuhi dan akan menyebabkan peringatan. when dapat disetel ke kurang dari 30 detik setelah "sekarang" tanpa peringatan, tetapi sebenarnya tidak akan menyebabkan alarm berbunyi selama minimal 30 detik.

Untuk membantu Anda men-debug aplikasi atau ekstensi, jika Anda telah memuatnya tanpa dikemas, tidak ada batasan frekuensi alarm dapat berbunyi.

Parameter

  • nama

    string opsional

    Nama opsional untuk mengidentifikasi alarm ini. Nilai defaultnya adalah string kosong.

  • alarmInfo

    AlarmCreateInfo

    Menjelaskan kapan alarm harus berbunyi. Waktu awal harus ditentukan oleh when atau delayInMinutes (tetapi tidak keduanya). Jika periodInMinutes disetel, alarm akan berulang setiap periodInMinutes menit setelah peristiwa awal. Jika when atau delayInMinutes tidak disetel untuk alarm berulang, periodInMinutes akan digunakan sebagai default untuk delayInMinutes.

Hasil

  • Promise<void>

    Chrome 111+

    Promise yang di-resolve saat alarm telah dibuat.

get()

chrome.alarms.get(
  name?: string,
): Promise<Alarm | undefined>

Mengambil detail tentang alarm yang ditentukan.

Parameter

  • nama

    string opsional

    Nama alarm yang akan didapatkan. Nilai defaultnya adalah string kosong.

Hasil

  • Promise<Alarm | undefined>

    Chrome 91+

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

Mendapatkan array dari semua alarm.

Hasil

  • Promise<Alarm[]>

    Chrome 91+

Acara

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

Diaktifkan saat alarm telah berlalu. Berguna untuk halaman peristiwa.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (alarm: Alarm) => void