Deskripsi
Namespace chrome.events
berisi jenis umum yang digunakan oleh API yang mengirim peristiwa untuk memberi tahu Anda ketika sesuatu yang menarik terjadi.
Konsep dan penggunaan
Event
adalah objek yang memungkinkan Anda diberi tahu jika terjadi sesuatu yang menarik. Berikut adalah
contoh penggunaan peristiwa chrome.alarms.onAlarm
untuk diberi tahu setiap kali alarm berlalu:
chrome.alarms.onAlarm.addListener((alarm) => {
appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});
Seperti yang ditunjukkan contoh, Anda mendaftar untuk notifikasi menggunakan addListener()
. Argumen untuk addListener()
selalu merupakan fungsi yang Anda tentukan untuk menangani peristiwa, tetapi parameter ke fungsi bergantung pada peristiwa yang Anda tangani. Dengan memeriksa dokumentasi untuk alarms.onAlarm
, Anda dapat melihat bahwa fungsi tersebut memiliki satu parameter: objek alarms.Alarm
yang memiliki detail tentang alarm yang berlalu.
Contoh API menggunakan Peristiwa: alarm, i18n, identitas, runtime. Sebagian besar chrome API melakukannya.
Pengendali Peristiwa Deklaratif
Pengendali peristiwa deklaratif menyediakan cara untuk menetapkan aturan yang terdiri dari kondisi dan tindakan deklaratif. Kondisi dievaluasi di browser, bukan mesin JavaScript, yang mengurangi latensi dua arah dan memungkinkan efisiensi yang sangat tinggi.
Pengendali peristiwa deklaratif digunakan, misalnya dalam Declarative Content API. Halaman ini menjelaskan konsep dasar dari semua pengendali peristiwa deklaratif.
Aturan
Aturan 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 dieksekusi.
Selain kondisi dan tindakan, Anda dapat memberikan ID pada setiap aturan, yang akan menyederhanakan pembatalan pendaftaran aturan yang sebelumnya terdaftar, dan memberikan prioritas untuk menentukan prioritas di antara aturan. Prioritas hanya dipertimbangkan jika aturan saling bertentangan atau perlu dijalankan dalam urutan tertentu. Tindakan dijalankan dalam urutan menurun sesuai 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 mungkin mendukung aturan. Objek peristiwa ini tidak memanggil fungsi callback saat
peristiwa terjadi, tetapi menguji apakah aturan terdaftar memiliki setidaknya 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()
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 dalam 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 ditetapkan saat fungsi callback dipanggil. Setiap aturan dalam rule_list
harus berisi ID unik yang belum digunakan oleh aturan lain atau ID kosong.
Hapus aturan
Untuk menghapus aturan, panggil fungsi removeRules()
. Fungsi ini menerima array ID aturan opsional sebagai parameter pertamanya dan fungsi callback sebagai parameter kedua.
const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});
Jika rule_ids
adalah array ID, semua aturan yang memiliki ID yang tercantum dalam array tersebut akan dihapus. Jika rule_ids
mencantumkan ID yang tidak diketahui, ID ini akan diabaikan secara diam-diam. Jika rule_ids
adalah undefined
, semua aturan yang terdaftar untuk ekstensi ini akan dihapus. Fungsi callback()
dipanggil saat aturan dihapus.
Mengambil aturan
Untuk mengambil daftar aturan terdaftar, panggil fungsi getRules()
. Fungsi ini menerima
array opsional ID aturan 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()
mengacu pada array aturan, termasuk parameter opsional yang terisi.
Performa
Untuk mencapai performa maksimal, perhatikan pedoman 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 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1]); chrome.declarativeWebRequest.onRequest.addRules([rule2]);
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
Memilih pencocokan substring daripada ekspresi reguler dalam events.UrlFilter. Pencocokan berbasis substring sangat cepat.
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {urlMatches: "example.com/[^?]*foo" } });
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {hostSuffix: "example.com", pathContains: "foo"} });
Jika ada banyak aturan yang memiliki tindakan yang sama, gabungkan aturan menjadi satu. Aturan memicu tindakannya segera setelah satu kondisi terpenuhi. Hal ini akan mempercepat pencocokan dan mengurangi konsumsi memori untuk kumpulan tindakan duplikat.
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]);
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]);
Peristiwa yang difilter
Peristiwa yang difilter adalah mekanisme yang memungkinkan pemroses menentukan subkumpulan peristiwa yang diminati. Pemroses yang menggunakan filter tidak akan dipanggil untuk peristiwa yang tidak lolos filter, sehingga kode pemrosesan menjadi lebih deklaratif dan efisien. Pekerja layanan tidak perlu diaktifkan untuk menangani peristiwa yang tidak diperlukan.
Peristiwa yang difilter dimaksudkan untuk memungkinkan transisi dari kode pemfilteran manual.
chrome.webNavigation.onCommitted.addListener((event) => { if (hasHostSuffix(event.url, 'google.com') || hasHostSuffix(event.url, 'google.com.au')) { // ... } });
chrome.webNavigation.onCommitted.addListener((event) => { // ... }, {url: [{hostSuffix: 'google.com'}, {hostSuffix: 'google.com.au'}]});
Peristiwa mendukung filter tertentu yang bermakna bagi 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.
Jenis
Event
Objek yang memungkinkan penambahan dan penghapusan pemroses untuk peristiwa Chrome.
Properti
-
addListener
void
Mendaftarkan callback pemroses peristiwa ke peristiwa.
Fungsi
addListener
terlihat seperti:(callback: H) => {...}
-
callback
H
Dipanggil saat peristiwa terjadi. Parameter fungsi ini bergantung pada jenis peristiwa.
-
-
addRules
void
Mendaftarkan aturan untuk menangani peristiwa.
Fungsi
addRules
terlihat seperti:(rules: Rule<anyany>[], callback?: function) => {...}
-
getRules
void
Menampilkan aturan yang saat ini terdaftar.
Fungsi
getRules
terlihat seperti:(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:(rules: Rule<anyany>[]) => void
-
rules
Aturan<anyany>[]
Aturan yang terdaftar, parameter opsional diisi dengan nilai.
-
-
-
hasListener
void
Fungsi
hasListener
terlihat seperti:(callback: H) => {...}
-
callback
H
Pemroses yang status pendaftarannya harus diuji.
-
akan menampilkan
boolean
True jika callback didaftarkan ke peristiwa.
-
-
hasListeners
void
Fungsi
hasListeners
terlihat seperti:() => {...}
-
akan menampilkan
boolean
True jika pemroses peristiwa didaftarkan ke peristiwa.
-
-
removeListener
void
Membatalkan pendaftaran callback pemroses peristiwa dari peristiwa.
Fungsi
removeListener
terlihat seperti:(callback: H) => {...}
-
callback
H
Pemroses yang akan dibatalkan pendaftarannya.
-
-
removeRules
void
Membatalkan pendaftaran aturan yang saat ini terdaftar.
Fungsi
removeRules
terlihat seperti:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] opsional
Jika array diteruskan, hanya aturan dengan ID yang terdapat dalam array ini yang tidak terdaftar.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
-
Rule
Deskripsi aturan deklaratif untuk menangani peristiwa.
Properti
-
tindakan
setiap[]
Daftar tindakan yang dipicu jika salah satu kondisi terpenuhi.
-
conditions
setiap[]
Daftar kondisi yang dapat memicu tindakan.
-
id
string opsional
ID opsional yang memungkinkan rujukan aturan ini.
-
prioritas
nomor opsional
Prioritas opsional dari aturan ini. Setelan defaultnya adalah 100.
-
tags
string[] opsional
Tag dapat digunakan untuk menganotasi 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 baruMencocokkan jika bagian host URL adalah alamat IP dan terdapat di salah satu blok CIDR yang ditentukan dalam array.
-
hostContains
string opsional
Cocok jika nama host URL berisi string yang ditentukan. Untuk menguji apakah komponen nama host memiliki awalan 'foo', gunakan hostContains: '.foo'. Nama ini cocok dengan 'www.foobar.com' dan 'foo.com', karena titik implisit ditambahkan di awal nama host. Demikian pula, hostContains dapat digunakan untuk mencocokkan akhiran komponen ('foo.') dan sama persis dengan komponen ('.foo.'). Pencocokan akhir dan persis untuk komponen terakhir harus dilakukan secara terpisah menggunakan hostSuffix, karena tidak ada titik implisit yang ditambahkan di akhir nama host.
-
hostEquals
string opsional
Cocok jika nama host URL sama dengan string yang ditentukan.
-
hostPrefix
string opsional
Cocok jika nama host URL dimulai dengan string yang ditentukan.
-
hostSuffix
string opsional
Cocok jika nama host URL diakhiri dengan string yang ditentukan.
-
originAndPathMatches
string opsional
Mencocokkan jika URL tanpa segmen kueri dan 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.
-
pathContains
string opsional
Cocok jika segmen jalur URL berisi string yang ditentukan.
-
pathEquals
string opsional
Cocok 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
(angka | number[])[] opsional
Mencocokkan jika port URL ada di salah satu daftar port yang ditentukan. Misalnya,
[80, 443, [1000, 1200]]
cocok dengan semua permintaan pada port 80, 443, dan rentang 1000-1200. -
queryContains
string opsional
Cocok jika segmen kueri URL berisi string yang ditentukan.
-
queryEquals
string opsional
Cocok 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.
-
schemes
string[] opsional
Mencocokkan jika skema URL sama dengan skema URL apa pun yang ditentukan dalam array.
-
urlContains
string opsional
Mencocokkan jika URL (tanpa ID fragmen) berisi string yang ditentukan. Nomor port akan dihapus 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 dihapus 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 dihapus dari URL jika cocok dengan nomor port default.
-
urlSuffix
string opsional
Mencocokkan jika URL (tanpa ID fragmen) diakhiri dengan string yang ditentukan. Nomor port akan dihapus dari URL jika cocok dengan nomor port default.