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 manifest dosyasında "alarms" iznini 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 alarmlar 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ılması planlandığı zamandan bu yana geçen süre dikkate alınmaz.

Kalıcılık

Alarmlar genellikle uzantı güncellenene kadar devam eder. Ancak bu garanti edilmez ve tarayıcı yeniden başlatıldığında alarmlar temizlenebilir. Bu nedenle, bir alarm oluşturulduğunda depolama alanında bir değer ayarlamayı ve ardından hizmet çalışanınız her başlatıldığında bu değerin mevcut olmasını sağlamayı düşünün. Ö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 yanıtlanacağı 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 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, ç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.

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

  • ne zaman

    number isteğe bağlı

    Alarmın tetiklenmesi gereken zaman (sıfır zaman milisaniyesi 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 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 ayarlanması kabul edilmez ve uyarıya neden olur. 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ği konusunda 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 (ikisi birden değil). 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

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