browser.events

Açıklama

Kavramlar ve kullanım

Event, ilginç bir şey olduğunda bildirim almanızı sağlayan bir nesnedir. Bir alarmın süresi dolduğunda bildirim almak için browser.alarms.onAlarm etkinliğini kullanma örneği:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Örnekte gösterildiği gibi, addListener() kullanarak bildirimlere kaydolursunuz. addListener() işlevine iletilen bağımsız değişken her zaman etkinliği işlemek için tanımladığınız bir işlevdir ancak işlevin parametreleri, hangi etkinliği işlediğinize bağlıdır. alarms.onAlarm ile ilgili dokümanları incelediğinizde işlevin tek bir parametreye sahip olduğunu görürsünüz: alarms.Alarm nesnesi, geçen alarm hakkında ayrıntılar içerir.

Etkinlikleri kullanan örnek API'ler: alarms, i18n, identity, runtime. Çoğu chrome API'si bunu yapar.

Bildirime Dayalı Etkinlik İşleyiciler

Bildirimli etkinlik işleyicileri, bildirimli koşullar ve işlemlerden oluşan kuralları tanımlamak için bir yöntem sağlar. Koşullar, JavaScript motoru yerine tarayıcıda değerlendirilir. Bu sayede gidiş dönüş gecikmeleri azalır ve çok yüksek verimlilik sağlanır.

Bildirimli etkinlik işleyiciler, örneğin Declarative Content API kullanılır. Bu sayfada, tüm bildirim temelli etkinlik işleyicilerin temel kavramları açıklanmaktadır.

Kurallar

Mümkün olan en basit kural, bir veya daha fazla koşul ve bir veya daha fazla işlemden oluşur:

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Koşullardan herhangi biri karşılanırsa tüm işlemler yürütülür.

Koşullara ve işlemlere ek olarak, her kurala bir tanımlayıcı verebilirsiniz. Bu tanımlayıcı, daha önce kaydedilmiş kuralların kaydını silmeyi kolaylaştırır. Ayrıca, kurallar arasında öncelikleri tanımlamak için bir öncelik de verebilirsiniz. Öncelikler yalnızca kurallar birbiriyle çakışıyorsa veya belirli bir sırada yürütülmesi gerekiyorsa dikkate alınır. İşlemler, kurallarının önceliğine 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. Bu etkinlik nesneleri, etkinlikler gerçekleştiğinde geri çağırma işlevini çağırmaz ancak kayıtlı kurallardan herhangi birinin en az bir koşulunun karşılanıp karşılanmadığını test eder ve bu kurala ilişkin işlemleri yürütür. Bildirimli API'yi destekleyen etkinlik nesnelerinin üç alakalı 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 parametre olarak bir kural örnekleri dizisi, tamamlandığında çağrılan bir geri çağırma işlevi alır.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

Kurallar başarıyla eklenirse details parametresi, eklenen kuralların bir dizisini içerir. Bu kurallar, iletilen rule_list içindekiyle aynı sırada görünür. İsteğe bağlı id ve priority parametreleri, oluşturulan değerlerle doldurulur. Geçersiz bir koşul veya işlem içerdiği için geçersiz olan bir kural varsa kuralların hiçbiri eklenmez ve geri çağırma işlevi çağrıldığında 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 parametre olarak isteğe bağlı bir kural tanımlayıcı dizisi, ikinci parametre olarak da bir geri çağırma işlevi alır.

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

rule_ids bir tanımlayıcı dizisiyse dizide listelenen tanımlayıcılara sahip tüm kurallar kaldırılır. rule_ids bilinmeyen bir tanımlayıcı listeliyorsa bu tanımlayıcı sessizce yoksayılır. rule_ids undefined ise bu uzantının kayıtlı tüm 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ı anlambilime sahip isteğe bağlı bir kural tanımlayıcı dizisi ve geri arama işlevi kabul eder.

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

callback() işlevine iletilen details parametresi, doldurulmuş isteğe bağlı parametreler de dahil olmak üzere bir kural dizisini ifade eder.

Performans

Maksimum performans elde etmek için aşağıdaki yönergeleri göz önünde bulundurmanız gerekir.

Kuralları toplu olarak kaydetme ve kaydını silme Her kayıt veya kaydı silme işleminden sonra Chrome'un dahili veri yapılarını güncellemesi gerekir. Bu güncelleme maliyetli bir işlemdir.

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

events.UrlFilter içinde 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 browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

Aynı işlemleri paylaşan birçok kural varsa bu kuralları tek bir kuralda birleştirin. Kurallar, tek bir koşul karşılanır karşılanmaz işlemlerini tetikler. Bu, eşleşmeyi hızlandırır ve yinelenen işlem kümeleri için bellek tüketimini azaltır.

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

Filtrelenmiş etkinlikler

Filtrelenmiş etkinlikler, dinleyicilerin ilgilendikleri etkinliklerin bir alt kümesini belirtmelerine olanak tanıyan bir mekanizmadır. Filtre kullanan bir dinleyici, filtreyi geçmeyen etkinlikler için çağrılmaz. Bu da dinleme kodunu daha bildirici ve verimli hale getirir. Hizmet çalışanı, ilgilenmediği etkinlikleri işlemek için uyandırılmak zorunda değildir.

Filtrelenen etkinlikler, manuel filtreleme kodundan geçişe olanak tanımak için tasarlanmıştır.

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Etkinlikler, o etkinlik için anlamlı olan belirli filtreleri destekler. Bir etkinliğin desteklediği filtrelerin listesi, "filtreler" bölümünde ilgili etkinliğin dokümanlarında yer alır.

URL'ler eşleştirilirken (yukarıdaki örnekte olduğu gibi) etkinlik filtreleri, şema ve bağlantı noktası eşleştirme hariç events.UrlFilter ile ifade edilebilen URL eşleştirme özelliklerini destekler.