browser.events

Açıklama

chrome.events ad alanı, ilginç bir şey olduğunda sizi bilgilendirmek için etkinlik gönderen API'ler tarafından kullanılan yaygın türleri içerir.

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 bildirim için 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, işlediğiniz etkinliğe bağlıdır. alarms.onAlarm ile ilgili belgelere baktığınızda işlevin tek bir parametresi olduğunu görebilirsiniz: Süresi dolan alarm hakkında ayrıntıları içeren bir alarms.Alarm nesnesi.

Etkinlikleri kullanan API'lere örnekler: alarms, i18n, identity, runtime. Çoğu chrome API'si bu şekilde çalışır.

Bildirime Dayalı Etkinlik İşleyiciler

Bildirim temelli etkinlik işleyiciler, bildirim temelli koşullar ve işlemlerden oluşan kurallar tanımlamanın bir yolunu sunar. Koşullar, JavaScript motoru yerine tarayıcıda değerlendirilir. Bu sayede gidiş dönüş gecikmeleri azalır ve çok yüksek verimlilik elde edilir.

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

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şullar ve işlemlerin yanı sıra her kurala bir tanımlayıcı verebilirsiniz. Bu sayede, önceden kaydedilmiş kuralların kaydını iptal etmek kolaylaşır. Ayrıca kurallar arasında öncelikleri tanımlamak için bir öncelik de belirleyebilirsiniz. Öncelikler yalnızca kurallar birbiriyle çelişiyorsa 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 bir geri çağırma işlevi çağırmaz ancak kayıtlı herhangi bir kuralın en az bir karşılanan 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 üç alakalı yöntemi vardır: events.Event.addRules(), events.Event.removeRules() ve events.Event.getRules().

Kural ekle

Reklam kuralları eklemek için etkinlik nesnesinin addRules() işlevini çağırın. İlk parametre olarak bir kural örnekleri dizisi ve 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 eklendiyse details parametresi, iletilen rule_list ile aynı sırada görünen eklenmiş kurallardan oluşan bir dizi içerir. Bu dizide, isteğ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 hiçbir kural 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 ve ikinci parametre olarak bir geri çağırma işlevi kabul eder.

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

rule_ids, bir tanımlayıcı dizisiyse dizide listelenen tanımlayıcıları içeren 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, 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ı semantiğe sahip isteğe bağlı bir kural tanımlayıcı dizisi ve bir geri çağırma 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ı iptal etme Her kayıttan veya kayıt iptalinden sonra Chrome'un dahili veri yapılarını güncellemesi gerekir. Bu güncelleme, yüksek miktarda kaynak tüketen bir işlemdir.

Bunu şu ifadenin yerine kullanırsınız:
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);
Tercih
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

events.UrlFilter'da normal ifadeler yerine alt dize eşleştirmeyi tercih edin. Alt dizeye dayalı eşleştirme son derece hızlıdır.

Bunu şu ifadenin yerine kullanırsınız:
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
Tercih
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

Aynı işlemleri paylaşan çok sayıda kural varsa 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 grupları için bellek tüketimini azaltır.

Bunu şu ifadenin yerine kullanırsınız:
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]);
Tercih
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 belirtmesine olanak tanıyan bir mekanizmadır. Filtre kullanan bir dinleyici, filtreyi geçemeyen etkinlikler için çağrılmaz. Bu sayede dinleme kodu daha açıklayıcı ve verimli olur. Hizmet çalışanının, ilgilenmediği etkinlikleri işlemek için uyandırılması gerekmez.

Filtrelenen etkinlikler, manuel filtreleme kodundan geçiş yapılmasına olanak tanır.

Bunu şu ifadenin yerine kullanırsınız:
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Tercih
browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

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 URL eşleştirme özelliklerini destekler.

Türler

Event

Chrome etkinliği için işleyici eklenmesine ve kaldırılmasına olanak tanıyan bir nesne.

Özellikler

  • addListener

    geçersiz

    Bir etkinliğe etkinlik işleyici geri çağırma işlevi kaydeder.

    addListener işlevi şu şekildedir: 

    (callback: H) => {...}

    • callback

      H

      Bir etkinlik gerçekleştiğinde çağrılır. Bu işlevin parametreleri, etkinliğin türüne bağlıdır.

  • addRules

    geçersiz

    Etkinlikleri işlemek için kuralları kaydeder.

    addRules işlevi şu şekildedir: 

    (rules: Rule<anyany>[], callback?: function) => {...}

    • kurallar

      Kural<anyany>[]

      Kayıt kuralları. Bu kurallar, daha önce kaydedilmiş kuralların yerini almaz.

    • callback

      function isteğe bağlı

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

      (rules: Rule<anyany>[]) => void

      • kurallar

        Kural<anyany>[]

        Kayıtlı kurallarda isteğe bağlı parametreler değerlerle doldurulur.

  • getRules

    geçersiz

    Kayıtlı kuralları döndürür.

    getRules işlevi şu şekildedir: 

    (ruleIdentifiers?: string[], callback: function) => {...}

    • ruleIdentifiers

      string[] isteğe bağlı

      Bir dizi iletilirse yalnızca bu dizide yer alan tanımlayıcılara sahip kurallar döndürülür.

    • callback

      işlev

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

      (rules: Rule<anyany>[]) => void

      • kurallar

        Kural<anyany>[]

        Kayıtlı kurallarda isteğe bağlı parametreler değerlerle doldurulur.

  • hasListener

    geçersiz

    hasListener işlevi şu şekildedir: 

    (callback: H) => {...}

    • callback

      H

      Kayıt durumu test edilecek işleyici.

    • returns

      boole

      callback etkinliğe kayıtlıysa True değerini döndürür.

  • hasListeners

    geçersiz

    hasListeners işlevi şu şekildedir: 

    () => {...}

    • returns

      boole

      Etkinliğe kayıtlı etkinlik işleyiciler varsa doğru değerini alır.

  • removeListener

    geçersiz

    Bir etkinlikten etkinlik işleyici geri çağırma kaydını iptal eder.

    removeListener işlevi şu şekildedir: 

    (callback: H) => {...}

    • callback

      H

      Kaydı iptal edilecek dinleyici.

  • removeRules

    geçersiz

    Kayıtlı kuralların kaydını iptal eder.

    removeRules işlevi şu şekildedir: 

    (ruleIdentifiers?: string[], callback?: function) => {...}

    • ruleIdentifiers

      string[] isteğe bağlı

      Bir dizi iletilirse yalnızca bu dizide yer alan tanımlayıcılara sahip kuralların kaydı iptal edilir.

    • callback

      function isteğe bağlı

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

      () => void

Rule

Etkinlikleri işlemek için kullanılan bildirim kuralının açıklaması.

Özellikler

  • işlemler

    any[]

    Koşullardan biri karşılanırsa tetiklenen işlemlerin listesi.

  • koşul

    any[]

    İşlemleri tetikleyebilecek koşulların listesi.

  • id

    string isteğe bağlı

    Bu kurala referans verilmesine olanak tanıyan isteğe bağlı tanımlayıcı.

  • önceliği

    number 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şlem yapmak için kullanılabilir.

UrlFilter

URL'leri çeşitli ölçütlere göre filtreler. Etkinlik filtreleme bölümüne bakın. 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ümler Chrome 148'den itibaren browser.*

    URL'nin ana makine kısmı bir IP adresiyse ve dizide belirtilen CIDR bloklarından herhangi birinde yer alıyorsa eşleşir.

  • hostContains

    string isteğe bağlı

    URL'nin ana makine adı belirtilen bir dizeyi içeriyorsa eşleşir. Bir ana makine adı bileşeninin "foo" önekine sahip olup olmadığını test etmek için hostContains: ".foo" ifadesini kullanın. Ana makine adının başına örtük bir nokta eklendiğinden bu, "www.foobar.com" ve "foo.com" ile eşleşir. Benzer şekilde, hostContains bileşen son ekiyle ('foo.') ve bileşenlerle ('.foo.') tam eşleşme için kullanılabilir. Ana makine adının sonuna örtük nokta eklenmediğinden, son bileşenler için son ek ve tam eşleme, hostSuffix kullanılarak ayrı ayrı yapılmalıdır.

  • 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 bir 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 dizeyi 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

    (number | number[])[] isteğe bağlı

    URL'nin bağlantı noktası, belirtilen bağlantı noktası listelerinden herhangi birinde yer alıyorsa eşleşir. Örneğin, [80, 443, [1000, 1200]] 80, 443 numaralı bağlantı noktalarındaki ve 1000-1200 aralığındaki tüm isteklerle eşleşir.

  • queryContains

    string isteğe bağlı

    URL'nin sorgu segmenti belirtilen bir dizeyi 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 dizeyle başlıyorsa eşleşir.

  • querySuffix

    string isteğe bağlı

    URL'nin sorgu segmenti belirtilen bir dizeyle bitiyorsa eşleşir.

  • şemalar

    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ı olmadan) belirtilen bir dizeyi 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ı 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ı olmadan) belirtilen bir normal ifadeyle eşleşiyorsa 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ı 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ı 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.