Chrome kini mendukung namespace browser.* standar (tersedia mulai Chrome 148). Kami memperbarui dokumentasi secara bertahap. Baca selengkapnya di panduan transisi kami.

Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

browser.events

Deskripsi

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

Konsep dan penggunaan

Event adalah objek yang memungkinkan Anda mendapatkan notifikasi saat terjadi 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 dalam contoh, Anda mendaftar untuk notifikasi menggunakan addListener(). Argumen untuk addListener() selalu berupa fungsi yang Anda tentukan untuk menangani peristiwa, tetapi parameter untuk fungsi tersebut 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 telah berlalu.

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

Pengendali Peristiwa Deklaratif

Pengendali 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 bolak-balik 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 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 telah didaftarkan sebelumnya, dan 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 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 acara dapat 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 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 akan 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 akan ditetapkan saat fungsi callback dipanggil. Setiap aturan di 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 otomatis. Jika rule_ids adalah undefined, semua aturan terdaftar dari ekstensi ini akan dihapus. Fungsi callback() dipanggil saat aturan dihapus.

Mengambil aturan

Untuk mengambil daftar aturan yang 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 diisi.

Performa

Untuk mencapai performa maksimum, Anda harus memperhatikan 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.

Daripada

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

Lebih suka

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.

Daripada

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

Lebih suka

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 akan memicu tindakannya segera setelah satu kondisi terpenuhi. Hal ini mempercepat pencocokan dan mengurangi konsumsi memori untuk set tindakan duplikat.

Daripada

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

Lebih suka

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 pemroses menjadi lebih deklaratif dan efisien. Service worker tidak perlu diaktifkan untuk menangani peristiwa yang tidak penting.

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

Daripada

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

Lebih suka

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 pada 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 suatu 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) => {...}
```
- rules
  
  Rule<anyany>[]
  
  Aturan yang akan didaftarkan. Aturan ini tidak menggantikan aturan yang telah didaftarkan sebelumnya.
- callback
  
  fungsi opsional
  
  Parameter callback terlihat seperti:
```
(rules: Rule<anyany>[]) => void
```
  - rules
    
    Rule<anyany>[]
    
    Aturan yang didaftarkan, parameter opsional diisi dengan nilai.
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
    
    Rule<anyany>[]
    
    Aturan yang didaftarkan, parameter opsional diisi dengan nilai.
hasListener

void

Fungsi hasListener terlihat seperti:
```
(callback: H) => {...}
```
- callback
  
  H
  
  Pemroses yang status pendaftarannya akan diuji.
- return
  boolean
  
  Benar jika callback terdaftar ke peristiwa.
hasListeners

void

Fungsi hasListeners terlihat seperti:
```
() => {...}
```
- return
  boolean
  
  Benar jika ada pemroses peristiwa yang terdaftar ke peristiwa.
removeListener

void

Membatalkan pendaftaran callback pemroses peristiwa dari suatu 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 didaftarkan.
- callback
  
  fungsi opsional
  
  Parameter callback terlihat seperti:
```
() => void
```

Rule

Deskripsi aturan deklaratif untuk menangani peristiwa.

Properti

tindakan

any[]

Daftar tindakan yang dipicu jika salah satu kondisi terpenuhi.
kondisi

any[]

Daftar kondisi yang dapat memicu tindakan.
id

string opsional

ID opsional yang memungkinkan referensi ke aturan ini.
prioritas

number opsional

Prioritas opsional aturan ini. Setelan defaultnya adalah 100.
tags

string[] opsional

Tag dapat digunakan untuk menganotasi aturan dan melakukan 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+ browser.* sejak Chrome 148

Cocok jika bagian host URL adalah alamat IP dan terdapat dalam 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'. Ini cocok dengan 'www.foobar.com' dan 'foo.com', karena titik implisit ditambahkan di awal nama host. Demikian pula, hostContains dapat digunakan untuk mencocokkan dengan akhiran komponen ('foo.') dan untuk mencocokkan persis dengan komponen ('.foo.'). Pencocokan akhiran 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

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

Cocok 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

(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

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.
skema

string[] opsional

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

string opsional

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

string opsional

Cocok 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

Cocok 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

Cocok 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

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

browser.events Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Deskripsi

Konsep dan penggunaan

Pengendali Peristiwa Deklaratif

Aturan

Objek peristiwa

Menambahkan aturan

Menghapus aturan

Mengambil aturan

Performa

Peristiwa yang difilter

Jenis

Event

Properti

Rule

Properti

UrlFilter

Properti

browser.events