browser.events

คำอธิบาย

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

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

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

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

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

เครื่องจัดการเหตุการณ์แบบประกาศ

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

ตัวแฮนเดิลเหตุการณ์แบบประกาศจะใช้ใน 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 รายการหรือไม่ และจะดำเนินการที่เชื่อมโยงกับกฎนี้ ออบเจ็กต์เหตุการณ์ที่รองรับ Declarative 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 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

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

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

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

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

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

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

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

เหตุการณ์ที่กรองแล้ว

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

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

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

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

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