chrome.events

คำอธิบาย

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

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
});

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

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

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

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

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

กฎ

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

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

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

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

var 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 ที่จะเรียกใช้เมื่อเสร็จสมบูรณ์

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

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

การนำกฎออก

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

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

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

กำลังเรียกกฎ

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

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});

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

ประสิทธิภาพ

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

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

แทนที่จะเป็น:

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

ต้องการ:

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

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

แทนที่จะเป็น:

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

ต้องการ:

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

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

แทนที่จะเป็น:

var condition1 = new chrome.declarativeWebRequest.RequestMatcher({
    url: { hostSuffix: 'example.com' } });
var condition2 = new chrome.declarativeWebRequest.RequestMatcher({
    url: { hostSuffix: 'foobar.com' } });
var rule1 = { conditions: [condition1],
              actions: [new chrome.declarativeWebRequest.CancelRequest()]};
var rule2 = { conditions: [condition2],
              actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

ต้องการ:

  var rule = { conditions: [condition1, condition2],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]};
  chrome.declarativeWebRequest.onRequest.addRules([rule]);

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

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

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

chrome.webNavigation.onCommitted.addListener(function(e) {
  if (hasHostSuffix(e.url, 'google.com') ||
      hasHostSuffix(e.url, 'google.com.au')) {
    // ...
  }
});

มาพูดถึงกัน:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

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