chrome.events

คำอธิบาย

แนวคิดและการใช้งาน

Event เป็นออบเจ็กต์ที่ให้คุณรับการแจ้งเตือนเมื่อมีสิ่งที่น่าสนใจเกิดขึ้น นี่คือ ตัวอย่างของการใช้เหตุการณ์ chrome.alarms.onAlarm เพื่อรับการแจ้งเตือนเมื่อการปลุกไปแล้ว

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

ตามตัวอย่างนี้ คุณลงทะเบียนรับการแจ้งเตือนโดยใช้ addListener() อาร์กิวเมนต์ของ addListener() จะเป็นฟังก์ชันที่คุณกำหนดให้จัดการเหตุการณ์เสมอ แต่จะใช้พารามิเตอร์ จะขึ้นอยู่กับเหตุการณ์ที่คุณกำลังจัดการ กำลังตรวจสอบเอกสารสำหรับ alarms.onAlarm คุณจะเห็นว่าฟังก์ชันมีพารามิเตอร์เดียว คือออบเจ็กต์ alarms.Alarm ที่มีรายละเอียด เกี่ยวกับการตั้งปลุกที่ผ่านไป

ตัวอย่าง API ที่ใช้เหตุการณ์ ได้แก่ การปลุก, i18n, identity, runtime Chrome ส่วนใหญ่ API

เครื่องจัดการกิจกรรมการประกาศ

เครื่องจัดการเหตุการณ์แบบประกาศเป็นวิธีกำหนดกฎที่ประกอบด้วยเงื่อนไขการประกาศ และการทำงาน เงื่อนไขจะได้รับการประเมินในเบราว์เซอร์ ไม่ใช่เครื่องมือ JavaScript ซึ่งลด เวลาในการตอบสนองไป-กลับ และทำให้มีประสิทธิภาพสูงมาก

ตัวอย่างเช่น มีการใช้เครื่องจัดการเหตุการณ์แบบประกาศ The Declarative Content API หน้านี้อธิบายแนวคิดสําคัญของเหตุการณ์ที่มีการประกาศทั้งหมด เครื่องจัดการ

กฎ

กฎที่ง่ายที่สุดประกอบด้วยเงื่อนไขอย่างน้อย 1 ข้อและการกระทำอย่างน้อย 1 รายการดังนี้

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

หากเป็นไปตามเงื่อนไขข้อใดข้อหนึ่ง ระบบจะดำเนินการทั้งหมด

นอกจากเงื่อนไขและการดำเนินการแล้ว คุณสามารถกำหนดตัวระบุให้กับกฎแต่ละข้อได้ ซึ่งจะช่วยลดความซับซ้อน การยกเลิกการลงทะเบียนกฎที่ลงทะเบียนไว้ก่อนหน้านี้ และลำดับความสำคัญเพื่อกำหนดลำดับความสำคัญระหว่างกฎต่างๆ ระบบจะพิจารณาลำดับความสำคัญก็ต่อเมื่อกฎขัดแย้งกันหรือต้องดำเนินการใน คำสั่งซื้อ การดำเนินการจะดำเนินการตามลำดับลำดับความสำคัญของกฎจากมากไปหาน้อย

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

ออบเจ็กต์เหตุการณ์

ออบเจ็กต์เหตุการณ์อาจรองรับกฎ ออบเจ็กต์เหตุการณ์เหล่านี้จะไม่เรียกใช้ฟังก์ชัน Callback เมื่อ เหตุการณ์จะเกิดขึ้น แต่ทดสอบว่ากฎที่ลงทะเบียนไว้มีเงื่อนไขที่บรรลุอย่างน้อย 1 รายการหรือไม่ และดำเนินการ การดำเนินการที่เชื่อมโยงกับกฎนี้ ออบเจ็กต์เหตุการณ์ที่รองรับ API การประกาศมี 3 รายการ เมธอดที่เกี่ยวข้อง: events.Event.addRules(), events.Event.removeRules() และ events.Event.getRules()

เพิ่มกฎ

หากต้องการเพิ่มกฎ ให้เรียกใช้ฟังก์ชัน addRules() ของออบเจ็กต์เหตุการณ์ ใช้อาร์เรย์ของอินสแตนซ์กฎ เป็นพารามิเตอร์แรกและฟังก์ชัน Callback ที่จะเรียกใช้เมื่อเสร็จสมบูรณ์

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

หากแทรกกฎสำเร็จ พารามิเตอร์ details จะมีอาร์เรย์ของกฎที่แทรก ปรากฏในลำดับเดียวกับใน rule_list ที่ส่งผ่าน ซึ่งพารามิเตอร์ที่ไม่บังคับ id และ มีการเติม priority ด้วยค่าที่สร้างขึ้น เช่น หากมีกฎที่ไม่ถูกต้องเนื่องจากมี เงื่อนไขหรือการดำเนินการที่ไม่ถูกต้อง ไม่มีการเพิ่มกฎใดๆ และตัวแปร runtime.lastError จะถูกตั้งค่าเมื่อมีการเรียกใช้ฟังก์ชัน Callback แต่ละกฎใน rule_list จะต้องประกอบด้วย ที่ไม่ได้ใช้อยู่แล้วโดยกฎอื่น หรือตัวระบุที่ว่างเปล่า

นำกฎออก

หากต้องการนำกฎออก ให้เรียกใช้ฟังก์ชัน removeRules() ยอมรับอาร์เรย์ของตัวระบุกฎที่ไม่บังคับ เป็นพารามิเตอร์แรกและมีฟังก์ชัน Callback เป็นพารามิเตอร์ที่ 2

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

หาก rule_ids เป็นอาร์เรย์ของตัวระบุ กฎทั้งหมดที่มีตัวระบุอยู่ในอาร์เรย์ ลบแล้ว หาก rule_ids แสดงตัวระบุซึ่งไม่ทราบที่มา ระบบจะละเว้นตัวระบุนี้โดยไม่มีการแจ้งเตือน ถ้า rule_ids คือ undefined ระบบจะนำกฎที่ลงทะเบียนทั้งหมดของส่วนขยายนี้ออก callback() จะถูกเรียกเมื่อกฎถูกนำออก

เรียกดูกฎ

หากต้องการเรียกดูรายการกฎที่ลงทะเบียน ให้เรียกใช้ฟังก์ชัน getRules() ยอมรับ อาร์เรย์ที่ไม่บังคับของตัวระบุกฎซึ่งมีความหมายเหมือนกับ removeRules() และฟังก์ชัน Callback

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

พารามิเตอร์ details ที่ส่งไปยังฟังก์ชัน callback() หมายถึงอาร์เรย์ของกฎ ซึ่งรวมถึง พารามิเตอร์ที่ไม่บังคับที่เติมโฆษณา

ประสิทธิภาพ

เพื่อให้ได้รับประสิทธิภาพสูงสุด คุณควรคํานึงถึงหลักเกณฑ์ต่อไปนี้

ลงทะเบียนและยกเลิกการลงทะเบียนกฎหลายรายการพร้อมกัน หลังจากการลงทะเบียนหรือยกเลิกการลงทะเบียนแต่ละครั้ง Chrome จะต้อง อัปเดตโครงสร้างข้อมูลภายในของ การอัปเดตนี้เป็นการดำเนินการที่มีค่าใช้จ่ายสูง

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

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

ต้องการการจับคู่สตริงย่อยแทนนิพจน์ทั่วไปใน events.UrlFilter การจับคู่ตามสตริงย่อยนั้นรวดเร็วมาก

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

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

หากมีกฎหลายข้อที่มีการดำเนินการเหมือนกัน ให้รวมกฎเหล่านั้นเป็นกฎเดียว กฎจะทริกเกอร์การดำเนินการของกฎเหล่านั้นทันทีที่เป็นไปตามเงื่อนไขเดียว ซึ่งจะช่วยเร่ง การจับคู่และลดปริมาณการใช้หน่วยความจำสำหรับชุดการดำเนินการที่ซ้ำกัน

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

เหตุการณ์ที่กรอง

เหตุการณ์ที่กรองแล้วคือกลไกที่ให้ผู้ฟังระบุชุดย่อยของเหตุการณ์ที่ตนอยู่ สนใจ ระบบจะไม่เรียกใช้ Listener ที่ใช้ตัวกรองสำหรับเหตุการณ์ที่ไม่ผ่าน ซึ่งทำให้โค้ดการฟังสื่อสารชัดเจนและมีประสิทธิภาพมากขึ้น ความต้องการของโปรแกรมทำงานของบริการ ไม่ต้องตื่นมารับเหตุการณ์ต่างๆ ที่ไม่สนใจ

เหตุการณ์ที่กรองมีไว้เพื่ออนุญาตให้เปลี่ยนจากโค้ดการกรองด้วยตนเองได้

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

เหตุการณ์รองรับตัวกรองเฉพาะที่มีความสำคัญต่อเหตุการณ์นั้น รายการตัวกรองที่เหตุการณ์ รองรับจะแสดงอยู่ในเอกสารสำหรับเหตุการณ์นั้นใน "ตัวกรอง"

เมื่อจับคู่ URL (ตามตัวอย่างด้านบน) ตัวกรองเหตุการณ์จะรองรับการจับคู่ URL เดียวกัน ความสามารถที่แสดงได้ด้วย events.UrlFilter ยกเว้นการจับคู่รูปแบบและพอร์ต