chrome.alarms

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 oleh when atau delayInMinutes. 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()

Promise 
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 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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

clearAll()

Promise 
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 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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

create()

Promise 
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

    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.

  • callback

    fungsi opsional

    Chrome 111 dan yang lebih baru

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

get()

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

Mengambil detail tentang alarm yang ditentukan.

Parameter

  • name

    string opsional

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

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (alarm?: Alarm)=>void

Hasil

  • Promise<Alarm|undefined>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getAll()

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

Mendapatkan array semua alarm.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (alarms: Alarm[])=>void

Hasil

  • Promise<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. Promise di-resolve dengan jenis yang sama 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: 

    (alarm: Alarm)=>void