browser.alarms

Açıklama

Kodun periyodik olarak veya gelecekte belirli bir zamanda çalıştırılmasını planlamak için chrome.alarms API'sini kullanın.

İzinler

alarms

browser.alarms API'sini kullanmak için "alarms" iznini manifest dosyasında bildirin:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

Kavramlar ve kullanım

Güvenilir davranış sağlamak için API'nin nasıl davrandığını anlamak faydalıdır.

Cihaz uyku modu

Cihaz uyku modundayken alarmlar çalışmaya devam eder. Ancak alarm, cihazı uyandırmaz. Cihaz uyandığında kaçırılan alarmlar tetiklenir. Tekrarlayan alarmlar en fazla bir kez tetiklenir ve ardından cihaz uyandıktan sonra belirtilen süre kullanılarak yeniden planlanır. Alarmın ilk olarak çalıştırılmak üzere ayarlanmasından bu yana geçen süre dikkate alınmaz.

Kalıcılık

persistAcrossSessions işaretini kullanarak oluşturma sırasında bir alarmın kalıcılığını kontrol edebilirsiniz. Bu, true (uzantı güncellenene kadar devam eder) veya false (uzantı yeniden yüklendiğinde ya da tarayıcı yeniden başlatıldığında ve uzantı her güncellendiğinde temizlenir) olarak ayarlanabilir.

Diğer tarayıcılar ve Chrome'un eski sürümleri

Bu özellik diğer tarayıcılarda (sorun) veya Chrome 150'den önceki Chrome sürümlerinde desteklenmez. Bu sürümlerde davranış tahmin edilemez olabilir. Bu nedenle, hizmet çalışanınız her başlatıldığında önemli alarmların olduğundan emin olmanız en iyisidir. Örneğin:

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

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

checkAlarmState();

Alarmınız kullanıcı işlemine göre dinamik olarak oluşturuluyorsa gerektiğinde yeniden oluşturabilmek için alarmın başka bir yerde oluşturulduğunu saklamak isteyebilirsiniz.

Örnekler

Aşağıdaki örneklerde, alarmların nasıl kullanılacağı ve bunlara nasıl yanıt verileceği gösterilmektedir. Bu API'yi denemek için chrome-extension-samples deposundan Alarm API örneğini yükleyin.

Alarm kur

Aşağıdaki örnekte, uzantının yeni bir sürümü yüklendiğinde hizmet çalışanında alarm ayarlanır:

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

Alarma yanıt verme

Aşağıdaki örnekte, işlem araç çubuğu simgesi, çalan alarm nesnesi adına göre ayarlanır.

service-worker.js:

browser.alarms.onAlarm.addListener((alarm) => {
  browser.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

Türler

Alarm

Özellikler

  • ad

    dize

    Bu alarmın adı.

  • periodInMinutes

    number isteğe bağlı

    Boş değilse alarm yinelenen bir alarmdır ve periodInMinutes dakika sonra tekrar tetiklenir.

  • persistAcrossSessions

    boole

    Chrome 150 veya daha yeni sürümler

    Alarmın oturumlar (tarayıcı yeniden başlatmaları) arasında kalıcı olup olmayacağı.

  • scheduledTime

    sayı

    Bu alarmın tetiklenmesi planlanan zaman, dönemden sonraki milisaniye cinsinden (ör. Date.now() + n). Performans nedenleriyle alarm, bu sürenin ötesinde rastgele bir süre gecikmiş olabilir.

AlarmCreateInfo

Özellikler

  • delayInMinutes

    number isteğe bağlı

    onAlarm etkinliğinin tetiklenmesi gereken süre (dakika cinsinden).

  • ad

    dize isteğe bağlı

    Chrome 152 ve sonraki sürümler

    Bu alarmın adı.

  • periodInMinutes

    number isteğe bağlı

    Ayarlanırsa onAlarm etkinliği, when veya delayInMinutes ile belirtilen ilk etkinlikten sonra her periodInMinutes dakikada bir tetiklenmelidir. Ayarlanmazsa alarm yalnızca bir kez çalar.

  • persistAcrossSessions

    boolean isteğe bağlı

    Chrome 150 veya daha yeni sürümler

    Alarmın oturumlar (tarayıcı yeniden başlatmaları) arasında kalıcı olup olmayacağı. Chrome'da bu ayar, geçmişteki davranışla eşleşmesi için varsayılan olarak doğru değerine ayarlanır ancak tarayıcılar arası uyumluluğu en üst düzeye çıkarmak için bunu açıkça ayarlamanız gerekir.

  • ne zaman

    number isteğe bağlı

    Alarmın tetiklenmesi gereken zaman (sıfır zamanından sonraki milisaniye cinsinden) (ör. Date.now() + n).

Yöntemler

clear()

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

Belirtilen ada sahip alarmı temizler.

Parametreler

  • ad

    dize isteğe bağlı

    Temizlenecek alarmın adı. Varsayılan olarak boş dize kullanılır.

İadeler

  • Promise<boolean>

    Chrome 91 veya daha yeni bir sürüm

clearAll()

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

Tüm alarmları temizler.

İadeler

  • Promise<boolean | undefined>

    Chrome 91 veya daha yeni bir sürüm

create()

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

Alarm oluşturur. alarmInfo tarafından belirtilen saatlerde onAlarm etkinliği tetiklenir. Aynı ada sahip (veya ad belirtilmemişse adsız) başka bir alarm varsa bu alarm iptal edilir ve yerine bu alarm ayarlanır.

Chrome, kullanıcının makinesindeki yükü azaltmak için alarmları en fazla 30 saniyede bir kez olacak şekilde sınırlar ancak alarmları rastgele bir süre daha geciktirebilir. Yani delayInMinutes veya periodInMinutes değerinin 0.5 değerinden daha düşük olması durumunda bu değerler dikkate alınmaz ve uyarı gösterilir. when, uyarı verilmeden "şimdi"den 30 saniye sonrasına ayarlanabilir ancak alarmın tetiklenmesi için en az 30 saniye geçmesi gerekir.

Uygulamanızda veya uzantınızda hata ayıklamanıza yardımcı olmak için, paketi açılmamış olarak yüklediğinizde alarmın ne sıklıkta tetiklenebileceğine dair bir sınır yoktur.

Parametreler

  • ad

    dize isteğe bağlı

    Bu alarmı tanımlamak için isteğe bağlı ad. Varsayılan olarak boş dize kullanılır.

  • alarmInfo

    AlarmCreateInfo

    Alarmın ne zaman çalması gerektiğini açıklar. Başlangıç zamanı when veya delayInMinutes ile belirtilmelidir (ancak ikisi birden belirtilmemelidir). periodInMinutes ayarlanırsa alarm, ilk etkinlikten sonra her periodInMinutes dakikada bir tekrarlanır. Tekrarlayan bir alarm için when veya delayInMinutes ayarlanmamışsa delayInMinutes için varsayılan olarak periodInMinutes kullanılır.

İadeler

  • Promise<void>

    Chrome 111 veya daha yeni bir sürüm

    Alarm oluşturulduğunda çözümlenen söz.

get()

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

Belirtilen alarm hakkında ayrıntıları alır.

Parametreler

  • ad

    dize isteğe bağlı

    Alınacak alarmın adı. Varsayılan olarak boş dize kullanılır.

İadeler

  • Promise<Alarm | undefined>

    Chrome 91 veya daha yeni bir sürüm

getAll()

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

Tüm alarmların dizisini alır.

İadeler

  • Promise<Alarm[]>

    Chrome 91 veya daha yeni bir sürüm

Etkinlikler

onAlarm

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

Alarm süresi dolduğunda tetiklenir. Etkinlik sayfaları için yararlıdır.

Parametreler

  • callback

    işlev

    callback parametresi şu şekilde görünür: 

    (alarm: Alarm) => void