chrome.events

Deskripsi

Konsep dan penggunaan

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((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 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:

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

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

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (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 belum digunakan oleh aturan lain atau pengenal kosong.

Hapus aturan

Untuk menghapus aturan, panggil fungsi removeRules(). Metode ini menerima array opsional ID aturan 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 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 terdaftar, panggil fungsi getRules(). Properti ini menerima array opsional ID aturan dengan semantik yang sama dengan 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 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.

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

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

Pilih 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 dengan 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.

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