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.

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

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
});

Örnekte gösterildiği gibi, bildirime addListener() kullanarak kaydolursunuz. Bağımsız değişken addListener() her zaman etkinliği işlemek için tanımladığınız bir işlevdir ancak işlevi, gerçekleştirdiğiniz etkinliğe bağlıdır. alarms.onAlarm ile ilgili dokümanlar kontrol ediliyor, işlevin tek bir parametreye (ayrıntılar içeren bir alarms.Alarm nesnesi) sahip olduğunu görebilirsiniz geçen alarmla ilgili.

Etkinlikleri kullanan örnek API'ler: alarms, i18n, identity, runtime. Chrome'un çoğu API'lerde çalışır.

Bildirim Temelli Etkinlik İşleyiciler

Bildirim temelli etkinlik işleyiciler, bildirim temelli koşullardan oluşan kuralları tanımlamak için bir yöntem sağlar. ve işlemler. Koşullar, JavaScript motoru yerine tarayıcıda değerlendirilir. Bu da gecikmelere neden oluyor ve son derece yüksek verimlilik sağlıyor.

Bildirim temelli etkinlik işleyiciler, örneğin Declarative Web Request API'de ve Declarative Content API. Bu sayfada, tüm bildirimli etkinliklerin temel kavramları açıklanmaktadır işleyicileri tarafından desteklenmektedir.

Kurallar

Olası en basit kural, bir veya daha fazla koşuldan ve bir ya da daha fazla işlemden oluşur:

var 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şlemlere ek olarak, her kurala bir tanımlayıcı verebilirsiniz. Bu tanımlayıcı daha önce kaydedilmiş kuralların kaydını silme ve kurallar arasındaki öncelikleri tanımlamaya öncelik verir. Öncelikler yalnızca, kurallar birbiriyle çakıştığında veya belirli bir sipariş. İşlemler, kurallarının önceliğine göre azalan düzende yürütülür.

var 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, olaylar gerçekleşir, ancak kayıtlı herhangi bir kuralın en az bir yerine getirilmiş koşul içerip içermediğini test eder ve bu kuralla ilişkili işlemlerdir. Bildirim temelli API'yi destekleyen etkinlik nesnelerinde üç bulunur alakalı yöntemler: events.Event.addRules, events.Event.removeRules ve events.Event.getRules.

Kural ekleniyor

Kural eklemek için etkinlik nesnesinin addRules() işlevini çağırın. Bir dizi kural örneği alır işlevini çağırır.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

Kurallar başarıyla eklendiyse details parametresi, eklenen kurallardan oluşan bir dizi içerir rule_list isteğe bağlı parametrelerin id ve priority oluşturulan değerlerle dolduruldu. Herhangi bir kural geçersizse (ör. geçersiz bir koşul veya işlem görüyorsanız kurallardan hiçbiri eklenmez ve runtime.lastError değişkeni değeri, geri çağırma işlevi çağrıldığında ayarlanır. rule_list grubundaki her kural benzersiz bir değer içermelidir şu anda başka bir kural veya boş tanımlayıcı tarafından kullanılmayan tanımlayıcı.

Kurallar kaldırılıyor

Kuralları kaldırmak için removeRules() işlevini çağırın. İsteğe bağlı kural tanımlayıcıları dizisini kabul eder ilk parametresi olarak ve ikinci parametresi olarak bir geri çağırma işlevi kullanılır.

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

rule_ids bir tanımlayıcı dizisiyse dizide listelenmiş tanımlayıcılara sahip tüm kurallar emin olun. rule_ids tarafından bilinmeyen bir tanımlayıcı listeleniyorsa bu tanımlayıcı sessizce yoksayılır. Eğer rule_ids undefined. Bu uzantının tüm kayıtlı kuralları kaldırıldı. callback() işlevi, kurallar kaldırıldığında çağrılır.

Kurallar alınıyor

Kayıtlı olan kuralların listesini almak için getRules() işlevini çağırın. Kabul edilen bir removeRules ile aynı anlama sahip isteğe bağlı kural tanımlayıcıları ve geri çağırma işlevi dizisi.

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});

callback() işlevine iletilen details parametresi, şunları içeren bir kural dizisine başvurur: doldurulan isteğe bağlı parametrelerdir.

Performans

En yüksek performansa ulaşmak için aşağıdaki yönergeleri aklınızda bulundurmanız gerekir.

Kuralları toplu olarak kaydedin ve kayıtlarını iptal edin. Her kayıt veya kaydın iptal edilmesinden sonra Chrome'un şunları yapması gerekir: dahili veri yapılarını güncellemektir. Bu güncelleme pahalı bir işlemdir.

Şunun yerine:

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

tercih edin:

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

events.UrlFilter içindeki normal ifadeler yerine alt dize eşleştirmesini tercih edin. Alt dizeye dayalı eşleştirme son derece hızlıdır.

Şunun yerine:

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

tercih edin:

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

Aynı işlemleri paylaşan birden fazla kural varsa bunları tek bir kuralda birleştirin. Kurallar, tek bir koşul karşılanır edilmez işlemlerini tetikler. Bu da ekip arkadaşlarınızın eşleşmesini sağlar ve yinelenen işlem grupları için bellek tüketimini azaltır.

Şunun yerine:

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

tercih edin:

  var rule = { conditions: [condition1, condition2],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]};
  chrome.declarativeWebRequest.onRequest.addRules([rule]);

Filtrelenen etkinlikler

Filtrelenmiş etkinlikler, dinleyicilerin etkinleştirdikleri etkinliklerin alt kümelerini belirtmesine olanak tanıyan mekanizmadır. emin olabilirsiniz. Filtre kullanan bir işleyici Bu filtre, dinleme kodunu daha bildirimsel ve verimli hale getirir. Service Worker'a yönelik bir ihtiyaç umursamadığı olaylara karşı uyanmadı.

Filtrelenmiş etkinlikler, aşağıdaki gibi manuel filtreleme kodundan geçişe olanak tanımak için tasarlanmıştır:

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

şunu yaz:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Etkinlikler, söz konusu etkinlik için anlamlı olan belirli filtreleri destekler. Bir etkinliğin düzenlediği filtrelerin "filtreler" sütunundaki bu etkinlikle ilgili dokümanlarda listelenir bölümüne ekleyin.

Etkinlik filtreleri, URL'leri eşleştirirken (yukarıdaki örnekte olduğu gibi) aynı URL eşleşmesini destekler özellikleri, şema ve bağlantı noktası eşleştirme hariç, events.UrlFilter ile ifade edilebilir.

Türler

Event

Bir Chrome etkinliği için işleyici eklemeye ve kaldırmaya olanak tanıyan bir nesne.

Özellikler

  • addListener

    geçersiz

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

    addListener işlevi aşağıdaki gibi görünür: 

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

    • geri çağırma

      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 aşağıdaki gibi görünür: 

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

    • kurallar

      Kural<herhangi bir>[]

      Kaydedilecek kurallar. Bunlar daha önce kaydedilmiş kuralların yerine geçmez.

    • geri çağırma

      işlev 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 dolduruldu.

  • getRules

    geçersiz

    Şu anda kayıtlı olan kuralları döndürür.

    getRules işlevi aşağıdaki gibi görünür: 

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

    • ruleIdentifiers

      string[] isteğe bağlı

      Bir dizi aktarılırsa yalnızca bu dizide bulunan 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 dolduruldu.

  • hasListener

    geçersiz

    hasListener işlevi aşağıdaki gibi görünür: 

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

    • geri çağırma

      H

      Kayıt durumu test edilecek dinleyici.

    • returns

      boolean

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

  • hasListeners

    geçersiz

    hasListeners işlevi aşağıdaki gibi görünür: 

    () => {...}

    • returns

      boolean

      Etkinliğe herhangi bir etkinlik işleyici kayıtlıysa doğru değerini döndürür.

  • removeListener

    geçersiz

    Bir etkinlikteki etkinlik işleyici geri çağırma kaydını siler.

    removeListener işlevi aşağıdaki gibi görünür: 

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

    • geri çağırma

      H

      Dinleyici kaydı iptal edilecek.

  • removeRules

    geçersiz

    Şu anda kayıtlı olan kuralların kaydını iptal eder.

    removeRules işlevi aşağıdaki gibi görünür: 

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

    • ruleIdentifiers

      string[] isteğe bağlı

      Bir dizi aktarılırsa yalnızca bu dizide bulunan tanımlayıcılara sahip kuralların kaydı iptal edilir.

    • geri çağırma

      işlev isteğe bağlı

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

      () => void

Rule

Etkinlikleri işlemeye ilişkin bildirim temelli bir kuralın açıklaması.

Özellikler

  • işlemler

    herhangi biri[]

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

  • koşul

    herhangi biri[]

    İşlemleri tetikleyebilecek koşulların listesi.

  • id

    dize isteğe bağlı

    Bu kuralın uygulanmasına olanak tanıyan isteğe bağlı tanımlayıcı.

  • önceliği

    sayı 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 gerçekleştirmek için kullanılabilir.

UrlFilter

URL'leri çeşitli ölçütlere göre 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 'nı inceleyin.

    URL'nin ana makine bölümü bir IP adresiyse ve dizide belirtilen CIDR bloklarından herhangi birinde yer alıyorsa eşleşir.

  • hostContains

    dize 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" ifadesini kullanın. Bu, "www.foobar.com" ile eşleşir gizli bir nokta olduğundan, ana makine adının başına eklenmiş olduğundan emin olun. Benzer şekilde, HostContains, bileşen son ekiyle ("foo.") ve bileşenlerle (".foo.") tam olarak eşleştirmek için kullanılabilir. Ana makine adının sonuna hiçbir örtülü nokta eklenmediğinden, son bileşenler için sonek ve tam eşlemenin hostsSuffix kullanılarak ayrı olarak yapılması gerekir.

  • hostEquals

    dize isteğe bağlı

    URL'nin ana makine adı, belirtilen bir dizeye eşitse eşleşir.

  • hostPrefix

    dize isteğe bağlı

    URL'nin ana makine adı belirtilen bir dizeyle başlıyorsa eşleşir.

  • hostSuffix

    dize isteğe bağlı

    URL'nin ana makine adı belirtilen bir dizeyle bitiyorsa eşleşir.

  • originAndPathMatches

    dize 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. Varsayılan bağlantı noktası numarasıyla eşleşen bağlantı noktası numaraları URL'den çıkarılır. Normal ifadeler RE2 söz dizimini kullanır.

  • pathContains

    dize isteğe bağlı

    URL'nin yol segmenti belirtilen bir dize içeriyorsa eşleşir.

  • pathEquals

    dize isteğe bağlı

    URL'nin yol segmenti belirtilen bir dizeye eşitse eşleşir.

  • pathPrefix

    dize isteğe bağlı

    URL'nin yol segmenti belirtilen bir dizeyle başlıyorsa eşleşir.

  • pathSuffix

    dize 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 yer alıyorsa eşleşir. Örneğin [80, 443, [1000, 1200]]; 80, 443 ve 1000-1200 aralığındaki tüm isteklerle eşleşir.

  • queryContains

    dize isteğe bağlı

    URL'nin sorgu segmenti belirtilen bir dize içeriyorsa eşleşir.

  • queryEquals

    dize isteğe bağlı

    URL'nin sorgu segmenti belirtilen bir dizeye eşitse eşleşir.

  • queryPrefix

    dize isteğe bağlı

    URL'nin sorgu segmenti belirtilen bir dizeyle başlıyorsa eşleşir.

  • querySuffix

    dize 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

    dize isteğe bağlı

    URL (parça tanımlayıcısı olmadan) belirtilen bir dize içeriyorsa eşleşir. Varsayılan bağlantı noktası numarasıyla eşleşen bağlantı noktası numaraları URL'den çıkarılır.

  • urlEquals

    dize isteğe bağlı

    URL (parça tanımlayıcısı olmadan) belirtilen bir dizeye eşitse eşleşir. Varsayılan bağlantı noktası numarasıyla eşleşen bağlantı noktası numaraları URL'den çıkarılır.

  • urlMatches

    dize isteğe bağlı

    URL (parça tanımlayıcısı olmadan) belirtilen bir normal ifadeyle eşleşirse eşleşir. Varsayılan bağlantı noktası numarasıyla eşleşen bağlantı noktası numaraları URL'den çıkarılır. Normal ifadeler RE2 söz dizimini kullanır.

  • urlPrefix

    dize isteğe bağlı

    URL (parça tanımlayıcısı olmadan) belirtilen bir dizeyle başlıyorsa eşleşir. Varsayılan bağlantı noktası numarasıyla eşleşen bağlantı noktası numaraları URL'den çıkarılır.

  • urlSuffix

    dize isteğe bağlı

    URL (parça tanımlayıcısı olmadan) belirtilen bir dizeyle bitiyorsa eşleşir. Varsayılan bağlantı noktası numarasıyla eşleşen bağlantı noktası numaraları URL'den çıkarılır.