chrome.events

refresh date: 2026-09-25 robots: noindex

Açıklama

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

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

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

Örnekte gösterildiği gibi, addListener() kullanarak bildirimlere kaydolursunuz. addListener() işlevinin 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, 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 İşleyicileri

Bildirim temelli etkinlik işleyiciler, bildirim temelli koşullar ve işlemlerden oluşan kuralları tanımlamak için bir yöntem sunar. Koşullar, gidiş dönüş gecikmelerini azaltan ve çok yüksek verimlilik sağlayan JavaScript motoru yerine tarayıcıda değerlendirilir.

Bildirimsel etkinlik işleyiciler, örneğin Declarative Web Request API ve Declarative Content API'de 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:

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şullara ve işlemlere ek olarak, her kurala bir tanımlayıcı atayabilirsiniz. Bu tanımlayıcı, daha önce kaydedilmiş kuralların kaydını silmeyi kolaylaştırır. Ayrıca, kurallar arasındaki öncelikleri tanımlamak için her kurala bir öncelik atayabilirsiniz. Ö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.

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, etkinlikler gerçekleştiğinde geri çağırma işlevini çağırmaz ancak kayıtlı kurallardan herhangi birinin en az bir koşulu karşılayıp karşılamadığını test eder ve bu kuralla ilişkili 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 ekleme

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.

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

Kurallar başarıyla eklenirse details parametresi, eklenen kuralların bir dizisini içerir. Bu kurallar, iletilen rule_list ile aynı sırada görünür. Burada, isteğe bağlı id ve priority parametreleri oluşturulan değerlerle doldurulmuştur. Geçersiz bir koşul veya işlem içerdiği için geçersiz olan kurallar eklenmez ve geri çağırma işlevi çağrıldığında runtime.lastError değişkeni ayarlanır. rule_list içindeki her kural, şu anda 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 kabul eder.

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

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. If rule_ids is undefined, all registered rules of this extension are removed. Kurallar kaldırıldığında callback() işlevi çağrılır.

Kuralları alma

Şu anda 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ıları dizisini ve bir geri çağırma işlevini kabul eder.

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(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.

Şunun yerine:

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

tercih etme:

var rule1 = {...};
var rule2 = {...};
chrome.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.

Şunun yerine:

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

tercih etme:

var match = new chrome.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.

Ş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 etme:

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

Filtrelenen etkinlikler

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

Filtrelenen etkinlikler, şu gibi manuel filtreleme kodundan geçişe olanak tanımayı amaçlar:

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

şuna dönüştürün:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {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ümanı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ç olmak üzere events.UrlFilter ile ifade edilebilen URL eşleştirme özelliklerinin aynısını destekler.

Türler

Event

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

Özellikler

  • addListener

    void

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

    addListener işlevi şu şekilde görünür: 

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

    • callback

      H

      Bir etkinlik gerçekleştiğinde çağrılır. Bu işlevin parametreleri, etkinlik 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<anyany>[]

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

    • callback

      işlev isteğe bağlı

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

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

      • kurallar

        Kural<anyany>[]

        Kaydedilen kurallar, isteğe bağlı parametreler değerlerle doldurulur.

  • getRules

    void

    Şu anda 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 iletilirse yalnızca bu dizideki tanımlayıcıları içeren 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ı kurallar, isteğe bağlı parametreler değerlerle doldurulur.

  • hasListener

    void

    hasListener işlevi şu şekilde görünür: 

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

    • callback

      H

      Kayıt durumu test edilecek işleyici.

    • returns

      boole

      callback etkinliğe kaydedilmişse doğru değerini alır.

  • hasListeners

    void

    hasListeners işlevi şu şekilde görünür: 

    () => {...}

    • returns

      boole

      Etkinliğe herhangi bir etkinlik işleyicisi kaydedilmişse doğru değerini alır.

  • removeListener

    void

    Bir etkinlik işleyici geri çağırma işlevini bir etkinlikten kaydını siler.

    removeListener işlevi şu şekilde görünür: 

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

    • callback

      H

      Kaydı silinecek işleyici.

  • 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 iletilirse yalnızca bu dizideki tanımlayıcıları içeren kuralların kaydı silinir.

    • callback

      işlev isteğe bağlı

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

      () => void

Rule

Etkinliklerin işlenmesi için bildirim temelli bir kuralı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

    dize 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 açıklama eklemek ve kural kümelerinde işlemler gerçekleştirmek için kullanılabilir.

UrlFilter

URL'leri çeşitli ölçütlere göre filtreler. Etkinlik filtreleme başlıklı makaleyi inceleyin. Tüm ölçütler büyük/küçük harfe duyarlıdır.

Özellikler

  • cidrBlocks

    string[] isteğe bağlı

    Chrome 123+

    URL'nin ana makine kısmı bir IP adresi ise 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 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ülü bir nokta eklendiğinden bu, "www.foobar.com" ve "foo.com" ile eşleşir. Benzer şekilde, hostContains, bileşen sonekiyle ("foo.") eşleşmek ve bileşenlerle tam olarak eşleşmek (".foo.") için kullanılabilir. Ana makine adının sonuna örtülü nokta eklenmediğinden, son bileşenler için sonek ve tam eşleme, hostSuffix kullanılarak ayrı ayrı yapılmalıdır.

  • 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şme gerçekleşir. Bağlantı noktası numaraları, varsayılan bağlantı noktası numarasıyla eşleşiyorsa URL'den kaldırılır. Normal ifadeler RE2 söz dizimini kullanır.

  • pathContains

    dize isteğe bağlı

    URL'nin yol segmenti belirtilen dizeyi 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 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

    (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 ve 443 bağlantı noktalarındaki ve 1000-1200 aralığındaki tüm isteklerle eşleşir.

  • queryContains

    dize isteğe bağlı

    URL'nin sorgu segmenti belirtilen dizeyi 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 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ı olmadan) belirtilen dizeyi içeriyorsa eşleşir. Bağlantı noktası numaraları, varsayılan bağlantı noktası numarasıyla eşleşiyorsa URL'den kaldırılır.

  • urlEquals

    dize 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 kaldırılır.

  • urlMatches

    dize isteğe bağlı

    URL (parça tanımlayıcı olmadan) 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 kaldırılır. Normal ifadeler RE2 söz dizimini kullanır.

  • urlPrefix

    dize 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 kaldırılır.

  • urlSuffix

    dize 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 kaldırılır.