chrome.alarms

Deskripsi

Gunakan API chrome.alarms 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 cara kerja API.

Mode tidur perangkat

Alarm terus berbunyi saat perangkat dalam mode tidur. Namun, alarm tidak akan mengaktifkan perangkat. Saat perangkat aktif, semua alarm yang terlewat akan berbunyi. Alarm berulang akan berbunyi paling banyak satu kali, lalu dijadwalkan ulang menggunakan periode yang ditentukan, dimulai dari saat perangkat aktif, tanpa memperhitungkan waktu yang telah berlalu sejak alarm awalnya disetel untuk berbunyi.

Persistensi

Alarm umumnya tetap ada hingga ekstensi diperbarui. Namun, hal ini tidak dijamin, dan alarm dapat dihapus saat browser dimulai ulang. Oleh karena itu, pertimbangkan untuk menetapkan nilai dalam penyimpanan saat alarm dibuat, lalu pastikan nilai tersebut ada setiap kali pekerja layanan Anda 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 service worker 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

    nomor opsional

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

  • scheduledTime

    angka

    Waktu saat alarm ini dijadwalkan untuk diaktifkan, dalam milidetik setelah epoch (mis. Date.now() + n). Untuk alasan performa, alarm mungkin telah ditunda dalam jumlah yang tidak ditentukan di luar waktu ini.

AlarmCreateInfo

Properti

  • delayInMinutes

    nomor opsional

    Durasi waktu dalam menit setelah peristiwa onAlarm harus dipicu.

  • periodInMinutes

    nomor opsional

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

  • kapan

    nomor 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. Default-nya 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 diaktifkan. Jika ada alarm lain dengan nama yang sama (atau tanpa nama jika tidak ada yang ditentukan), alarm tersebut akan dibatalkan dan digantikan oleh alarm ini.

Untuk mengurangi beban pada mesin pengguna, Chrome membatasi alarm maksimal sekali setiap 30 detik, tetapi dapat menundanya dalam jumlah yang lebih besar. Artinya, menetapkan delayInMinutes atau periodInMinutes ke nilai yang lebih kecil dari 0.5 tidak akan dipatuhi dan akan menyebabkan peringatan. when dapat disetel ke kurang dari 30 detik setelah "sekarang" tanpa peringatan, tetapi sebenarnya tidak akan menyebabkan alarm berbunyi setidaknya selama 30 detik.

Untuk membantu Anda men-debug aplikasi atau ekstensi, saat Anda memuatnya tanpa di-unzip, tidak ada batasan seberapa sering alarm dapat diaktifkan.

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 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+

get()

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

Mengambil detail tentang alarm yang ditentukan.

Parameter

  • nama

    string opsional

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

Hasil

  • Promise<Alarm | undefined>

    Chrome 91+

getAll()

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

Mendapatkan array semua alarm.

Hasil

  • Promise<Alarm[]>

    Chrome 91+

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