chrome.events

Deskripsi

Namespace chrome.events berisi jenis umum yang digunakan oleh API yang mengirimkan peristiwa untuk memberi tahu Anda jika terjadi sesuatu yang menarik.

Event adalah objek yang memungkinkan Anda diberi tahu ketika terjadi sesuatu yang menarik. Berikut adalah contoh penggunaan peristiwa chrome.alarms.onAlarm untuk diberi tahu setiap kali alarm telah berlalu:

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

Seperti yang ditunjukkan dalam contoh, Anda mendaftar untuk notifikasi menggunakan addListener(). Argumen untuk addListener() selalu merupakan fungsi yang Anda tentukan untuk menangani peristiwa, tetapi merupakan parameter untuk bergantung pada peristiwa yang Anda tangani. Memeriksa dokumentasi untuk alarms.onAlarm, Anda dapat melihat bahwa fungsi tersebut memiliki satu parameter: objek alarms.Alarm yang memiliki detail tentang alarm yang lewat.

Contoh API yang menggunakan Peristiwa: alarm, i18n, identitas, runtime. Sebagian besar Chrome API.

Pengendali Peristiwa deklaratif

Pengendali peristiwa deklaratif menyediakan cara untuk menentukan aturan yang terdiri dari kondisi deklaratif tindakan dan tindakan. Kondisi dievaluasi di browser, bukan mesin JavaScript yang mengurangi latensi bolak-balik dan memungkinkan efisiensi yang sangat tinggi.

Pengendali peristiwa deklaratif digunakan misalnya dalam Declarative Web Request API dan Content API deklaratif. Halaman ini menjelaskan konsep dasar semua peristiwa deklaratif pengendali.

Aturan

Aturan paling sederhana yang mungkin terdiri dari satu atau beberapa kondisi dan satu atau beberapa tindakan:

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

Jika salah satu kondisi terpenuhi, semua tindakan akan dijalankan.

Selain ketentuan dan tindakan, Anda dapat memberikan ID pada setiap aturan, sehingga akan menyederhanakan membatalkan pendaftaran aturan yang sebelumnya terdaftar, dan prioritas untuk menentukan prioritas di antara aturan. Prioritas hanya dipertimbangkan jika aturan saling bertentangan atau perlu dijalankan dalam pesanan. Tindakan dijalankan dalam urutan menurun sesuai prioritas aturannya.

var rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Objek peristiwa

Objek peristiwa mungkin mendukung aturan. Objek peristiwa ini tidak memanggil fungsi callback saat peristiwa terjadi, tetapi menguji apakah aturan yang terdaftar memiliki setidaknya satu kondisi yang terpenuhi dan menjalankannya tindakan yang terkait dengan aturan ini. Objek peristiwa yang mendukung API deklaratif memiliki tiga metode yang relevan: events.Event.addRules, events.Event.removeRules, dan events.Event.getRules.

Menambahkan aturan

Untuk menambahkan aturan, panggil fungsi addRules() dari objek peristiwa. Dibutuhkan array instance aturan sebagai parameter pertamanya dan fungsi callback yang akan dipanggil setelah selesai.

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

Jika aturan berhasil disisipkan, parameter details berisi array aturan yang disisipkan muncul dalam urutan yang sama seperti dalam rule_list yang diteruskan tempat parameter opsional id dan priority diisi dengan nilai yang dihasilkan. Jika ada aturan yang tidak valid, misalnya, karena ada aturan yang kondisi atau tindakan yang tidak valid, tidak ada aturan yang ditambahkan dan variabel runtime.lastError ditetapkan saat fungsi callback dipanggil. Setiap aturan di rule_list harus berisi yang saat ini tidak digunakan oleh aturan lain atau pengenal kosong.

Menghapus aturan

Untuk menghapus aturan, panggil fungsi removeRules(). Metode ini menerima array opsional ID aturan sebagai parameter pertamanya dan fungsi callback sebagai parameter kedua.

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

Jika rule_ids adalah array ID, semua aturan yang memiliki ID yang tercantum dalam array tersebut dihapus. Jika rule_ids mencantumkan ID yang tidak diketahui, ID ini akan otomatis diabaikan. Jika rule_ids bernilai undefined, semua aturan yang terdaftar di ekstensi ini akan dihapus. callback() dipanggil ketika aturan dihapus.

Mengambil aturan

Untuk mengambil daftar aturan yang saat ini terdaftar, panggil fungsi getRules(). Properti ini menerima array opsional ID aturan dengan semantik yang sama dengan removeRules dan fungsi callback.

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

Parameter details yang diteruskan ke fungsi callback() mengacu pada array aturan termasuk parameter opsional yang terisi.

Performa

Untuk mencapai performa maksimum, perhatikan pedoman berikut.

Mendaftarkan dan membatalkan pendaftaran aturan secara massal. Setelah setiap pendaftaran atau pembatalan pendaftaran, Chrome harus memperbarui struktur data internal. Update ini adalah operasi yang mahal.

Jangan gunakan:

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

lebih suka:

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

Pilih pencocokan substring daripada ekspresi reguler dalam events.UrlFilter. Pencocokan berbasis substring sangat cepat.

Jangan gunakan:

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

lebih suka:

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

Jika banyak aturan yang memiliki tindakan yang sama, gabungkan aturan tersebut menjadi satu. Aturan memicu tindakannya segera setelah satu kondisi terpenuhi. Hal ini mempercepat cocok dan mengurangi pemakaian memori untuk kumpulan tindakan duplikat.

Jangan gunakan:

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

lebih suka:

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

Peristiwa yang difilter

Peristiwa yang difilter adalah mekanisme yang memungkinkan pemroses menetapkan subset peristiwa yang membuat Anda tertarik. Pemroses yang menggunakan filter tidak akan dipanggil untuk peristiwa yang tidak meneruskan {i>filter<i}, yang membuat kode yang mendengarkan lebih deklaratif dan efisien. Pekerja layanan membutuhkan tidak dibangunkan untuk menangani peristiwa yang tidak penting.

Peristiwa yang difilter dimaksudkan untuk memungkinkan transisi dari kode pemfilteran manual seperti ini:

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

menjadi ini:

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

Peristiwa mendukung filter tertentu yang berarti bagi peristiwa tersebut. Daftar filter yang peristiwa akan dicantumkan dalam dokumentasi untuk peristiwa itu dalam daftar “{i>filters<i}” bagian.

Saat mencocokkan URL (seperti pada contoh di atas), filter peristiwa mendukung pencocokan URL yang sama yang dapat diungkapkan dengan events.UrlFilter, kecuali untuk pencocokan skema dan port.

Jenis

Event

Objek yang memungkinkan penambahan dan penghapusan pemroses untuk peristiwa Chrome.

Properti

  • addListener

    void

    Mendaftarkan callback pemroses peristiwa ke sebuah peristiwa.

    Fungsi addListener akan terlihat seperti ini: 

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

    • callback

      H

      Dipanggil saat peristiwa terjadi. Parameter fungsi ini bergantung pada jenis peristiwa.

  • addRules

    void

    Mendaftarkan aturan untuk menangani peristiwa.

    Fungsi addRules akan terlihat seperti ini: 

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

    • rules

      Aturan<anyany>[]

      Aturan yang harus didaftarkan. Aturan ini tidak menggantikan aturan yang telah didaftarkan sebelumnya.

    • callback

      fungsi opsional

      Parameter callback terlihat seperti ini: 

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

      • rules

        Aturan<anyany>[]

        Aturan yang didaftarkan, parameter opsional diisi dengan nilai.

  • getRules

    void

    Menampilkan aturan yang saat ini terdaftar.

    Fungsi getRules akan terlihat seperti ini: 

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

    • ruleIdentifiers

      string[] opsional

      Jika array diteruskan, hanya aturan dengan ID yang terdapat dalam array ini yang akan ditampilkan.

    • callback

      fungsi

      Parameter callback terlihat seperti ini: 

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

      • rules

        Aturan<anyany>[]

        Aturan yang didaftarkan, parameter opsional diisi dengan nilai.

  • hasListener

    void

    Fungsi hasListener akan terlihat seperti ini: 

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

    • callback

      H

      Pemroses yang status pendaftarannya harus diuji.

    • akan menampilkan

      boolean

      True jika callback terdaftar ke peristiwa.

  • hasListeners

    void

    Fungsi hasListeners akan terlihat seperti ini: 

    () => {...}

    • akan menampilkan

      boolean

      True jika ada pemroses peristiwa yang terdaftar ke peristiwa.

  • removeListener

    void

    Membatalkan pendaftaran callback pemroses peristiwa dari peristiwa.

    Fungsi removeListener akan terlihat seperti ini: 

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

    • callback

      H

      Pemroses yang harus dibatalkan pendaftarannya.

  • removeRules

    void

    Membatalkan pendaftaran aturan yang saat ini terdaftar.

    Fungsi removeRules akan terlihat seperti ini: 

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

    • ruleIdentifiers

      string[] opsional

      Jika array diteruskan, hanya aturan dengan ID yang terdapat dalam array ini yang akan dibatalkan pendaftarannya.

    • callback

      fungsi opsional

      Parameter callback terlihat seperti ini: 

      () => void

Rule

Deskripsi aturan deklaratif untuk menangani peristiwa.

Properti

  • tindakan

    setiap[]

    Daftar tindakan yang dipicu jika salah satu kondisi terpenuhi.

  • kondisi

    setiap[]

    Daftar kondisi yang dapat memicu tindakan.

  • id

    string opsional

    ID opsional yang mengizinkan referensi aturan ini.

  • prioritas

    angka opsional

    Prioritas opsional aturan ini. Setelan defaultnya adalah 100.

  • tag

    string[] opsional

    Tag dapat digunakan untuk memberi anotasi pada aturan dan menjalankan operasi pada kumpulan aturan.

UrlFilter

Memfilter URL untuk berbagai kriteria. Lihat pemfilteran peristiwa. Semua kriteria peka huruf besar/kecil.

Properti

  • cidrBlocks

    string[] opsional

    Chrome 123 dan yang lebih baru

    Mencocokkan jika bagian host URL adalah alamat IP dan terdapat di salah satu blok CIDR yang ditentukan dalam array.

  • hostContains

    string opsional

    Mencocokkan jika nama host URL berisi string yang ditentukan. Untuk menguji apakah komponen nama host memiliki awalan 'foo', gunakan hostContains: '.foo'. Ini cocok dengan 'www.foobar.com' dan 'foo.com', karena titik implisit ditambahkan di awal nama {i>host<i}. Demikian pula, hostContains dapat digunakan untuk mencocokkan dengan akhiran komponen ('foo.') dan sama persis dengan komponen ('.foo.'). Pencocokan akhir dan pencocokan persis untuk komponen terakhir harus dilakukan secara terpisah menggunakan hostSuffix, karena tidak ada titik implisit yang ditambahkan di akhir nama host.

  • hostEquals

    string opsional

    Mencocokkan jika nama host URL sama dengan string yang ditentukan.

  • hostPrefix

    string opsional

    Cocok jika nama host URL diawali dengan string yang ditentukan.

  • hostSuffix

    string opsional

    Cocok jika nama host URL diakhiri dengan string yang ditentukan.

  • originAndPathMatches

    string opsional

    Cocok jika URL tanpa segmen kueri dan ID fragmen cocok dengan ekspresi reguler yang ditentukan. Nomor port akan dihilangkan dari URL jika cocok dengan nomor port default. Ekspresi reguler menggunakan sintaksis RE2.

  • pathContains

    string opsional

    Mencocokkan jika segmen jalur URL berisi string yang ditentukan.

  • pathEquals

    string opsional

    Mencocokkan jika segmen jalur URL sama dengan string yang ditentukan.

  • pathPrefix

    string opsional

    Cocok jika segmen jalur URL dimulai dengan string yang ditentukan.

  • pathSuffix

    string opsional

    Cocok jika segmen jalur URL diakhiri dengan string yang ditentukan.

  • ports

    (number | number[])[] opsional

    Cocok jika port URL terdapat dalam salah satu daftar port yang ditentukan. Misalnya, [80, 443, [1000, 1200]] cocok dengan semua permintaan di port 80, 443, dan dalam rentang 1000-1200.

  • queryContains

    string opsional

    Mencocokkan jika segmen kueri URL berisi string yang ditentukan.

  • queryEquals

    string opsional

    Mencocokkan jika segmen kueri URL sama dengan string yang ditentukan.

  • queryPrefix

    string opsional

    Cocok jika segmen kueri URL dimulai dengan string yang ditentukan.

  • querySuffix

    string opsional

    Cocok jika segmen kueri URL diakhiri dengan string yang ditentukan.

  • skema

    string[] opsional

    Mencocokkan jika skema URL sama dengan salah satu skema yang ditentukan dalam array.

  • urlContains

    string opsional

    Mencocokkan jika URL (tanpa ID fragmen) berisi string yang ditentukan. Nomor port akan dihilangkan dari URL jika cocok dengan nomor port default.

  • urlEquals

    string opsional

    Mencocokkan jika URL (tanpa ID fragmen) sama dengan string yang ditentukan. Nomor port akan dihilangkan dari URL jika cocok dengan nomor port default.

  • urlMatches

    string opsional

    Mencocokkan jika URL (tanpa ID fragmen) cocok dengan ekspresi reguler yang ditentukan. Nomor port akan dihapus dari URL jika cocok dengan nomor port default. Ekspresi reguler menggunakan sintaksis RE2.

  • urlPrefix

    string opsional

    Mencocokkan jika URL (tanpa ID fragmen) dimulai dengan string yang ditentukan. Nomor port akan dihilangkan dari URL jika cocok dengan nomor port default.

  • urlSuffix

    string opsional

    Cocok jika URL (tanpa ID fragmen) diakhiri dengan string yang ditentukan. Nomor port akan dihapus dari URL jika cocok dengan nomor port default.