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
veyadelayInMinutes
tarafından belirtilen ilk etkinlikten sonraki herperiodInMinutes
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()
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ümlerVaatler, 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()
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ümlerVaatler, 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()
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
Alarmın ne zaman çalması gerektiğini açıklar. Başlangıç zamanı
when
veyadelayInMinutes
tarafından belirtilmelidir (ikisi birden değil).periodInMinutes
ayarlanırsa alarm ilk etkinlikten sonra herperiodInMinutes
dakikada bir tekrarlanır. Tekrarlanan alarm içinwhen
veyadelayInMinutes
ayarlanmamışsadelayInMinutes
için varsayılan olarakperiodInMinutes
kullanılır. -
geri çağırma
Functions (isteğe bağlı)
Chrome 111 ve sonraki sürümlercallback
parametresi şu şekilde görünür:() => void
İlerlemeler
-
Promise<void>
Chrome 111 ve sonraki sürümlerVaatler, 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()
chrome.alarms.get(
name?: string,
callback?: function,
)
Belirtilen alarmla ilgili ayrıntıları alır.
Parametreler
İlerlemeler
-
Promise<Alarm | undefined>
Chrome 91 ve sonraki sürümlerVaatler, 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()
chrome.alarms.getAll(
callback?: function,
)
Tüm alarmların bir dizisini alır.
Parametreler
İlerlemeler
-
Söz<Alarm[]>
Chrome 91 ve sonraki sürümlerVaatler, 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.