Açıklama
chrome.events
ad alanı, ilginç bir şey olduğunda sizi bilgilendirmek için etkinlik gönderen API'lerin kullandığı yaygın türleri içerir.
Kavramlar ve kullanım
Event
, ilginç bir şey olduğunda bildirim almanızı sağlayan bir nesnedir. Aşağıda, bir alarm sona erdiğinde bildirim almak için chrome.alarms.onAlarm
etkinliğinin kullanılmasına ilişkin bir örnek verilmiştir:
chrome.alarms.onAlarm.addListener((alarm) => {
appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});
Örnekte de gösterildiği gibi, bildirim için addListener()
kullanarak kaydolursunuz. addListener()
bağımsız değişkeni her zaman etkinliği işlemek için tanımladığınız bir işlevdir ancak işlevin parametreleri, yönetmekte olduğunuz etkinliğe bağlıdır. alarms.onAlarm
belgelerini kontrol ettiğinizde işlevin tek bir parametreye sahip olduğunu görebilirsiniz: Geçen alarmla ilgili ayrıntıları içeren bir alarms.Alarm
nesnesi.
Etkinlikleri kullanan örnek API'ler: alarms, i18n, identity, runtime. Çoğu Chrome API'si bunu yapar.
Bildirim Temelli Etkinlik İşleyiciler
Bildirim temelli etkinlik işleyiciler, bildirim temelli koşullar ve işlemlerden oluşan kuralları tanımlamak için bir araç sağlar. Koşullar, JavaScript motoru yerine tarayıcıda değerlendirilir. Bu, gidiş dönüş gecikmelerini azaltır ve çok yüksek verimlilik sağlar.
Bildirim temelli etkinlik işleyiciler, örneğin Declarative Content API'de kullanılır. Bu sayfada, tüm bildirim temelli etkinlik işleyicilerin temel kavramları açıklanmaktadır.
Kurallar
Olası en basit kural, bir veya daha fazla koşul ile bir veya daha fazla işlemden oluşur:
const rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
Koşullardan herhangi biri yerine getirilirse tüm işlemler gerçekleştirilir.
Koşullara ve işlemlere ek olarak her kurala bir tanımlayıcı verebilirsiniz. Bu, önceden kaydedilmiş kuralların kaydını iptal etmeyi kolaylaştırır ve kurallar arasındaki öncelikleri tanımlamak için bir öncelik sağlar. Öncelikler, yalnızca kuralların birbiriyle çelişmesi veya belirli bir sırayla yürütülmesi gerekiyorsa dikkate alınır. İşlemler, kendi kurallarının önceliklerine göre azalan sırada yürütülür.
const rule = {
id: "my rule", // optional, will be generated if not set.
priority: 100, // optional, defaults to 100.
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
Etkinlik nesneleri
Etkinlik nesneleri kuralları destekleyebilir. Etkinlikler gerçekleştiğinde bu etkinlik nesneleri, bir geri çağırma işlevi çağırmaz. Ancak kayıtlı herhangi bir kuralın en az bir yerine getirilmiş koşulu olup olmadığını test eder ve bu kuralla ilişkili işlemleri yürütür. Bildirim temelli API'yi destekleyen etkinlik nesnelerinin üç ilgili yöntemi vardır: events.Event.addRules()
, events.Event.removeRules()
ve events.Event.getRules()
.
Kural ekle
Kural eklemek için etkinlik nesnesinin addRules()
işlevini çağırın. İlk parametresi olarak bir dizi kural örneği alır ve tamamlandığında çağrılan bir geri çağırma işlevi kullanılır.
const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});
Kurallar başarıyla eklendiyse details
parametresi, iletilen rule_list
parametresiyle aynı sırada görünen ve isteğe bağlı id
ve priority
parametrelerinin oluşturulan değerlerle doldurulduğu bir eklenen kurallar dizisi içerir. Örneğin, herhangi bir kural geçersizse (örneğin, geçersiz bir koşul veya işlem içerdiği için) geri çağırma işlevi çağrıldığında kuralların hiçbiri eklenmez ve runtime.lastError değişkeni ayarlanır. rule_list
içindeki her kural, başka bir kural tarafından kullanılmayan benzersiz bir tanımlayıcı veya boş bir tanımlayıcı içermelidir.
Kuralları kaldırma
Kuralları kaldırmak için removeRules()
işlevini çağırın. İlk parametresi olarak kural tanımlayıcılarından oluşan isteğe bağlı diziyi ve ikinci parametresi olarak da geri çağırma işlevini kabul eder.
const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});
rule_ids
bir tanımlayıcılar dizisiyse dizide listelenen tanımlayıcılara sahip tüm kurallar kaldırılır. rule_ids
, bilinmeyen bir tanımlayıcı listelerse bu tanımlayıcı sessizce yoksayılır. rule_ids
değeri undefined
ise bu uzantının tüm kayıtlı kuralları kaldırılır. Kurallar kaldırıldığında callback()
işlevi çağrılır.
Kuralları alma
Kayıtlı kuralların listesini almak için getRules()
işlevini çağırın. removeRules()
ile aynı anlama sahip isteğe bağlı kural tanımlayıcıları dizisini ve bir geri çağırma işlevini kabul eder.
const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});
callback()
işlevine iletilen details
parametresi, doldurulmuş isteğe bağlı parametreleri de içeren bir kural dizisine başvuruda bulunur.
Performans
Maksimum performans elde etmek için aşağıdaki yönergeleri göz önünde bulundurmalısınız.
Kuralları toplu olarak kaydetme ve kaydını iptal etme. Her kayıt veya kayıt iptalinden sonra, Chrome'un dahili veri yapılarını güncellemesi gerekir. Bu güncelleme pahalı bir işlemdir.
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1]); chrome.declarativeWebRequest.onRequest.addRules([rule2]);
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
events.UrlFilter içindeki normal ifadeler yerine alt dize eşleşmesini tercih edin. Alt dizeye dayalı eşleştirme son derece hızlıdır.
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {urlMatches: "example.com/[^?]*foo" } });
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {hostSuffix: "example.com", pathContains: "foo"} });
Aynı işlemleri paylaşan birden fazla kural varsa bu kuralları tek bir kuralda birleştirin. Kurallar, tek bir koşul yerine getirildiğinde eylemlerini tetikler. Bu, eşleştirmeyi hızlandırır ve kopya işlem kümeleri için bellek tüketimini azaltır.
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }); const condition2 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'foobar.com' } }); const rule1 = { conditions: [condition1], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; const rule2 = { conditions: [condition2], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }); const condition2 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'foobar.com' } }); const rule = { conditions: [condition1, condition2], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; chrome.declarativeWebRequest.onRequest.addRules([rule]);
Filtrelenen etkinlikler
Filtrelenen etkinlikler, işleyicilerin ilgilendikleri etkinliklerin bir alt kümesini belirtmesine olanak tanıyan bir mekanizmadır. Filtre kullanan bir dinleyici, filtreyi geçemeyen etkinlikler için çağrılmaz. Bu da dinleme kodunu daha bildirim temelli ve verimli hale getirir. Service Worker'ın önem vermediği etkinlikleri işlemek için uyandırılması gerekmez.
Filtrelenen etkinliklerin manuel filtreleme kodundan geçişe izin vermesi amaçlanmıştır.
chrome.webNavigation.onCommitted.addListener((event) => { if (hasHostSuffix(event.url, 'google.com') || hasHostSuffix(event.url, 'google.com.au')) { // ... } });
chrome.webNavigation.onCommitted.addListener((event) => { // ... }, {url: [{hostSuffix: 'google.com'}, {hostSuffix: 'google.com.au'}]});
Etkinlikler, söz konusu etkinlik için anlamlı olan belirli filtreleri destekler. Bir etkinliğin desteklediği filtrelerin listesi, "filtreler" bölümündeki o etkinlikle ilgili belgelerde listelenir.
URL'leri eşleştirirken (yukarıdaki örnekte olduğu gibi) etkinlik filtreleri, şema ve bağlantı noktası eşleştirme hariç olmak üzere, events.UrlFilter
ile ifade edilebilen aynı URL eşleştirme özelliklerini destekler.
Türler
Event
Bir Chrome etkinliği için işleyicilerin eklenmesine ve kaldırılmasına olanak tanıyan bir nesne.
Özellikler
-
addListener
void
Bir etkinliğe etkinlik işleyici geri çağırma kaydeder.
addListener
işlevi şu şekilde görünür:(callback: H) => {...}
-
geri çağırma
VR
Bir etkinlik gerçekleştiğinde çağrılır. Bu işlevin parametreleri etkinliğin türüne bağlıdır.
-
-
addRules
void
Etkinlikleri işlemek için kuralları kaydeder.
addRules
işlevi şu şekilde görünür:(rules: Rule<anyany>[], callback?: function) => {...}
-
kurallar
Kural<herhangi bir>[]
Kaydedilecek kurallar. Bu kurallar, önceden kaydedilmiş kuralların yerine geçmez.
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:(rules: Rule<anyany>[]) => void
-
kurallar
Kural<herhangi bir>[]
Kaydedilen kurallar, isteğe bağlı parametreler değerlerle doldurulur.
-
-
-
getRules
void
Kayıtlı kuralları döndürür.
getRules
işlevi şu şekilde görünür:(ruleIdentifiers?: string[], callback: function) => {...}
-
ruleIdentifiers
string[] isteğe bağlı
Bir dizi aktarılırsa yalnızca bu dizide yer alan tanımlayıcılara sahip kurallar döndürülür.
-
geri çağırma
işlev
callback
parametresi şu şekilde görünür:(rules: Rule<anyany>[]) => void
-
kurallar
Kural<herhangi bir>[]
Kaydedilen kurallar, isteğe bağlı parametreler değerlerle doldurulur.
-
-
-
hasListener
void
hasListener
işlevi şu şekilde görünür:(callback: H) => {...}
-
geri çağırma
VR
Kayıt durumu test edilecek dinleyici.
-
returns
boolean
callback etkinliğe kayıtlıysa doğru değerini alır.
-
-
hasListeners
void
hasListeners
işlevi şu şekilde görünür:() => {...}
-
returns
boolean
Etkinliğe kayıtlı etkinlik işleyiciler varsa doğru değerini alır.
-
-
removeListener
void
Bir etkinlik işleyicinin geri çağırma kaydını bir etkinlikten siler.
removeListener
işlevi şu şekilde görünür:(callback: H) => {...}
-
geri çağırma
VR
Kaydı iptal edilecek dinleyici.
-
-
removeRules
void
Şu anda kayıtlı olan kuralların kaydını siler.
removeRules
işlevi şu şekilde görünür:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] isteğe bağlı
Bir dizi aktarılırsa yalnızca bu dizide yer alan tanımlayıcılara sahip kuralların kaydı silinir.
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:() => void
-
Rule
Etkinliklerin işlenmesine yönelik bildirim temelli bir kuralın açıklaması.
Özellikler
-
işlemler
herhangi biri[]
Koşullardan biri yerine getirildiğinde tetiklenen işlemlerin listesi.
-
conditions
herhangi biri[]
İşlemleri tetikleyebilecek koşulların listesi.
-
id
string isteğe bağlı
Bu kurala referans verilmesini sağlayan isteğe bağlı tanımlayıcı.
-
önceliği
numara isteğe bağlı
Bu kuralın isteğe bağlı önceliği. Varsayılan olarak 100 değerine ayarlanır.
-
etiketler
string[] isteğe bağlı
Etiketler, kurallara ek açıklama eklemek ve kural grupları üzerinde işlemler gerçekleştirmek için kullanılabilir.
UrlFilter
Çeşitli ölçütler için URL'leri filtreler. Etkinlik filtreleme bölümünü inceleyin. Tüm ölçütler büyük/küçük harfe duyarlıdır.
Özellikler
-
cidrBlocks
string[] isteğe bağlı
Chrome 123 ve sonraki sürümlerURL'nin ana makine kısmı bir IP adresiyse ve dizide belirtilen CIDR bloklarından herhangi birinde yer alıyorsa eşleşme sağlar.
-
hostContains
string isteğe bağlı
URL'nin ana makine adı belirtilen bir dize içeriyorsa eşleşir. Bir ana makine adı bileşeninin "foo" önekine sahip olup olmadığını test etmek için hostContains: ".foo" ön ekini kullanın. Ana makine adının başına örtülü bir nokta eklendiği için, "www.foobar.com" ve "foo.com" ile eşleşir. Benzer şekilde, hostContains, bileşen sonekiyle ("foo.") ve bileşenlerle ('.foo.') tam olarak eşleştirmek için kullanılabilir. Ana makine adının sonuna örtülü bir nokta eklenmediğinden, son bileşenler için son ek ve tam eşlemenin HostSuffix kullanılarak ayrı ayrı yapılması gerekir.
-
hostEquals
string isteğe bağlı
URL'nin ana makine adı belirtilen bir dizeye eşitse eşleşir.
-
hostPrefix
string isteğe bağlı
URL'nin ana makine adı belirtilen bir dizeyle başlıyorsa eşleşir.
-
hostSuffix
string isteğe bağlı
URL'nin ana makine adı belirtilen bir dizeyle bitiyorsa eşleşir.
-
originAndPathMatches
string isteğe bağlı
Sorgu segmenti ve parça tanımlayıcısı olmayan URL, belirtilen normal ifadeyle eşleşirse eşleşir. Bağlantı noktası numaraları, varsayılan bağlantı noktası numarasıyla eşleşiyorsa URL'den çıkarılır. Normal ifadeler RE2 söz dizimini kullanır.
-
pathContains
string isteğe bağlı
URL'nin yol segmenti, belirtilen bir dize içeriyorsa eşleşir.
-
pathEquals
string isteğe bağlı
URL'nin yol segmenti, belirtilen bir dizeye eşitse eşleşir.
-
pathPrefix
string isteğe bağlı
URL'nin yol segmenti belirtilen bir dizeyle başlıyorsa eşleşir.
-
pathSuffix
string isteğe bağlı
URL'nin yol segmenti, belirtilen bir dizeyle bitiyorsa eşleşir.
-
ports
(sayı | sayı[])[] isteğe bağlı
URL'nin bağlantı noktası, belirtilen bağlantı noktası listelerinden herhangi birinde bulunuyorsa eşleşir. Örneğin
[80, 443, [1000, 1200]]
; 80, 443 numaralı bağlantı noktasında ve 1000-1200 aralığındaki tüm isteklerle eşleşir. -
queryContains
string isteğe bağlı
URL'nin sorgu segmenti belirtilen bir dize içeriyorsa eşleşir.
-
queryEquals
string isteğe bağlı
URL'nin sorgu segmenti belirtilen bir dizeye eşitse eşleşir.
-
queryPrefix
string isteğe bağlı
URL'nin sorgu segmenti belirtilen bir dizeyle başlıyorsa eşleşir.
-
querySuffix
string isteğe bağlı
URL'nin sorgu segmenti belirtilen bir dizeyle bitiyorsa eşleşir.
-
schemes
string[] isteğe bağlı
URL'nin şeması, dizide belirtilen şemalardan herhangi birine eşitse eşleşir.
-
urlContains
string isteğe bağlı
URL (parça tanımlayıcısı olmadan) belirtilen bir dize içeriyorsa eşleşir. Bağlantı noktası numaraları, varsayılan bağlantı noktası numarasıyla eşleşiyorsa URL'den çıkarılır.
-
urlEquals
string isteğe bağlı
URL (parça tanımlayıcısı olmadan) belirtilen bir dizeye eşitse eşleşir. Bağlantı noktası numaraları, varsayılan bağlantı noktası numarasıyla eşleşiyorsa URL'den çıkarılır.
-
urlMatches
string isteğe bağlı
URL (parça tanımlayıcısı olmadan) belirtilen normal ifadeyle eşleşirse eşleşir. Bağlantı noktası numaraları, varsayılan bağlantı noktası numarasıyla eşleşiyorsa URL'den çıkarılır. Normal ifadeler RE2 söz dizimini kullanır.
-
urlPrefix
string isteğe bağlı
URL (parça tanımlayıcısı olmadan) belirtilen bir dizeyle başlıyorsa eşleşir. Bağlantı noktası numaraları, varsayılan bağlantı noktası numarasıyla eşleşiyorsa URL'den çıkarılır.
-
urlSuffix
string isteğe bağlı
URL (parça tanımlayıcısı olmadan) belirtilen bir dizeyle bitiyorsa eşleşir. Bağlantı noktası numaraları, varsayılan bağlantı noktası numarasıyla eşleşiyorsa URL'den çıkarılır.