chrome.alarms

Açıklama

Kodu düzenli olarak veya gelecekte 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 dosyasında "alarms" iznini beyan edin:

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

Kavramlar ve kullanım

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

Cihaz uyku modu

Alarmlar, cihaz uykudayken çalışmaya devam eder. Ancak alarmlar cihazı uyandırmaz. Cihaz uyandırıldığında kaçırılan alarmlar tetiklenir. Tekrarlanan alarmlar en fazla bir kez tetiklenir ve ardından cihazın uyandığı andan itibaren belirtilen süre kullanılarak yeniden planlanır. Alarmın ilk kez çalışacak şekilde ayarlanmasından bu yana geçen süre dikkate alınmaz.

Kalıcı

Alarmlar genellikle uzantı güncellenene kadar devam eder. Ancak bu durum garanti edilmez ve tarayıcı yeniden başlatıldığında alarmlar temizlenmeyebilir. Bu nedenle, alarm oluşturulduğunda depolama alanında bir değer ayarlayabilir ve ardından servis çalışanınızın her başlatıldığında bu değerin mevcut olduğundan emin olabilirsiniz. Ö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, alarmların nasıl kullanılacağı ve alarmlara 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ı yüklendiğinde hizmet çalışanında 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 simgesi çaldığı alarmın adına göre 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 tekrarlanan bir alarmdır ve periodInMinutes dakika sonra tekrar tetiklenir.

  • scheduledTime

    sayı

    Bu alarmın, başlangıç tarihinden itibaren milisaniye cinsinden tetiklanacağı zaman (ör. Date.now() + n). Performans nedeniyle alarm, bu tarihten sonra rastgele bir miktarda geciktirilmiş 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 tarafından belirtilen ilk etkinlikten sonraki her periodInMinutes dakikada tetiklenir. Ayarlanmazsa alarm yalnızca bir kez etkinleşir.

  • ne zaman

    number isteğe bağlı

    Alarmın çalacağı zaman (milisaniye cinsinden, başlangıç zamanından itibaren) (ör. Date.now() + n).

Yöntemler

clear()

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

Belirtilen ada sahip alarmı temizler.

Parametreler

  • ad

    dize isteğe bağlı

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

  • geri çağırma

    işlev isteğe bağlı

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

    (wasCleared: boolean) => void

    • wasCleared

      boolean

İadeler

  • Promise<boolean>

    Chrome 91 ve sonraki sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

clearAll()

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

Tüm alarmları temizler.

Parametreler

  • geri çağırma

    işlev isteğe bağlı

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

    (wasCleared: boolean) => void

    • wasCleared

      boolean

İadeler

  • Promise<boolean>

    Chrome 91 ve sonraki sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

create()

Promise 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Alarm oluşturur. alarmInfo tarafından belirtilen zamanlarda 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 yeni 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 bunları istediğiniz kadar daha geciktirebilir. Yani delayInMinutes veya periodInMinutes'nin 0.5'den düşük bir değere ayarlanması dikkate alınmaz ve uyarı gösterilir. when, uyarı verilmeden "şimdi"den 30 saniye sonra olacak şekilde ayarlanabilir ancak alarmın en az 30 saniye boyunca tetiklenmesine neden olmaz.

Uygulamanızı veya uzantınızı unpacked olarak yüklediğinizde, uygulamanızda veya uzantınızda hata ayıklamanıza yardımcı olmak için alarmın ne sıklıkta tetiklenebileceği konusunda bir sınırlama 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 tetiklenmesi gerektiğini açıklar. İlk zaman, when veya delayInMinutes ile belirtilmelidir (ancak ikisi birden değil). periodInMinutes ayarlanırsa alarm, ilk etkinlikten sonraki her periodInMinutes dakikada bir tekrarlanır. Tekrarlanan alarm için when veya delayInMinutes ayarlanmazsa delayInMinutes için varsayılan olarak periodInMinutes kullanılır.

  • geri çağırma

    işlev isteğe bağlı

    Chrome 111 ve sonraki sürümler

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

    () => void

İadeler

  • Promise<void>

    Chrome 111 ve sonraki sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

get()

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

Belirtilen alarmla ilgili 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.

  • geri çağırma

    işlev isteğe bağlı

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

    (alarm?: Alarm) => void

    • alarm

      Alarm isteğe bağlı

İadeler

  • Promise<Alarm | undefined>

    Chrome 91 ve sonraki sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

getAll()

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

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

Parametreler

  • geri çağırma

    işlev isteğe bağlı

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

    (alarms: Alarm[]) => void

İadeler

  • Promise<Alarm[]>

    Chrome 91 ve sonraki sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

Etkinlikler

onAlarm

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

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

Parametreler

  • geri çağırma

    işlev

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

    (alarm: Alarm) => void