chrome.alarms

Açıklama

Kodu periyodik olarak veya gelecekte belirli bir zamanda çalışacak şekilde planlamak için chrome.alarms API'sini kullanın.

İzinler

alarms

chrome.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 çalmaya 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 bir alarmın kalıcılığını oluşturma sırasında kontrol edebilirsiniz. Bu işaret true (uzantı güncellenene kadar kalıcı olur) 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 önceki 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 bulunduğundan emin olmanız en iyisidir. Örneğin:

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

  if (!alarm) {
    await chrome.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, alarmın nasıl kullanılacağı ve yanıtlama işleminin nasıl yapılacağı 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:

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

Alarma yanıt verme

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

service-worker.js:

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

Türler

Alarm

Özellikler

  • ad

    dize

    Bu alarmın adı.

  • periodInMinutes

    number isteğe bağlı

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

  • persistAcrossSessions

    boole

    Beklemede

    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).

  • 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ı

    Beklemede

    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ında 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>

Tüm alarmları temizler.

İadeler

  • Promise<boolean>

    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 başka bir alarm varsa (veya ad belirtilmemişse adsız 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 olacak şekilde sınırlar ancak bunları rastgele bir süre daha geciktirebilir. Yani delayInMinutes veya periodInMinutes değerini 0.5 değerinden daha küçük bir değere ayarlamak kabul edilmez ve uyarıya neden olur. when değeri, uyarı verilmeden "şimdi"den 30 saniye sonrasına ayarlanabilir ancak alarmın en az 30 saniye boyunca tetiklenmesine neden olmaz.

Uygulamanızda veya uzantınızda hata ayıklamanıza yardımcı olmak için, paketi açılmamış olarak yüklediğinizde alarmın tetiklenme sıklığı sınırlanmaz.

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 (ikisi birden değil). periodInMinutes ayarlanmışsa 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 Promise.

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