chrome.events

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

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 ที่ใช้เหตุการณ์: alarms, i18n, identity, runtime API ของ Chrome ส่วนใหญ่ทำได้

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

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

ตัวแฮนเดิลเหตุการณ์แบบประกาศใช้ใน Declarative Web Request API และ 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 รายการหรือไม่ และจะดำเนินการที่เชื่อมโยงกับกฎนี้ ออบเจ็กต์เหตุการณ์ที่รองรับ Declarative 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 ระบุชุดย่อยของเหตุการณ์ที่ตนสนใจได้ ระบบจะไม่เรียกใช้ Listener ที่ใช้ตัวกรองสำหรับเหตุการณ์ที่ไม่ผ่านตัวกรอง ซึ่งจะทำให้โค้ดการฟังประกาศและมีประสิทธิภาพมากขึ้น Service Worker ไม่จำเป็นต้องตื่นขึ้นมาเพื่อจัดการเหตุการณ์ที่ไม่เกี่ยวข้อง

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

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 ยกเว้นการจับคู่รูปแบบและพอร์ต