chrome.events

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.

Not: Kurallar, göz atma oturumlarında kalıcıdır. Bu nedenle, kuralları uzantı yükleme sırasında runtime.onInstalled etkinliğini kullanarak yüklemeniz gerekir. Bu etkinliğin, bir uzantı güncellendiğinde de tetiklendiğini unutmayın. Bu nedenle, önceden yüklenmiş kuralları temizlemeniz ve ardından yeni kurallar kaydetmeniz gerekir.

Kuralları kaldır

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.

Bunu şu ifadenin yerine kullanırsınız:

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

Tercih

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.

Bunu şu ifadenin yerine kullanırsınız:

const match = new chrome.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

Tercih

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.

Bunu şu ifadenin yerine kullanırsınız:

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]);

Tercih

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.

Bunu şu ifadenin yerine kullanırsınız:

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

Tercih

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ümler

  URL'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.