คำอธิบาย
เนมสเปซ chrome.events
มีประเภททั่วไปที่ใช้โดย API ที่ส่งเหตุการณ์เพื่อแจ้งให้คุณทราบเมื่อมีสิ่งน่าสนใจเกิดขึ้น
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, รันไทม์ API ของ Chrome ส่วนใหญ่ใช้
เครื่องจัดการเหตุการณ์เชิงประกาศ
ตัวแฮนเดิลเหตุการณ์แบบประกาศระบุวิธีการกำหนดกฎที่ประกอบด้วยเงื่อนไขและการดำเนินการแบบประกาศ เงื่อนไขจะได้รับการประเมินในเบราว์เซอร์ไม่ใช่จากเครื่องมือ JavaScript ซึ่งจะลดเวลาในการตอบสนองและช่วยให้ประสิทธิภาพการทำงานสูงมาก
มีการใช้ตัวแฮนเดิลเหตุการณ์เชิงประกาศ เช่น ใน API คำขอเว็บเชิงประกาศและ Delarative 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 */ ]
};
ออบเจ็กต์เหตุการณ์
ออบเจ็กต์เหตุการณ์อาจรองรับกฎ ออบเจ็กต์เหตุการณ์เหล่านี้จะไม่เรียกใช้ฟังก์ชันเรียกกลับเมื่อมีเหตุการณ์เกิดขึ้น แต่ทดสอบว่ากฎที่บันทึกไว้มีคุณสมบัติตรงตามเงื่อนไขอย่างน้อย 1 รายการหรือไม่ และดำเนินการที่เกี่ยวข้องกับกฎนี้ ออบเจ็กต์เหตุการณ์ที่รองรับ Declarative API มีวิธีที่เกี่ยวข้อง 3 วิธี ได้แก่ events.Event.addRules
, events.Event.removeRules
และ events.Event.getRules
การเพิ่มกฎ
หากต้องการเพิ่มกฎ ให้เรียกใช้ฟังก์ชัน addRules()
ของออบเจ็กต์เหตุการณ์ ซึ่งจะใช้อาร์เรย์ของอินสแตนซ์กฎ
เป็นพารามิเตอร์แรกและใช้ฟังก์ชันเรียกกลับที่จะเรียกใช้เมื่อเสร็จสิ้น
var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});
หากแทรกกฎสำเร็จ พารามิเตอร์ details
จะมีอาร์เรย์ของกฎที่แทรกไว้ซึ่งปรากฏในลำดับเดียวกันกับ rule_list
ที่ส่ง ซึ่งเติมพารามิเตอร์ที่ไม่บังคับ id
และ priority
ด้วยค่าที่สร้างขึ้น หากกฎใดไม่ถูกต้อง เช่น เพราะมีเงื่อนไขหรือการดำเนินการที่ไม่ถูกต้อง จะไม่มีการเพิ่มกฎใดๆ และมีการตั้งค่าตัวแปร runtime.lastError เมื่อมีการเรียกใช้ฟังก์ชันเรียกกลับ แต่ละกฎใน rule_list
ต้องมีตัวระบุที่ไม่ซ้ำกันซึ่งกฎอื่นไม่ได้ใช้อยู่ในขณะนี้หรือตัวระบุที่ว่างเปล่า
การนำกฎออก
หากต้องการนำกฎออกจะเรียกฟังก์ชัน removeRules()
ยอมรับอาร์เรย์ที่ไม่บังคับของตัวระบุกฎเป็นพารามิเตอร์แรก และใช้ฟังก์ชันเรียกกลับเป็นพารามิเตอร์ที่ 2
var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});
หาก rule_ids
เป็นอาร์เรย์ของตัวระบุ ระบบจะนำกฎทั้งหมดที่มีตัวระบุอยู่ในอาร์เรย์ออก หาก rule_ids
แสดงตัวระบุที่ไม่ทราบ ระบบจะไม่สนใจตัวระบุนี้โดยไม่มีการแจ้งเตือน หาก rule_ids
คือ undefined
ระบบจะนำกฎที่จดทะเบียนทั้งหมดของส่วนขยายนี้ออก ระบบจะเรียกใช้ฟังก์ชัน callback()
เมื่อนำกฎออก
กำลังเรียกข้อมูลกฎ
หากต้องการเรียกรายการกฎที่ลงทะเบียนไว้ในปัจจุบัน ให้เรียกใช้ฟังก์ชัน getRules()
โดยจะยอมรับอาร์เรย์ที่ไม่บังคับของตัวระบุกฎที่มีความหมายเดียวกันกับ removeRules
และฟังก์ชันเรียกกลับ
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 ที่ใช้ตัวกรองสำหรับเหตุการณ์ที่ไม่ผ่านตัวกรอง ซึ่งจะทำให้โค้ดการฟังมีความชัดเจนและมีประสิทธิภาพมากขึ้น 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
ยกเว้นรูปแบบและการจับคู่พอร์ต
ประเภท
Event
ออบเจ็กต์ที่อนุญาตให้เพิ่มและนำ Listener สำหรับเหตุการณ์ Chrome ออก
พร็อพเพอร์ตี้
-
addListener
void
ลงทะเบียน Listener เหตุการณ์ callback ไปยังเหตุการณ์
ฟังก์ชัน
addListener
มีลักษณะดังนี้(callback: H) => {...}
-
Callback
ฮิต
เรียกใช้เมื่อเกิดเหตุการณ์ พารามิเตอร์ของฟังก์ชันนี้ขึ้นอยู่กับประเภทของเหตุการณ์
-
-
addRules
void
ลงทะเบียนกฎเพื่อจัดการเหตุการณ์
ฟังก์ชัน
addRules
มีลักษณะดังนี้(rules: Rule<anyany>[], callback?: function) => {...}
-
getRules
void
แสดงผลกฎที่ลงทะเบียนไว้ในปัจจุบัน
ฟังก์ชัน
getRules
มีลักษณะดังนี้(ruleIdentifiers?: string[], callback: function) => {...}
-
hasListener
void
ฟังก์ชัน
hasListener
มีลักษณะดังนี้(callback: H) => {...}
-
Callback
ฮิต
ผู้ฟังที่มีสถานะการลงทะเบียนจะถูกทดสอบ
-
returns
boolean
เป็นจริงหากมีการลงทะเบียน callback สำหรับกิจกรรม
-
-
hasListeners
void
ฟังก์ชัน
hasListeners
มีลักษณะดังนี้() => {...}
-
returns
boolean
เป็นจริงหาก Listener เหตุการณ์ลงทะเบียนไว้กับเหตุการณ์
-
-
removeListener
void
ยกเลิกการลงทะเบียน callback ของ Listener เหตุการณ์จากเหตุการณ์
ฟังก์ชัน
removeListener
มีลักษณะดังนี้(callback: H) => {...}
-
Callback
ฮิต
ผู้ฟังที่จะไม่ได้รับการลงทะเบียน
-
-
removeRules
void
ยกเลิกการลงทะเบียนกฎที่ลงทะเบียนไว้ในปัจจุบัน
ฟังก์ชัน
removeRules
มีลักษณะดังนี้(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] ไม่บังคับ
หากส่งต่ออาร์เรย์ จะไม่มีการลงทะเบียนกฎที่มีตัวระบุอยู่ในอาร์เรย์นี้เท่านั้น
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
-
Rule
คําอธิบายกฎการประกาศสําหรับการจัดการเหตุการณ์
พร็อพเพอร์ตี้
-
การดำเนินการ
ทั้งหมด[]
รายการการดำเนินการที่จะทริกเกอร์หากเป็นไปตามเงื่อนไขข้อใดข้อหนึ่ง
-
conditions
ทั้งหมด[]
รายการเงื่อนไขที่ทริกเกอร์การดำเนินการได้
-
id
string ไม่บังคับ
ตัวระบุที่ไม่บังคับซึ่งอนุญาตให้อ้างอิงกฎนี้
-
ลำดับความสำคัญ
ตัวเลข ไม่บังคับ
ลำดับความสำคัญที่ไม่บังคับของกฎนี้ ค่าเริ่มต้นคือ 100
-
แท็ก
string[] ไม่บังคับ
คุณสามารถใช้แท็กเพื่อใส่คำอธิบายประกอบกฎและดำเนินการกับชุดกฎได้
UrlFilter
กรอง URL ตามเกณฑ์ต่างๆ ดูการกรองเหตุการณ์ เกณฑ์ทั้งหมดคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
พร็อพเพอร์ตี้
-
cidrBlocks
string[] ไม่บังคับ
Chrome 123 ขึ้นไปจับคู่หากส่วนโฮสต์ของ URL เป็นที่อยู่ IP และอยู่ในบล็อก CIDR ใดก็ตามที่ระบุในอาร์เรย์
-
hostContains
string ไม่บังคับ
จับคู่หากชื่อโฮสต์ของ URL มีสตริงที่ระบุ หากต้องการทดสอบว่าคอมโพเนนต์ชื่อโฮสต์มีคำนำหน้า "foo" หรือไม่ ให้ใช้ hostContains: '.foo' รายการนี้ตรงกับ "www.foobar.com" และ "foo.com" เนื่องจากมีการเพิ่มจุดโดยนัยที่ตอนต้นของชื่อโฮสต์ ในทำนองเดียวกัน hostContains สามารถใช้เพื่อจับคู่กับส่วนต่อท้ายคอมโพเนนต์ ('foo.') และเพื่อจับคู่กับคอมโพเนนต์ (".foo.") ทุกประการได้ การจับคู่คำต่อท้ายและการจับคู่ที่ตรงกันทั้งหมดสำหรับคอมโพเนนต์สุดท้ายต้องทำแยกต่างหากโดยใช้ hostSuffix เนื่องจากไม่มีการเพิ่มจุดโดยนัยที่ส่วนท้ายของชื่อโฮสต์
-
hostEquals
string ไม่บังคับ
จับคู่หากชื่อโฮสต์ของ URL เท่ากับสตริงที่ระบุ
-
hostPrefix
string ไม่บังคับ
จับคู่หากชื่อโฮสต์ของ URL ขึ้นต้นด้วยสตริงที่ระบุ
-
hostSuffix
string ไม่บังคับ
จับคู่หากชื่อโฮสต์ของ URL ลงท้ายด้วยสตริงที่ระบุ
-
originAndPathMatches
string ไม่บังคับ
จับคู่หาก URL ที่ไม่มีกลุ่มข้อความค้นหาและตัวระบุส่วนย่อยตรงกับนิพจน์ทั่วไปที่ระบุ หมายเลขพอร์ตจะถูกตัดออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น นิพจน์ทั่วไปใช้ไวยากรณ์ RE2
-
pathContains
string ไม่บังคับ
จับคู่หากส่วนเส้นทางของ URL มีสตริงที่ระบุ
-
pathEquals
string ไม่บังคับ
จับคู่หากส่วนเส้นทางของ URL เท่ากับสตริงที่ระบุ
-
pathPrefix
string ไม่บังคับ
จับคู่หากส่วนเส้นทางของ URL เริ่มต้นด้วยสตริงที่ระบุ
-
pathSuffix
string ไม่บังคับ
จับคู่หากส่วนเส้นทางของ URL ลงท้ายด้วยสตริงที่ระบุ
-
ports
(number | number[])[] ไม่บังคับ
จับคู่หากพอร์ตของ URL อยู่ในรายการพอร์ตที่ระบุ ตัวอย่างเช่น
[80, 443, [1000, 1200]]
จะจับคู่คำขอทั้งหมดในพอร์ต 80, 443 และในช่วง 1000-1200 -
queryContains
string ไม่บังคับ
จับคู่หากกลุ่มการค้นหาของ URL มีสตริงที่ระบุ
-
queryEquals
string ไม่บังคับ
จับคู่หากกลุ่มการค้นหาของ URL เท่ากับสตริงที่ระบุ
-
queryPrefix
string ไม่บังคับ
จับคู่หากกลุ่มการค้นหาของ URL ขึ้นต้นด้วยสตริงที่ระบุ
-
querySuffix
string ไม่บังคับ
จับคู่หากกลุ่มการค้นหาของ URL ลงท้ายด้วยสตริงที่ระบุ
-
schemes
string[] ไม่บังคับ
จับคู่หากสคีมของ URL เท่ากับรูปแบบที่ระบุไว้ในอาร์เรย์
-
urlContains
string ไม่บังคับ
จับคู่หาก URL (ไม่มีตัวระบุส่วนย่อย) มีสตริงที่ระบุ หมายเลขพอร์ตจะถูกตัดออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น
-
urlEquals
string ไม่บังคับ
จับคู่หาก URL (ไม่มีตัวระบุส่วนย่อย) เท่ากับสตริงที่ระบุ หมายเลขพอร์ตจะถูกตัดออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น
-
urlMatches
string ไม่บังคับ
จับคู่หาก URL (ไม่มีตัวระบุส่วนย่อย) ตรงกับนิพจน์ทั่วไปที่ระบุ หมายเลขพอร์ตจะถูกตัดออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น นิพจน์ทั่วไปใช้ไวยากรณ์ RE2
-
urlPrefix
string ไม่บังคับ
จับคู่หาก URL (ไม่มีตัวระบุส่วนย่อย) เริ่มต้นด้วยสตริงที่ระบุ หมายเลขพอร์ตจะถูกตัดออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น
-
urlSuffix
string ไม่บังคับ
จับคู่หาก URL (ไม่มีตัวระบุส่วนย่อย) ลงท้ายด้วยสตริงที่ระบุ หมายเลขพอร์ตจะถูกตัดออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น