browser.alarms

Açıklama

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

İzinler

alarms

browser.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 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. Tekrarlanan alarmlar en fazla bir kez çalar ve ardından cihazın uyandığı andan itibaren belirtilen süre kullanılarak yeniden planlanır. Alarmın ilk ayarlandığı andan itibaren geçen süre dikkate alınmaz.

Kalıcılık

persistAcrossSessions işaretini kullanarak alarmın oluşturma zamanındaki kalıcılığını kontrol edebilirsiniz. Bu değer true (uzantı güncellenene kadar devam eder) veya false (uzantı yeniden yüklenirse ya da tarayıcı yeniden başlatılırsa 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ış öngörülemez olabilir. Bu nedenle, hizmet çalışanınız her başlatıldığında önemli alarmların mevcut olduğundan emin olmak 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 alarmın başka bir yerde oluşturulduğunu depolayabilirsiniz. Böylece, gerektiğinde alarmı yeniden oluşturabilirsiniz.

Örnekler

Aşağıdaki örneklerde, alarmın nasıl kullanılacağı ve alarma 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 bir alarm ayarlanmaktadı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
  });
});

Alarmı yanıtlama

Aşağıdaki örnekte, işlem araç çubuğu simgesi, çalan alarmın adına göre ayarlanmaktadı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 çalar.

  • persistAcrossSessions

    boole

    Chrome 150+

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

  • scheduledTime

    sayı

    Bu alarmın çalması için planlanan zaman, milisaniye cinsinden (ör. Date.now() + n). Performans nedeniyle alarm, bu sürenin ötesinde rastgele bir süre geciktirilmiş olabilir.

AlarmCreateInfo

Özellikler

  • delayInMinutes

    number isteğe bağlı

    onAlarm etkinliğinin tetiklenmesi için geçmesi gereken süre (dakika cinsinden).

  • ad

    string isteğe bağlı

    Chrome 152+

    Bu alarmın adı.

  • periodInMinutes

    number isteğe bağlı

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

  • persistAcrossSessions

    boole isteğe bağlı

    Chrome 150+

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

  • ne zaman

    number isteğe bağlı

    Alarmın çalması gereken zaman, milisaniye cinsinden (ör. Date.now() + n).

Yöntemler

clear()

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

Belirtilen ada sahip alarmı siler.

Parametreler

  • ad

    string isteğe bağlı

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

İadeler

  • Promise<boolean>

    Chrome 91 ve sonraki sürümler Chrome 148'den itibaren browser.*

clearAll()

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

Tüm alarmları temizler.

İadeler

  • Promise<boolean | undefined>

    Chrome 91 ve sonraki sürümler Chrome 148'den itibaren browser.*

create()

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

Alarm oluşturur. alarmInfo tarafından belirtilen zamanlara yakın bir zamanda onAlarm etkinliği tetiklenir. Aynı ada sahip başka bir alarm varsa (veya ad belirtilmemişse) iptal edilir ve yerine bu alarm kullanılır.

Chrome, kullanıcının makinesindeki yükü azaltmak için alarmları saniyede en fazla bir kez olacak şekilde sınırlandırır ancak rastgele bir süre daha geciktirebilir. Yani delayInMinutes veya periodInMinutes değerinin 1 saniyeden daha kısa bir süreye ayarlanması dikkate alınmaz ve uyarıya neden olur. when, uyarı olmadan "şimdi"den sonraki 1 saniyeden daha kısa bir süreye ayarlanabilir ancak alarmın en az 1 saniye boyunca çalmasına neden olmaz.

Parametreler

  • ad

    string 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 çalacağını 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. Tekrarlanan bir alarm için when veya delayInMinutes ayarlanmazsa delayInMinutes için varsayılan olarak periodInMinutes kullanılır.

İadeler

  • Promise<void>

    Chrome 111 ve sonraki sürümler Chrome 148'den itibaren browser.*

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

get()

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

Belirtilen alarm hakkındaki 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.

İadeler

  • Promise<Alarm | undefined>

    Chrome 91 ve sonraki sürümler Chrome 148'den itibaren browser.*

getAll()

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

Tüm alarmların dizisini alır.

İadeler

  • Promise<Alarm[]>

    Chrome 91 ve sonraki sürümler Chrome 148'den itibaren browser.*

Etkinlikler

onAlarm

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

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

Parametreler

  • callback

    işlev

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

    (alarm: Alarm) => void