chrome.alarms

Açıklama

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

İzinler

alarms

chrome.alarms API'yi kullanmak için manifest bölümünde "alarms" iznini beyan edin:

{
  "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

Bir cihaz uyku moduna geçtiğinde alarmlar çalışmaya devam eder. Ancak, alarm cihaz uyandırılmaz. Cihaz uyandığında, kaçırılan alarmlar devreye girer. Yinelenen alarmlar en fazla bir kez etkinleşir ve ardından cihazın uyanık olduğu andan itibaren, belirtilen süre boyunca tekrar planlanır. Alarmın ilk olarak çalışmaya başlamasından bu yana geçen süre dikkate alınmaz.

Kalıcı

Alarmlar genellikle bir uzantı güncellenene kadar devam eder. Ancak bu garanti edilmez ve tarayıcı yeniden başlatıldığında alarmlar silinebilir. Sonuç olarak, alarm oluşturulduğunda depolama alanında bir değer belirleyin ve Service Worker'ınız her başlatıldığında bu değerin mevcut olduğundan emin olun. Örneğin:

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

Örnekler

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

Alarm kur

Aşağıdaki örnekte, uzantı yüklendiğinde Service Worker'da bir alarm ayarlanır:

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

Alarma yanıt verme

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

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

    numara isteğe bağlı

    Boş değilse alarm tekrar eden bir alarmdır ve periodInMinutes dakika içinde tekrar etkinleşecektir.

  • scheduledTime

    sayı

    Dönemden sonra (ör. Date.now() + n) bu alarmın çalması için programlandığı zaman (milisaniye cinsinden). Performans nedenleriyle, alarm bundan daha uzun bir süre gecikmiş olabilir.

AlarmCreateInfo

Özellikler

  • delayInMinutes

    numara isteğe bağlı

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

  • periodInMinutes

    numara isteğe bağlı

    Ayarlanırsa onAlarm etkinliği, when veya delayInMinutes tarafından belirtilen ilk etkinlikten sonraki her periodInMinutes dakikada bir etkinleşmelidir. Ayarlanmazsa alarm yalnızca bir kez çalar.

  • şu olduğunda:

    numara isteğe bağlı

    Dönemden sonraki milisaniye cinsinden, alarmın etkinleşmesi gereken zaman (ör. Date.now() + n).

Yöntemler

clear()

Söz 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Verilen ada sahip alarmı temizler.

Parametreler

  • ad

    string isteğe bağlı

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

  • geri çağırma

    Functions (isteğe bağlı)

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

İlerlemeler

  • Promise<boolean>

    Chrome 91 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

clearAll()

Söz 
chrome.alarms.clearAll(
  callback?: function,
)

Tüm alarmları temizler.

Parametreler

  • geri çağırma

    Functions (isteğe bağlı)

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

İlerlemeler

  • Promise<boolean>

    Chrome 91 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

create()

Söz 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Alarm oluşturur. alarmInfo tarafından belirtilen zamanların yakınında onAlarm etkinliği tetiklenir. Aynı ada sahip (veya herhangi bir ad belirtilmezse) başka bir alarm varsa iptal edilir ve bu alarmla değiştirilir.

Chrome, kullanıcının makinesindeki yükü azaltmak için alarmları en fazla 30 saniyede bir olacak şekilde sınırlar, ancak bu alarmları rastgele bir miktarda geciktirebilir. Yani, delayInMinutes veya periodInMinutes politikasının 0.5 değerinden küçük bir değere ayarlanması kabul edilmez ve bir uyarıya neden olur. when, uyarı yapılmaksızın "şimdi" sonrasında 30 saniyeden daha kısa bir süreye ayarlanabilir, ancak gerçekte en az 30 saniye boyunca alarmın çalmasına neden olmaz.

Uygulama veya uzantınızı paketinden çıkardığınızda, hata ayıklamanıza yardımcı olmak için alarmın ne sıklıkta tetiklenebileceğiyle ilgili bir sınır yoktur.

Parametreler

  • ad

    string isteğe bağlı

    Bu alarmı tanımlamak için kullanılan 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 tarafından belirtilmelidir (ikisi birden değil). periodInMinutes ayarlanırsa alarm ilk etkinlikten sonra her periodInMinutes dakikada bir tekrarlanır. Tekrarlanan alarm için when veya delayInMinutes ayarlanmamışsa delayInMinutes için varsayılan olarak periodInMinutes kullanılır.

  • geri çağırma

    Functions (isteğe bağlı)

    Chrome 111 ve sonraki sürümler

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

    ()=>void

İlerlemeler

  • Promise<void>

    Chrome 111 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

get()

Söz 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

Belirtilen alarmla ilgili ayrıntıları alır.

Parametreler

  • ad

    string isteğe bağlı

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

  • geri çağırma

    Functions (isteğe bağlı)

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

    (alarm?: Alarm)=>void

    • alarm

      Alarm isteğe bağlı

İlerlemeler

  • Söz<Alarm|undefined>

    Chrome 91 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

getAll()

Söz 
chrome.alarms.getAll(
  callback?: function,
)

Tüm alarmların bir dizisini alır.

Parametreler

  • geri çağırma

    Functions (isteğe bağlı)

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

    (alarms: Alarm[])=>void

İlerlemeler

  • Söz<Alarm[]>

    Chrome 91 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

Etkinlikler

onAlarm

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

Alarm çaldığında tetiklenir. Etkinlik sayfaları için kullanışlıdır.

Parametreler

  • geri çağırma

    işlev

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

    (alarm: Alarm)=>void