chrome.alarms

Deskripsi

Gunakan chrome.alarms API untuk menjadwalkan kode untuk dijalankan 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.

Tidur perangkat

Alarm terus berjalan saat perangkat tidur. Namun, alarm tidak akan mengaktifkan perangkat. Saat perangkat bangun, setiap alarm yang terlewat akan berbunyi. Alarm berulang akan berbunyi paling banyak sekali dan kemudian dijadwalkan ulang menggunakan periode tertentu mulai dari saat perangkat aktif, tanpa mempertimbangkan yang telah berlalu sejak alarm awalnya disetel untuk berjalan.

Persistensi

Alarm biasanya tetap ada hingga ekstensi diupdate. Namun, hal ini tidak dijamin, dan alarm dapat dihapus ketika browser dimulai ulang. Oleh karena itu, pertimbangkan untuk menetapkan nilai dalam penyimpanan ketika alarm dibuat, lalu memastikannya ada 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 chrome-extension-samples repositori resource.

Setel alarm

Contoh berikut menyetel alarm di pekerja layanan saat 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

  • nama

    string

    Nama alarm ini.

  • periodInMinutes

    angka opsional

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

  • scheduledTime

    angka

    Waktu saat alarm ini dijadwalkan untuk dipicu, dalam milidetik setelah epoch (mis. Date.now() + n). Karena alasan performa, alarm mungkin telah tertunda dalam jumlah berapa pun setelah ini.

AlarmCreateInfo

Properti

  • delayInMinutes

    angka opsional

    Durasi waktu dalam menit setelah peristiwa onAlarm harus diaktifkan.

  • periodInMinutes

    angka opsional

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

  • kapan

    angka opsional

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

Metode

clear()

Janji 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Menghapus alarm yang diberi nama.

Parameter

  • nama

    string opsional

    Nama alarm yang akan dihapus. Default-nya adalah string kosong.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Hasil

  • Promise<boolean>

    Chrome 91 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

clearAll()

Janji 
chrome.alarms.clearAll(
  callback?: function,
)

Menghapus semua alarm.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (wasCleared: boolean) => void

    • wasCleared

      boolean

Hasil

  • Promise<boolean>

    Chrome 91 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

create()

Janji 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

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

Untuk mengurangi beban komputer pengguna, Chrome membatasi alarm paling tidak sekali setiap 30 detik, tetapi mungkin menundanya lebih banyak lagi. Artinya, menetapkan delayInMinutes atau periodInMinutes ke kurang dari 0.5 tidak akan diabaikan dan akan menyebabkan peringatan. when dapat disetel menjadi kurang dari 30 detik setelah "sekarang" tanpa peringatan, tetapi tidak benar-benar menyebabkan alarm aktif selama minimal 30 detik.

Untuk membantu Anda men-debug aplikasi atau ekstensi, setelah Anda memuatnya dari paket, tidak ada batas seberapa sering alarm dapat terpicu.

Parameter

  • nama

    string opsional

    Nama opsional untuk mengidentifikasi alarm ini. Default-nya adalah string kosong.

  • alarmInfo

    AlarmCreateInfo

    Menjelaskan kapan alarm harus berbunyi. Waktu awal harus ditentukan oleh when atau delayInMinutes (tetapi bukan 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.

  • callback

    fungsi opsional

    Chrome 111 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 111 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

get()

Janji 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

Mengambil detail tentang alarm yang ditentukan.

Parameter

  • nama

    string opsional

    Nama alarm yang akan didapatkan. Default-nya adalah string kosong.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (alarm?: Alarm) => void

Hasil

  • Promise&lt;Alarm | tidak terdefinisi>

    Chrome 91 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getAll()

Janji 
chrome.alarms.getAll(
  callback?: function,
)

Mendapatkan array dari semua alarm.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (alarms: Alarm[]) => void

Hasil

  • Janjikan<Alarm[]>

    Chrome 91 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

Acara

onAlarm

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

Diaktifkan saat alarm telah berlalu. Berguna untuk halaman acara.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (alarm: Alarm) => void