browser.events

คำอธิบาย

เนมสเปซ chrome.events มีประเภททั่วไปที่ API ใช้ในการส่งเหตุการณ์เพื่อแจ้งให้คุณทราบเมื่อมีสิ่งที่น่าสนใจเกิดขึ้น

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

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 Chrome API ส่วนใหญ่จะใช้ได้

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

เครื่องจัดการเหตุการณ์แบบประกาศมีวิธีในการกำหนดกฎที่ประกอบด้วยเงื่อนไขและการดำเนินการแบบประกาศ ระบบจะประเมินเงื่อนไขในเบราว์เซอร์แทนเครื่องมือ 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 ข้อหรือไม่ และจะดำเนินการที่เชื่อมโยงกับกฎนี้ ออบเจ็กต์เหตุการณ์ที่รองรับ 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 ต้องมีตัวระบุที่ไม่ซ้ำกันซึ่งกฎอื่นยังไม่ได้ใช้ หรือตัวระบุที่ว่างเปล่า

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

นำกฎออก

หากต้องการนำกฎออก ให้เรียกใช้ฟังก์ชัน 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 ยกเว้นการจับคู่รูปแบบและพอร์ต

ประเภท

Event

ออบเจ็กต์ที่อนุญาตให้เพิ่มและนำ Listener ออกสำหรับเหตุการณ์ Chrome

พร็อพเพอร์ตี้

• addListener

  void

  ลงทะเบียน Callback ของ Listener เหตุการณ์กับเหตุการณ์

  ฟังก์ชัน addListener จะมีลักษณะดังนี้

  (callback: H) => {...}

  • callback

    H

    เรียกใช้เมื่อเกิดเหตุการณ์ พารามิเตอร์ของฟังก์ชันนี้ขึ้นอยู่กับประเภทของเหตุการณ์

• addRules

  void

  ลงทะเบียนกฎเพื่อจัดการเหตุการณ์

  ฟังก์ชัน addRules จะมีลักษณะดังนี้

  (rules: Rule<anyany>[], callback?: function) => {...}

  • กฎ

    Rule<anyany>[]

    กฎที่ต้องลงทะเบียน ซึ่งจะไม่แทนที่กฎที่ลงทะเบียนไว้ก่อนหน้านี้

  • callback

    function ไม่บังคับ

    พารามิเตอร์ callback จะมีลักษณะดังนี้

    (rules: Rule<anyany>[]) => void

    • กฎ

      Rule<anyany>[]

      กฎที่ลงทะเบียนไว้ พารามิเตอร์ที่ไม่บังคับจะมีการป้อนค่าไว้

• getRules

  void

  แสดงผลกฎที่ลงทะเบียนไว้ในปัจจุบัน

  ฟังก์ชัน getRules จะมีลักษณะดังนี้

  (ruleIdentifiers?: string[], callback: function) => {...}

  • ruleIdentifiers

    string[] ไม่บังคับ

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

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback จะมีลักษณะดังนี้

    (rules: Rule<anyany>[]) => void

    • กฎ

      Rule<anyany>[]

      กฎที่ลงทะเบียนไว้ พารามิเตอร์ที่ไม่บังคับจะมีการป้อนค่าไว้

• hasListener

  void

  ฟังก์ชัน hasListener จะมีลักษณะดังนี้

  (callback: H) => {...}

  • callback

    H

    Listener ที่จะทดสอบสถานะการลงทะเบียน

  • returns

    บูลีน

    True หากมีการลงทะเบียน callback กับเหตุการณ์

• hasListeners

  void

  ฟังก์ชัน hasListeners จะมีลักษณะดังนี้

  () => {...}

  • returns

    บูลีน

    True หากมีการลงทะเบียน Listener เหตุการณ์กับเหตุการณ์

• removeListener

  void

  ยกเลิกการลงทะเบียน Callback ของ Listener เหตุการณ์จากเหตุการณ์

  ฟังก์ชัน removeListener จะมีลักษณะดังนี้

  (callback: H) => {...}

  • callback

    H

    Listener ที่จะยกเลิกการลงทะเบียน

• removeRules

  void

  ยกเลิกการลงทะเบียนกฎที่ลงทะเบียนไว้ในปัจจุบัน

  ฟังก์ชัน removeRules จะมีลักษณะดังนี้

  (ruleIdentifiers?: string[], callback?: function) => {...}

  • ruleIdentifiers

    string[] ไม่บังคับ

    หากมีการส่งอาร์เรย์ ระบบจะยกเลิกการลงทะเบียนเฉพาะกฎที่มีตัวระบุที่อยู่ในอาร์เรย์นี้

  • callback

    function ไม่บังคับ

    พารามิเตอร์ callback จะมีลักษณะดังนี้

    () => void

Rule

คำอธิบายกฎที่ประกาศสำหรับการจัดการเหตุการณ์

พร็อพเพอร์ตี้

• การดำเนินการ

  any[]

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

• ภาวะทางการแพทย์

  any[]

  รายการเงื่อนไขที่ทริกเกอร์การดำเนินการได้

• id

  สตริง ไม่บังคับ

  ตัวระบุที่ไม่บังคับซึ่งช่วยให้อ้างอิงกฎนี้ได้

• ลำดับความสำคัญ

  number ไม่บังคับ

  ลำดับความสำคัญที่ไม่บังคับของกฎนี้ ค่าเริ่มต้นคือ 100

• แท็ก

  string[] ไม่บังคับ

  คุณสามารถใช้แท็กเพื่อใส่คำอธิบายประกอบกฎและดำเนินการกับชุดกฎได้

UrlFilter

กรอง URL ตามเกณฑ์ต่างๆ ดูการกรองเหตุการณ์ เกณฑ์ทั้งหมดจะคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่

พร็อพเพอร์ตี้

• cidrBlocks

  string[] ไม่บังคับ

  Chrome 123 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  ตรงกันหากส่วนโฮสต์ของ URL เป็นที่อยู่ IP และอยู่ในบล็อก CIDR ใดๆ ที่ระบุไว้ในอาร์เรย์

• hostContains

  สตริง ไม่บังคับ

  ตรงกันหากชื่อโฮสต์ของ URL มีสตริงที่ระบุ หากต้องการทดสอบว่าคอมโพเนนต์ชื่อโฮสต์มีคำนำหน้า "foo" หรือไม่ ให้ใช้ hostContains: ".foo" ซึ่งจะตรงกับ "www.foobar.com" และ "foo.com" เนื่องจากมีการเพิ่มจุดโดยนัยที่จุดเริ่มต้นของชื่อโฮสต์ ในทำนองเดียวกัน คุณสามารถใช้ hostContains เพื่อจับคู่กับส่วนต่อท้ายคอมโพเนนต์ ("foo.") และจับคู่กับคอมโพเนนต์แบบตรงทั้งหมด (".foo.") ได้ การจับคู่คำต่อท้ายและการทำงานแบบตรงทั้งหมดสำหรับคอมโพเนนต์สุดท้ายต้องทำแยกกันโดยใช้ hostSuffix เนื่องจากไม่มีการเพิ่มจุดโดยนัยที่ส่วนท้ายของชื่อโฮสต์

• hostEquals

  สตริง ไม่บังคับ

  ตรงกันหากชื่อโฮสต์ของ URL เท่ากับสตริงที่ระบุ

• hostPrefix

  สตริง ไม่บังคับ

  จับคู่หากชื่อโฮสต์ของ URL ขึ้นต้นด้วยสตริงที่ระบุ

• hostSuffix

  สตริง ไม่บังคับ

  ตรงกันหากชื่อโฮสต์ของ URL ลงท้ายด้วยสตริงที่ระบุ

• originAndPathMatches

  สตริง ไม่บังคับ

  ตรงกันหาก URL ที่ไม่มีกลุ่มการค้นหาและตัวระบุ Fragment ตรงกับนิพจน์ทั่วไปที่ระบุ ระบบจะตัดหมายเลขพอร์ตออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น นิพจน์ทั่วไปจะใช้ไวยากรณ์ RE2

• pathContains

  สตริง ไม่บังคับ

  ตรงกันหากกลุ่มเส้นทางของ URL มีสตริงที่ระบุ

• pathEquals

  สตริง ไม่บังคับ

  ตรงกันหากกลุ่มเส้นทางของ URL เท่ากับสตริงที่ระบุ

• pathPrefix

  สตริง ไม่บังคับ

  จับคู่หากกลุ่มเส้นทางของ URL ขึ้นต้นด้วยสตริงที่ระบุ

• pathSuffix

  สตริง ไม่บังคับ

  จับคู่หากกลุ่มเส้นทางของ URL ลงท้ายด้วยสตริงที่ระบุ

• ports

  (number | number[])[] optional

  ตรงกันหากพอร์ตของ URL อยู่ในรายการพอร์ตที่ระบุ เช่น [80, 443, [1000, 1200]] จะจับคู่คำขอทั้งหมดในพอร์ต 80, 443 และในช่วง 1000-1200

• queryContains

  สตริง ไม่บังคับ

  ตรงกันหากกลุ่มการค้นหาของ URL มีสตริงที่ระบุ

• queryEquals

  สตริง ไม่บังคับ

  ตรงกันหากกลุ่มการค้นหาของ URL เท่ากับสตริงที่ระบุ

• queryPrefix

  สตริง ไม่บังคับ

  ตรงกันหากกลุ่มการค้นหาของ URL ขึ้นต้นด้วยสตริงที่ระบุ

• querySuffix

  สตริง ไม่บังคับ

  ตรงกันหากกลุ่มการค้นหาของ URL ลงท้ายด้วยสตริงที่ระบุ

• รูปแบบ

  string[] ไม่บังคับ

  จับคู่หากรูปแบบของ URL เท่ากับรูปแบบใดๆ ที่ระบุไว้ในอาร์เรย์

• urlContains

  สตริง ไม่บังคับ

  ตรงกันหาก URL (ไม่มีตัวระบุส่วนย่อย) มีสตริงที่ระบุ ระบบจะตัดหมายเลขพอร์ตออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น

• urlEquals

  สตริง ไม่บังคับ

  จับคู่หาก URL (ไม่มีตัวระบุ Fragment) เท่ากับสตริงที่ระบุ ระบบจะตัดหมายเลขพอร์ตออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น

• urlMatches

  สตริง ไม่บังคับ

  ตรงกันหาก URL (ไม่มีตัวระบุ Fragment) ตรงกับนิพจน์ทั่วไปที่ระบุ ระบบจะตัดหมายเลขพอร์ตออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น นิพจน์ทั่วไปจะใช้ไวยากรณ์ RE2

• urlPrefix

  สตริง ไม่บังคับ

  จับคู่หาก URL (ไม่มีตัวระบุ Fragment) ขึ้นต้นด้วยสตริงที่ระบุ ระบบจะตัดหมายเลขพอร์ตออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น

• urlSuffix

  สตริง ไม่บังคับ

  ตรงกันหาก URL (ไม่มีตัวระบุ Fragment) ลงท้ายด้วยสตริงที่ระบุ ระบบจะตัดหมายเลขพอร์ตออกจาก URL หากตรงกับหมายเลขพอร์ตเริ่มต้น