chrome.events

คำอธิบาย

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

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

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

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

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

ตัวอย่าง API ที่ใช้เหตุการณ์ เช่น การปลุก, i18n, identity, รันไทม์ 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 */ ]
};

ออบเจ็กต์เหตุการณ์

ออบเจ็กต์เหตุการณ์อาจรองรับกฎ ออบเจ็กต์เหตุการณ์เหล่านี้จะไม่เรียกใช้ฟังก์ชันเรียกกลับเมื่อมีเหตุการณ์เกิดขึ้น แต่ทดสอบว่ากฎที่บันทึกไว้มีคุณสมบัติตรงตามเงื่อนไขอย่างน้อย 1 รายการหรือไม่ และดำเนินการที่เกี่ยวข้องกับกฎนี้ ออบเจ็กต์เหตุการณ์ที่รองรับ Declarative API มีวิธีที่เกี่ยวข้อง 3 วิธี ได้แก่ events.Event.addRules(), events.Event.removeRules() และ events.Event.getRules()

เพิ่มกฎ

หากต้องการเพิ่มกฎ ให้เรียกใช้ฟังก์ชัน addRules() ของออบเจ็กต์เหตุการณ์ ซึ่งจะใช้อาร์เรย์ของอินสแตนซ์กฎ เป็นพารามิเตอร์แรกและใช้ฟังก์ชันเรียกกลับที่จะเรียกใช้เมื่อเสร็จสิ้น

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

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

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

นำกฎออก

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

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

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

เรียกข้อมูลกฎ

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

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

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

การแสดง

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

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

แทนที่จะใช้

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

ต้องการ

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

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

แทนที่จะใช้

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

ต้องการ

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

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

แทนที่จะใช้

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

ต้องการ

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

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

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

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

แทนที่จะใช้

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

ต้องการ

chrome.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {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)=> {...}

  • กฎ

    กฎ<anyany>[]

    กฎสำหรับการลงทะเบียน ซึ่งกฎเหล่านี้ไม่ได้แทนที่กฎที่ลงทะเบียนไว้ก่อนหน้านี้

  • Callback

    ฟังก์ชัน ไม่บังคับ

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

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

    • กฎ

      กฎ<anyany>[]

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

• getRules

  void

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

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

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

  • ruleIdentifiers

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

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

  • Callback

    ฟังก์ชัน

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

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

    • กฎ

      กฎ<anyany>[]

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

• 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 หากตรงกับหมายเลขพอร์ตเริ่มต้น