browser.events

Deskripsi

Konsep dan penggunaan

Event adalah objek yang memungkinkan Anda mendapatkan notifikasi saat ada sesuatu yang menarik. Berikut adalah contoh penggunaan peristiwa browser.alarms.onAlarm untuk mendapatkan notifikasi setiap kali alarm telah berlalu:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Seperti yang ditunjukkan contoh, Anda mendaftar untuk menerima notifikasi menggunakan addListener(). Argumen untuk addListener() selalu berupa fungsi yang Anda tentukan untuk menangani peristiwa, tetapi parameter untuk fungsi bergantung pada peristiwa yang Anda tangani. Dengan memeriksa dokumentasi untuk alarms.onAlarm, Anda dapat melihat bahwa fungsi ini memiliki satu parameter: objek alarms.Alarm yang memiliki detail tentang alarm yang telah berlalu.

Contoh API yang menggunakan Events: alarms, i18n, identity, runtime. Sebagian besar chrome API melakukannya.

Pengendali Peristiwa Deklaratif

Handler peristiwa deklaratif menyediakan cara untuk menentukan aturan yang terdiri dari kondisi dan tindakan deklaratif. Kondisi dievaluasi di browser, bukan di mesin JavaScript, sehingga mengurangi latensi pulang pergi dan memungkinkan efisiensi yang sangat tinggi.

Misalnya, pengendali peristiwa deklaratif digunakan dalam Declarative Content API. Halaman ini menjelaskan konsep dasar semua pengendali peristiwa deklaratif.

Aturan

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

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

Jika salah satu kondisi terpenuhi, semua tindakan akan dijalankan.

Selain kondisi dan tindakan, Anda dapat memberikan ID untuk setiap aturan, yang menyederhanakan pembatalan pendaftaran aturan yang sebelumnya terdaftar, dan prioritas untuk menentukan urutan aturan. Prioritas hanya dipertimbangkan jika aturan saling bertentangan atau perlu dieksekusi dalam urutan tertentu. Tindakan dijalankan dalam urutan menurun berdasarkan prioritas aturannya.

const 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 dapat mendukung aturan. Objek peristiwa ini tidak memanggil fungsi callback saat peristiwa terjadi, tetapi menguji apakah ada aturan terdaftar yang memiliki minimal satu kondisi yang terpenuhi dan menjalankan 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. Fungsi ini menggunakan array instance aturan sebagai parameter pertamanya dan fungsi callback yang dipanggil setelah selesai.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

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

Menghapus aturan

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

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

Jika rule_ids adalah array ID, semua aturan yang memiliki ID yang tercantum dalam array akan dihapus. Jika rule_ids mencantumkan ID yang tidak diketahui, ID ini akan diabaikan secara diam-diam. Jika rule_ids adalah undefined, semua aturan terdaftar ekstensi ini akan dihapus. Fungsi callback() dipanggil saat aturan dihapus.

Mengambil aturan

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

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

Parameter details yang diteruskan ke fungsi callback() merujuk ke array aturan termasuk parameter opsional yang diisi.

Performa

Untuk mencapai performa maksimum, Anda harus mengingat panduan berikut.

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

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

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

Lebih memilih pencocokan substring daripada ekspresi reguler di events.UrlFilter. Pencocokan berbasis substring sangat cepat.

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

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

Jika ada banyak aturan yang memiliki tindakan yang sama, gabungkan aturan tersebut menjadi satu. Aturan memicu tindakannya segera setelah satu kondisi terpenuhi. Hal ini akan mempercepat pencocokan dan mengurangi penggunaan memori untuk set tindakan duplikat.

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

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

Peristiwa yang difilter

Peristiwa yang difilter adalah mekanisme yang memungkinkan pemroses menentukan subset peristiwa yang mereka minati. Pemroses yang menggunakan filter tidak akan dipanggil untuk peristiwa yang tidak lulus filter, sehingga kode pemrosesan menjadi lebih deklaratif dan efisien. Service worker tidak perlu diaktifkan untuk menangani peristiwa yang tidak diperlukannya.

Peristiwa yang difilter dimaksudkan untuk memungkinkan transisi dari kode pemfilteran manual.

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

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Peristiwa mendukung filter tertentu yang bermakna untuk peristiwa tersebut. Daftar filter yang didukung peristiwa akan dicantumkan dalam dokumentasi untuk peristiwa tersebut di bagian "filter".

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