chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

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

สิทธิ์

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

ความพร้อมใช้งาน

Chrome 84 ขึ้นไป

ไฟล์ Manifest

นอกเหนือจากสิทธิ์ที่อธิบายไว้ข้างต้นแล้ว กฎบางประเภท โดยเฉพาะกฎแบบคงที่ ต้องประกาศคีย์ไฟล์ Manifest "declarative_net_request" ซึ่งควรเป็นพจนานุกรมที่มีคีย์เดียวชื่อ "rule_resources" คีย์นี้เป็นอาร์เรย์ที่มีพจนานุกรมประเภท Ruleset ดังที่แสดงด้านล่าง (โปรดทราบว่าชื่อ "Ruleset" จะไม่ปรากฏใน JSON ของไฟล์ Manifest เนื่องจากเป็นเพียงอาร์เรย์) เราจะอธิบายชุดกฎแบบคงที่ในส่วนถัดไปของเอกสารนี้

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

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

หากต้องการใช้ API นี้ ให้ระบุชุดกฎอย่างน้อย 1 ชุด ชุดกฎประกอบด้วยอาร์เรย์ของกฎ กฎเดียวจะดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้

  • บล็อกคำขอเครือข่าย
  • อัปเกรดสคีมา (http เป็น https)
  • ป้องกันไม่ให้คำขอถูกบล็อกโดยการลบล้างกฎที่ถูกบล็อกที่ตรงกัน
  • เปลี่ยนเส้นทางคำขอเครือข่าย
  • แก้ไขส่วนหัวของคำขอหรือการตอบกลับ

กฎมี 3 ประเภท ซึ่งจัดการด้วยวิธีที่แตกต่างกันเล็กน้อย

ไดนามิก
คงอยู่ตลอดเซสชันของเบราว์เซอร์และการอัปเกรดส่วนขยาย และได้รับการจัดการโดยใช้ JavaScript ขณะที่ส่วนขยายมีการใช้งานอยู่
เซสชัน
ระบบจะล้างข้อมูลเมื่อเบราว์เซอร์ปิดลงและเมื่อมีการติดตั้งส่วนขยายเวอร์ชันใหม่ กฎเซสชันจะได้รับการจัดการโดยใช้ JavaScript ขณะที่ใช้ส่วนขยาย
คงที่
จัดแพ็กเกจ ติดตั้ง และอัปเดตเมื่อมีการติดตั้งหรืออัปเกรดส่วนขยาย กฎแบบคงที่จะจัดเก็บไว้ในไฟล์กฎที่จัดรูปแบบ JSON และแสดงอยู่ในไฟล์ Manifest

ส่วนถัดไปจะอธิบายประเภทชุดกฎโดยละเอียด

ชุดกฎแบบไดนามิกและระดับเซสชัน

กฎแบบไดนามิกและกฎเซสชันจะได้รับการจัดการโดยใช้ JavaScript ขณะที่ส่วนขยายกำลังใช้งานอยู่

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

กฎแต่ละประเภทจะมีเพียงกฎเดียวเท่านั้น ส่วนขยายสามารถเพิ่มหรือนำกฎออกจากชุดกฎได้แบบไดนามิกโดยเรียกใช้ updateDynamicRules() และ updateSessionRules() หากไม่เกินขีดจำกัดของกฎ ดูข้อมูลเกี่ยวกับขีดจำกัดของกฎได้ที่ขีดจำกัดของกฎ คุณดูตัวอย่างของกรณีนี้ได้ในส่วนตัวอย่างโค้ด

ชุดกฎแบบคงที่

กฎแบบคงที่จะได้รับการจัดแพ็กเกจ ติดตั้ง และอัปเดตเมื่อมีการติดตั้งหรืออัปเกรดส่วนขยาย ซึ่งต่างจากกฎแบบไดนามิกและกฎเซสชัน โดยจะจัดเก็บไว้ในไฟล์กฎในรูปแบบ JSON ซึ่งจะระบุไว้ในส่วนขยายโดยใช้คีย์ "declarative_net_request" และ "rule_resources" ตามที่อธิบายไว้ข้างต้น รวมถึงพจนานุกรม Ruleset อย่างน้อย 1 รายการ พจนานุกรม Ruleset มีเส้นทางไปยังไฟล์กฎ รหัสสำหรับชุดกฎที่อยู่ในไฟล์ และสถานะว่าชุดกฎเปิดหรือปิดใช้อยู่ 2 รายการสุดท้ายมีความสำคัญเมื่อคุณเปิดหรือปิดใช้ชุดกฎแบบเป็นโปรแกรม

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

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

เปิดและปิดใช้กฎและชุดกฎแบบคงที่

คุณสามารถเปิดหรือปิดใช้ทั้งกฎแบบคงที่แต่ละข้อและชุดกฎแบบคงที่ทั้งหมดได้ขณะรันไทม์

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

นอกจากนี้ เพื่อประสิทธิภาพในการทำงาน ระบบยังจำกัดจำนวนกฎและชุดกฎที่เปิดใช้พร้อมกันได้ด้วย เรียกใช้ getAvailableStaticRuleCount() เพื่อตรวจสอบจำนวนกฎเพิ่มเติมที่อาจเปิดใช้อยู่ ดูข้อมูลเกี่ยวกับขีดจำกัดของกฎได้ที่ขีดจำกัดของกฎ

หากต้องการเปิดหรือปิดใช้กฎแบบคงที่ ให้เรียกใช้ updateStaticRules() เมธอดนี้ใช้ออบเจ็กต์ UpdateStaticRulesOptions ซึ่งมีอาร์เรย์ของรหัสของกฎที่จะเปิดหรือปิดใช้ ระบบจะกำหนดรหัสโดยใช้คีย์ "id" ของพจนานุกรม Ruleset

หากต้องการเปิดหรือปิดใช้กฎแบบคงที่ ให้เรียกใช้ updateEnabledRulesets() เมธอดนี้จะใช้ออบเจ็กต์ UpdateRulesetOptions ซึ่งมีอาร์เรย์ของรหัสของชุดกฎที่จะเปิดหรือปิดใช้ ระบบจะกำหนดรหัสโดยใช้คีย์ "id" ของพจนานุกรม Ruleset

สร้างกฎ

ไม่ว่าจะเป็นประเภทใด กฎจะเริ่มต้นด้วย 4 ช่องดังที่แสดงด้านล่าง แม้ว่าคีย์ "id" และ "priority" จะใช้ตัวเลข แต่คีย์ "action" และ "condition" อาจมีเงื่อนไขการบล็อกและการเปลี่ยนเส้นทางหลายรายการ กฎต่อไปนี้จะบล็อกคำขอสคริปต์ทั้งหมดที่มาจาก "foo.com" ไปยัง URL ใดก็ตามที่มี "abc" เป็นสตริงย่อย

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

อักขระที่ตรงกันของ urlFilter

คีย์ "condition" ของกฎอนุญาตให้ใช้คีย์ "urlFilter" เพื่อดำเนินการกับ URL ภายใต้โดเมนที่ระบุ คุณสร้างรูปแบบโดยใช้โทเค็นการจับคู่รูปแบบ ตัวอย่างบางส่วนมีดังนี้

urlFilter การจับคู่ ไม่ตรงกัน
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

การจัดลำดับความสำคัญของกฎ

กฎจะทริกเกอร์โดยคำขอที่ส่งจากหน้าเว็บ หากกฎหลายข้อตรงกับคำขอหนึ่งๆ คุณต้องจัดลำดับความสำคัญของกฎ ส่วนนี้จะอธิบายวิธีจัดลําดับความสําคัญของกฎ การจัดลำดับความสำคัญจะเกิดขึ้นใน 2 ระยะ

  1. ระบบจะกำหนดลำดับความสำคัญของกฎภายในส่วนขยาย
  2. หากส่วนขยายมากกว่า 1 รายการสามารถใช้กฎกับคำขอได้ ระบบจะกำหนดลำดับความสำคัญสำหรับส่วนขยายทั้งหมดที่ตรงกับคำขอหนึ่งๆ

การจับคู่ในลักษณะนี้หมายความว่ากฎที่ส่วนขยายหนึ่งๆ ให้ความสำคัญจะได้รับการจัดลำดับความสำคัญเหนือกฎจากส่วนขยายอื่นๆ

การจัดลำดับความสำคัญของกฎภายในส่วนขยาย

ภายในส่วนขยายเดียว การจัดลำดับความสำคัญจะดำเนินการโดยใช้กระบวนการต่อไปนี้

  1. ระบบจะแสดงผลกฎที่มีลำดับความสำคัญสูงสุดที่นักพัฒนาแอปกำหนด (หรือก็คือช่อง "priority")

  2. หากมีกฎมากกว่า 1 ข้อที่มีลำดับความสำคัญสูงสุดที่นักพัฒนาแอปกำหนดไว้ ระบบจะจัดลำดับความสำคัญของกฎโดยใช้ช่อง "action" ตามลำดับต่อไปนี้

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. หากประเภทการดำเนินการไม่ใช่ block หรือ redirect ระบบจะประเมินกฎ modifyHeaders ที่ตรงกัน โปรดทราบว่าหากมีกฎที่มีลำดับความสำคัญที่นักพัฒนาแอปกำหนดไว้ต่ำกว่าลำดับความสำคัญที่ระบุสำหรับ allow และ allowAllRequests ระบบจะไม่สนใจกฎดังกล่าว

  4. หากกฎหลายข้อแก้ไขส่วนหัวเดียวกัน การแก้ไขจะขึ้นอยู่กับช่อง "priority" ที่นักพัฒนาแอปกำหนดและการดำเนินการที่ระบุ

    • หากกฎต่อท้ายส่วนหัว กฎที่มีลำดับความสำคัญต่ำกว่าจะต่อท้ายส่วนหัวนั้นได้เท่านั้น ไม่อนุญาตให้ดำเนินการตั้งค่าและนำออก
    • หากกฎตั้งค่าส่วนหัว กฎที่มีลำดับความสำคัญต่ำกว่าจะเพิ่มต่อท้ายส่วนหัวนั้นได้เท่านั้น ไม่อนุญาตให้ทำการแก้ไขอื่นๆ
    • หากกฎนำส่วนหัวออก กฎที่มีลำดับความสำคัญต่ำกว่าจะแก้ไขส่วนหัวเพิ่มเติมไม่ได้

การจัดลำดับความสำคัญของกฎระหว่างส่วนขยาย

หากมีส่วนขยายเพียงรายการเดียวที่มีกฎที่ตรงกับคำขอ ระบบจะใช้กฎนั้น แต่หากมีส่วนขยายมากกว่า 1 รายการที่ตรงกับคำขอ ระบบจะใช้กระบวนการต่อไปนี้

  1. ระบบจะจัดลำดับความสำคัญของกฎโดยใช้ฟิลด์ "action" ตามลำดับต่อไปนี้

    1. block
    2. redirect หรือ upgradeScheme
    3. allow หรือ allowAllRequests

  2. หากมีกฎที่ตรงกันมากกว่า 1 ข้อ ส่วนขยายที่ติดตั้งล่าสุดจะมีลำดับความสำคัญสูงสุด

ขีดจํากัดของกฎ

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

กฎแบบคงที่

กฎแบบคงที่คือกฎที่ระบุไว้ในไฟล์กฎที่ประกาศในไฟล์ Manifest ส่วนขยายสามารถระบุชุดกฎแบบคงที่ได้สูงสุด 50 ชุดโดยเป็นส่วนหนึ่งของคีย์ไฟล์ Manifest "rule_resources" แต่จะเปิดใช้ชุดกฎเหล่านี้ได้ครั้งละ 10 ชุดเท่านั้น ซึ่งเรียกว่า MAX_NUMBER_OF_ENABLED_STATIC_RULESETS โดยรวมแล้ว ชุดกฎเหล่านั้นจะรับประกันกฎอย่างน้อย 30,000 ข้อ ซึ่งเรียกว่า GUARANTEED_MINIMUM_STATIC_RULES

จำนวนกฎที่ใช้ได้หลังจากนั้นจะขึ้นอยู่กับจำนวนกฎที่เปิดใช้โดยส่วนขยายทั้งหมดที่ติดตั้งในเบราว์เซอร์ของผู้ใช้ คุณสามารถดูหมายเลขนี้ได้ที่รันไทม์โดยเรียกใช้ getAvailableStaticRuleCount() คุณดูตัวอย่างของกรณีนี้ได้ในส่วนตัวอย่างโค้ด

กฎแบบไดนามิกและกฎเซสชัน

ขีดจำกัดที่ใช้กับกฎแบบไดนามิกและกฎเซสชันจะเข้าใจง่ายกว่ากฎแบบคงที่ จำนวนรวมของทั้ง 2 รายการต้องไม่เกิน 5,000 รายการ ซึ่งเรียกว่า MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES

กฎที่ใช้นิพจน์ทั่วไป

กฎทุกประเภทสามารถใช้นิพจน์ทั่วไปได้ แต่จำนวนกฎนิพจน์ทั่วไปทั้งหมดของแต่ละประเภทต้องไม่เกิน 1, 000 รายการ ซึ่งเรียกว่า MAX_NUMBER_OF_REGEX_RULES

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

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

การโต้ตอบกับ Service Worker

declarativeNetRequest จะมีผลกับคำขอที่เข้าถึงสแต็กเครือข่ายเท่านั้น ซึ่งรวมถึงการตอบกลับจากแคช HTTP แต่อาจไม่รวมการตอบกลับที่ผ่านเครื่องจัดการ onfetch ของ Service Worker declarativeNetRequest จะไม่ส่งผลต่อการตอบกลับที่สร้างโดย Service Worker หรือดึงมาจาก CacheStorage แต่จะส่งผลต่อการเรียกใช้ fetch() ที่ทำใน Service Worker

แหล่งข้อมูลที่เข้าถึงได้บนเว็บ

กฎ declarativeNetRequest ไม่สามารถเปลี่ยนเส้นทางจากคำขอทรัพยากรสาธารณะไปยังทรัพยากรที่เข้าถึงไม่ได้บนเว็บ เนื่องจากจะทำให้เกิดข้อผิดพลาด ซึ่งรวมถึงกรณีที่ส่วนขยายที่เปลี่ยนเส้นทางเป็นเจ้าของทรัพยากรที่เข้าถึงได้บนเว็บที่ระบุด้วย หากต้องการประกาศทรัพยากรสำหรับ declarativeNetRequest ให้ใช้อาร์เรย์ "web_accessible_resources" ของไฟล์ Manifest

ตัวอย่าง

ตัวอย่างโค้ด

อัปเดตกฎแบบไดนามิก

ตัวอย่างต่อไปนี้แสดงวิธีเรียกใช้ updateDynamicRules() ขั้นตอนสำหรับ updateSessionRules() จะเหมือนกัน

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

อัปเดตชุดกฎแบบคงที่

ตัวอย่างต่อไปนี้แสดงวิธีเปิดและปิดใช้ชุดกฎโดยพิจารณาจากจำนวนชุดกฎแบบคงที่ที่ใช้ได้และจำนวนสูงสุดของชุดกฎแบบคงที่ที่เปิดใช้ คุณจะดำเนินการนี้เมื่อจำนวนกฎแบบคงที่ที่ต้องการเกินจำนวนที่อนุญาต เพื่อให้วิธีนี้ได้ผล คุณควรติดตั้งชุดกฎบางชุดโดยปิดใช้ชุดกฎบางชุด (ตั้งค่า "Enabled" เป็น false ภายในไฟล์ Manifest)

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

ตัวอย่างกฎ

ตัวอย่างด้านล่างแสดงวิธีที่ Chrome จัดลำดับความสำคัญของกฎในส่วนขยาย เมื่อตรวจสอบ คุณอาจต้องเปิดกฎการจัดลำดับความสำคัญในหน้าต่างแยกต่างหาก

คีย์ "priority"

ตัวอย่างเหล่านี้ต้องใช้สิทธิ์ของโฮสต์ใน *://*.example.com/*

หากต้องการหาลำดับความสำคัญของ URL หนึ่งๆ ให้ดูที่คีย์ "priority" (ที่นักพัฒนาซอฟต์แวร์กำหนด) คีย์ "action" และคีย์ "urlFilter" ตัวอย่างเหล่านี้อ้างอิงถึงไฟล์กฎตัวอย่างที่แสดงด้านล่าง

การนำทางไปยัง https://google.com
กฎ 2 ข้อครอบคลุม URL นี้ ได้แก่ กฎที่มีรหัส 1 และ 4 กฎที่มีรหัส 1 จะมีผลเนื่องจากการดำเนินการ"block"มีลำดับความสำคัญสูงกว่าการดำเนินการ"redirect" กฎที่เหลือจะไม่มีผลเนื่องจากเป็นกฎสำหรับ URL ที่ยาวกว่า
การนำทางไปยัง https://google.com/1234
เนื่องจาก URL ยาวขึ้น กฎที่มีรหัส 2 จึงตรงกันด้วย นอกเหนือจากกฎที่มีรหัส 1 และ 4 กฎที่มีรหัส 2 จะมีผลเนื่องจาก "allow" มีลำดับความสำคัญสูงกว่า "block" และ "redirect"
การไปยัง https://google.com/12345
กฎทั้ง 4 ข้อตรงกับ URL นี้ กฎที่มีรหัส 3 จะมีผลบังคับใช้เนื่องจากลำดับความสำคัญที่นักพัฒนาแอปกำหนดไว้สูงที่สุดในกลุ่ม
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
]

การเปลี่ยนเส้นทาง

ตัวอย่างด้านล่างต้องใช้สิทธิ์ของโฮสต์ใน *://*.example.com/*

ตัวอย่างต่อไปนี้แสดงวิธีเปลี่ยนเส้นทางคำขอจาก example.com ไปยังหน้าภายในส่วนขยายเอง เส้นทางส่วนขยาย /a.jpg จะเปลี่ยนเป็น chrome-extension://EXTENSION_ID/a.jpg โดยที่ EXTENSION_ID คือรหัสของส่วนขยาย เพื่อให้ฟีเจอร์นี้ทำงานได้ ไฟล์ Manifest ควรประกาศ /a.jpg เป็นทรัพยากรที่เข้าถึงได้บนเว็บ

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "https://www.example.com",
    "resourceTypes": ["main_frame"]
  }
}

ตัวอย่างต่อไปนี้ใช้คีย์ "transform" เพื่อเปลี่ยนเส้นทางไปยังโดเมนย่อยของ example.com โดยใช้ Anchor ชื่อโดเมน ("||") เพื่อสกัดกั้นคำขอที่มีรูปแบบใดก็ได้จาก example.com คีย์ "scheme" ใน "transform" ระบุว่าการเปลี่ยนเส้นทางไปยังโดเมนย่อยจะใช้ "https" เสมอ

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com",
    "resourceTypes": ["main_frame"]
  }
}

ตัวอย่างต่อไปนี้ใช้นิพจน์ทั่วไปเพื่อเปลี่ยนเส้นทางจาก https://www.abc.xyz.com/path ไปยัง https://abc.xyz.com/path ในคีย์ "regexFilter" ให้สังเกตวิธีหลีกเลี่ยงจุดและแคปเจอร์กรุ๊ปจะเลือก "abc" หรือ "def" คีย์ "regexSubstitution" จะระบุรายการที่ตรงกันรายการแรกที่แสดงผลของนิพจน์ทั่วไปโดยใช้ "\1" ในกรณีนี้ ระบบจะบันทึก "abc" จาก URL ที่เปลี่ยนเส้นทางและวางไว้ในการแทนที่

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

ส่วนหัว

ตัวอย่างต่อไปนี้จะนำคุกกี้ทั้งหมดออกจากทั้งเฟรมหลักและเฟรมย่อย

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

ประเภท

DomainType

ซึ่งจะอธิบายว่าคำขอเป็นของบุคคลที่หนึ่งหรือบุคคลที่สามในเฟรมที่คำขอเริ่มต้นขึ้น คำขอจะถือว่าเป็นของบุคคลที่หนึ่งหากมีโดเมน (eTLD+1) เดียวกันกับเฟรมที่คำขอเริ่มต้นขึ้น

ค่าแจกแจง

"firstParty"
คำขอเครือข่ายเป็นบุคคลที่หนึ่งสำหรับเฟรมที่คำขอเริ่มต้นขึ้น

"thirdParty"
คำขอเครือข่ายเป็นของบุคคลที่สามสำหรับเฟรมที่คำขอเริ่มต้นขึ้น

ExtensionActionOptions

Chrome 88 ขึ้นไป

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

  • displayActionCountAsBadgeText

    บูลีน ไม่บังคับ

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

  • tabUpdate

    TabActionCountUpdate ไม่บังคับ

    Chrome 89 ขึ้นไป

    รายละเอียดเกี่ยวกับวิธีปรับจำนวนการดำเนินการของแท็บ

GetDisabledRuleIdsOptions

Chrome 111 ขึ้นไป

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

  • rulesetId

    สตริง

    รหัสที่สอดคล้องกับ Ruleset แบบคงที่

GetRulesFilter

Chrome 111 ขึ้นไป

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

  • ruleIds

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

    หากระบุ ระบบจะรวมเฉพาะกฎที่มีรหัสที่ตรงกันเท่านั้น

HeaderInfo

Chrome 128 ขึ้นไป

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

  • excludedValues

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

    หากระบุ เงื่อนไขนี้จะไม่ตรงกันหากมีส่วนหัวอยู่ แต่ค่าของส่วนหัวมีองค์ประกอบอย่างน้อย 1 รายการในรายการนี้ ซึ่งใช้ไวยากรณ์รูปแบบการจับคู่เดียวกันกับ values

  • ส่วนหัว

    สตริง

    ชื่อของส่วนหัว เงื่อนไขนี้จะจับคู่กับชื่อก็ต่อเมื่อไม่ได้ระบุทั้ง values และ excludedValues

  • values

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

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

    '*' : จับคู่อักขระจำนวนเท่าใดก็ได้

    "?" : จับคู่อักขระ 0 หรือ 1 ตัว

    คุณสามารถหลีกเลี่ยง "*" และ "?" ได้ด้วยแบ็กสแลช เช่น "\*" และ "\?"

HeaderOperation

Chrome 86 ขึ้นไป

ส่วนนี้อธิบายการดำเนินการที่เป็นไปได้สำหรับกฎ "modifyHeaders"

ค่าแจกแจง

"append"
เพิ่มรายการใหม่สำหรับส่วนหัวที่ระบุ เมื่อแก้ไขส่วนหัวของคำขอ การดำเนินการนี้จะรองรับเฉพาะส่วนหัวที่เฉพาะเจาะจงเท่านั้น

"set"
ตั้งค่าใหม่สำหรับส่วนหัวที่ระบุ โดยนำส่วนหัวที่มีอยู่ซึ่งมีชื่อเดียวกันออก

"remove"
นำรายการทั้งหมดสำหรับส่วนหัวที่ระบุออก

IsRegexSupportedResult

Chrome 87 ขึ้นไป

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

  • isSupported

    บูลีน

  • เหตุผล

    UnsupportedRegexReason ไม่บังคับ

    ระบุสาเหตุที่ไม่รองรับนิพจน์ทั่วไป ระบุเฉพาะในกรณีที่ isSupported เป็นเท็จ

MatchedRule

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

  • ruleId

    ตัวเลข

    รหัสของกฎการจับคู่

  • rulesetId

    สตริง

    รหัสของ Ruleset ที่กฎนี้เป็นของ สำหรับกฎที่มาจากชุดกฎแบบไดนามิก ค่านี้จะเท่ากับ DYNAMIC_RULESET_ID

MatchedRuleInfo

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

  • กฎ

    MatchedRule

  • tabId

    ตัวเลข

    tabId ของแท็บที่ส่งคำขอ หากแท็บยังทำงานอยู่ Else -1.

  • timeStamp

    ตัวเลข

    เวลาที่กฎตรงกัน การประทับเวลาจะสอดคล้องกับรูปแบบเวลาของ JavaScript เช่น จำนวนมิลลิวินาทีนับตั้งแต่จุดเริ่มต้น

MatchedRuleInfoDebug

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

  • ส่งคำขอ

    RequestDetails

    รายละเอียดเกี่ยวกับคำขอที่ตรงกับกฎ

  • กฎ

    MatchedRule

MatchedRulesFilter

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

  • minTimeStamp

    number ไม่บังคับ

    หากระบุไว้ ระบบจะจับคู่กฎหลังจากมีการประทับเวลาที่ระบุเท่านั้น

  • tabId

    number ไม่บังคับ

    หากระบุไว้ ระบบจะจับคู่กฎสำหรับแท็บที่ระบุเท่านั้น จับคู่กฎที่ไม่ได้เชื่อมโยงกับแท็บที่ใช้งานอยู่หากตั้งค่าเป็น -1

ModifyHeaderInfo

Chrome 86 ขึ้นไป

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

  • ส่วนหัว

    สตริง

    ชื่อของส่วนหัวที่จะแก้ไข

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

    HeaderOperation

    การดำเนินการที่จะทำกับส่วนหัว

  • value

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

    ค่าใหม่สำหรับส่วนหัว ต้องระบุสำหรับการดำเนินการ append และ set

QueryKeyValue

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

  • แป้น

    สตริง

  • replaceOnly

    บูลีน ไม่บังคับ

    Chrome 94 ขึ้นไป

    หากเป็นจริง ระบบจะแทนที่คีย์การค้นหาเฉพาะในกรณีที่มีอยู่แล้วเท่านั้น ไม่เช่นนั้น ระบบจะเพิ่มคีย์ด้วยหากไม่มี ค่าเริ่มต้นคือ "เท็จ"

  • value

    สตริง

QueryTransform

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

  • addOrReplaceParams

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

    รายการคู่คีย์-ค่าของคำค้นหาที่จะเพิ่มหรือแทนที่

  • removeParams

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

    รายการคีย์การค้นหาที่จะนำออก

Redirect

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

  • extensionPath

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

    เส้นทางที่สัมพันธ์กับไดเรกทอรีส่วนขยาย ควรขึ้นต้นด้วย "/"

  • regexSubstitution

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

    รูปแบบการแทนที่สำหรับกฎที่ระบุ regexFilter ระบบจะแทนที่รายการแรกที่ตรงกับ regexFilter ภายใน URL ด้วยรูปแบบนี้ ภายใน regexSubstitution คุณสามารถใช้ตัวเลขที่หลีกด้วยแบ็กสแลช (\1 ถึง \9) เพื่อแทรกแคปเจอร์กรุ๊ปที่เกี่ยวข้องได้ \0 หมายถึงข้อความที่ตรงกันทั้งหมด

  • การเปลี่ยนรูปแบบ

    URLTransform ไม่บังคับ

    การเปลี่ยนรูปแบบ URL ที่จะดำเนินการ

  • URL

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

    URL เปลี่ยนเส้นทาง ไม่อนุญาตให้เปลี่ยนเส้นทางไปยัง URL ของ JavaScript

RegexOptions

Chrome 87 ขึ้นไป

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

  • isCaseSensitive

    บูลีน ไม่บังคับ

    regexที่ระบุคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่หรือไม่ ค่าเริ่มต้นคือ true

  • นิพจน์ทั่วไป

    สตริง

    นิพจน์ทั่วไปที่จะตรวจสอบ

  • requireCapturing

    บูลีน ไม่บังคับ

    regex ที่ระบุต้องมีการบันทึกหรือไม่ การบันทึกจำเป็นสำหรับกฎการเปลี่ยนเส้นทางที่ระบุการดำเนินการ regexSubstition เท่านั้น ค่าเริ่มต้นคือเท็จ

RequestDetails

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

  • documentId

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

    Chrome 106 ขึ้นไป

    ตัวระบุที่ไม่ซ้ำกันสำหรับเอกสารของเฟรม หากคำขอนี้มีไว้สำหรับเฟรม

  • documentLifecycle

    DocumentLifecycle ไม่บังคับ

    Chrome 106 ขึ้นไป

    วงจรของเอกสารของเฟรม หากคำขอนี้มีไว้สำหรับเฟรม

  • frameId

    ตัวเลข

    ค่า 0 บ่งชี้ว่าคำขอเกิดขึ้นในเฟรมหลัก ค่าบวกบ่งชี้รหัสของเฟรมย่อยที่คำขอเกิดขึ้น หากโหลดเอกสารของ (เฟรมย่อย) (type คือ main_frame หรือ sub_frame) frameId จะระบุรหัสของเฟรมนี้ ไม่ใช่รหัสของเฟรมนอก รหัสเฟรมจะไม่ซ้ำกันภายในแท็บ

  • frameType

    FrameType ไม่บังคับ

    Chrome 106 ขึ้นไป

    ประเภทของเฟรม หากคำขอนี้มีไว้สำหรับเฟรม

  • ผู้เริ่ม

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

    ต้นทางที่เริ่มคำขอ ซึ่งจะไม่เปลี่ยนแปลงผ่านการเปลี่ยนเส้นทาง หากเป็นต้นทางแบบทึบแสง ระบบจะใช้สตริง "null"

  • method

    สตริง

    เมธอด HTTP มาตรฐาน

  • parentDocumentId

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

    Chrome 106 ขึ้นไป

    ตัวระบุที่ไม่ซ้ำกันสำหรับเอกสารหลักของเฟรม หากคำขอนี้มีไว้สำหรับเฟรมและมีรายการหลัก

  • parentFrameId

    ตัวเลข

    รหัสของเฟรมที่รวมเฟรมที่ส่งคำขอ ตั้งค่าเป็น -1 หากไม่มีเฟรมระดับบนสุด

  • requestId

    สตริง

    รหัสของคำขอ รหัสคำขอจะไม่ซ้ำกันภายในเซสชันของเบราว์เซอร์

  • tabId

    ตัวเลข

    รหัสของแท็บที่มีคำขอเกิดขึ้น ตั้งค่าเป็น -1 หากคำขอไม่เกี่ยวข้องกับแท็บ

  • ประเภท

    ResourceType

    ประเภททรัพยากรของคำขอ

  • URL

    สตริง

    URL ของคำขอ

RequestMethod

Chrome 91 ขึ้นไป

ซึ่งจะอธิบายเมธอดคำขอ HTTP ของคำขอเครือข่าย

ค่าแจกแจง

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

ซึ่งอธิบายประเภททรัพยากรของคำขอเครือข่าย

ค่าแจกแจง

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

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

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

    RuleAction

    การดำเนินการที่ต้องทำหากตรงกับกฎนี้

  • เงื่อนไข

    RuleCondition

    เงื่อนไขที่จะเรียกใช้กฎนี้

  • id

    ตัวเลข

    รหัสที่ระบุกฎแบบไม่ซ้ำกัน ต้องระบุและควรมีค่า >= 1

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

    number ไม่บังคับ

    ลำดับความสำคัญของกฎ ค่าเริ่มต้นคือ 1 เมื่อระบุแล้ว ควรมีค่า >= 1

RuleAction

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

  • เปลี่ยนเส้นทาง

    Redirect ไม่บังคับ

    อธิบายวิธีดำเนินการเปลี่ยนเส้นทาง ใช้ได้กับกฎการเปลี่ยนเส้นทางเท่านั้น

  • requestHeaders

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

    Chrome 86 ขึ้นไป

    ส่วนหัวของคำขอที่จะแก้ไขสำหรับคำขอ ใช้ได้เฉพาะเมื่อ RuleActionType เป็น "modifyHeaders"

  • responseHeaders

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

    Chrome 86 ขึ้นไป

    ส่วนหัวการตอบกลับที่จะแก้ไขสำหรับคำขอ ใช้ได้เฉพาะเมื่อ RuleActionType เป็น "modifyHeaders"

  • ประเภท

    RuleActionType

    ประเภทการดำเนินการที่จะทำ

RuleActionType

อธิบายประเภทการดำเนินการที่ต้องทำหาก RuleCondition ที่ระบุตรงกัน

ค่าแจกแจง

"block"
บล็อกคำขอเครือข่าย

"redirect"
เปลี่ยนเส้นทางคำขอเครือข่าย

"allow"
อนุญาตคำขอเครือข่าย ระบบจะไม่สกัดกั้นคำขอหากมีกฎการอนุญาตที่ตรงกับคำขอดังกล่าว

"upgradeScheme"
อัปเกรดรูปแบบ URL ของคำขอเครือข่ายเป็น HTTPS หากคำขอเป็น HTTP หรือ FTP

"modifyHeaders"
แก้ไขส่วนหัวของคำขอ/ส่วนหัวการตอบกลับจากคำขอเครือข่าย

"allowAllRequests"
อนุญาตคำขอทั้งหมดภายในลำดับชั้นของเฟรม รวมถึงคำขอเฟรมเอง

RuleCondition

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

  • domainType

    DomainType ไม่บังคับ

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

  • โดเมน

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

    เลิกใช้งานตั้งแต่ Chrome 101

    ใช้ initiatorDomains แทน

    กฎจะจับคู่เฉพาะคำขอเครือข่ายที่มาจากรายการ domains เท่านั้น

  • excludedDomains

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

    เลิกใช้งานตั้งแต่ Chrome 101

    ใช้ excludedInitiatorDomains แทน

    กฎจะไม่จับคู่คำขอเครือข่ายที่มาจากรายการ excludedDomains

  • excludedInitiatorDomains

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

    Chrome 101 ขึ้นไป

    กฎจะไม่จับคู่คำขอเครือข่ายที่มาจากรายการ excludedInitiatorDomains หากรายการว่างเปล่าหรือละเว้น ระบบจะไม่ยกเว้นโดเมนใดๆ ซึ่งจะมีความสำคัญเหนือ initiatorDomains

    หมายเหตุ:

    • นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
    • รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
    • ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
    • ซึ่งจะจับคู่กับผู้เริ่มคำขอ ไม่ใช่ URL ของคำขอ
    • ระบบจะยกเว้นโดเมนย่อยของโดเมนที่ระบุด้วย
  • excludedRequestDomains

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

    Chrome 101 ขึ้นไป

    กฎจะไม่จับคู่คำขอเครือข่ายเมื่อโดเมนตรงกับโดเมนจากรายการ excludedRequestDomains หากรายการว่างเปล่าหรือละเว้น ระบบจะไม่ยกเว้นโดเมนใดๆ ซึ่งจะมีความสำคัญเหนือ requestDomains

    หมายเหตุ:

    • นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
    • รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
    • ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
    • ระบบจะยกเว้นโดเมนย่อยของโดเมนที่ระบุด้วย
  • excludedRequestMethods

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

    Chrome 91 ขึ้นไป

    รายการเมธอดคำขอที่กฎจะไม่จับคู่ ควรระบุ requestMethods หรือ excludedRequestMethods เพียงรายการเดียวเท่านั้น หากไม่ได้ระบุทั้ง 2 รายการ ระบบจะจับคู่เมธอดคำขอทั้งหมด

  • excludedResourceTypes

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

    รายการประเภททรัพยากรที่กฎจะไม่จับคู่ ควรระบุ resourceTypes หรือ excludedResourceTypes เพียงรายการเดียวเท่านั้น หากไม่ได้ระบุทั้ง 2 อย่าง ระบบจะบล็อกทรัพยากรทุกประเภท ยกเว้น "main_frame"

  • excludedResponseHeaders

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

    Chrome 128 ขึ้นไป

    กฎจะไม่ตรงกันหากคำขอตรงกับเงื่อนไขส่วนหัวการตอบกลับในรายการนี้ (หากระบุ) หากระบุทั้ง excludedResponseHeaders และ responseHeaders พร็อพเพอร์ตี้ excludedResponseHeaders จะมีความสำคัญเหนือกว่า

  • excludedTabIds

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

    Chrome 92 ขึ้นไป

    รายการ tabs.Tab.id ที่กฎไม่ควรจับคู่ รหัส tabs.TAB_ID_NONE จะยกเว้นคำขอที่ไม่ได้มาจากแท็บ รองรับเฉพาะกฎที่กำหนดขอบเขตระดับเซสชันเท่านั้น

  • excludedTopDomains

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

    Chrome 145 ขึ้นไป

    กฎจะไม่จับคู่คำขอเครือข่ายเมื่อโดเมนของเฟรมระดับบนสุดที่เชื่อมโยงตรงกับโดเมนจากรายการ excludedTopDomains หากรายการว่างเปล่าหรือละเว้น ระบบจะไม่ยกเว้นโดเมนใดๆ ซึ่งจะมีความสำคัญเหนือ topDomains

    หมายเหตุ:

    • นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
    • รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
    • ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
    • ระบบจะยกเว้นโดเมนย่อยของโดเมนที่ระบุด้วย
    • สำหรับคำขอที่ไม่มีเฟรมระดับบนสุดที่เชื่อมโยง (เช่น คำขอที่เริ่มต้นโดย ServiceWorker) ระบบจะพิจารณาโดเมนของผู้เริ่มต้นคำขอแทน
  • initiatorDomains

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

    Chrome 101 ขึ้นไป

    กฎจะจับคู่เฉพาะคำขอเครือข่ายที่มาจากรายการ initiatorDomains เท่านั้น หากละเว้นรายการ ระบบจะใช้กฎกับคำขอจากโดเมนทั้งหมด ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

    หมายเหตุ:

    • นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
    • รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
    • ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
    • ซึ่งจะจับคู่กับผู้เริ่มคำขอ ไม่ใช่ URL ของคำขอ
    • โดเมนย่อยของโดเมนที่ระบุจะตรงกันด้วย
  • isUrlFilterCaseSensitive

    บูลีน ไม่บังคับ

    urlFilter หรือ regexFilter (ตามที่ระบุ) คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่หรือไม่ ค่าเริ่มต้นคือ false

  • regexFilter

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

    นิพจน์ทั่วไปที่จะจับคู่กับ URL คำขอเครือข่าย ซึ่งเป็นไปตามไวยากรณ์ RE2

    หมายเหตุ: คุณระบุได้เพียง urlFilter หรือ regexFilter อย่างใดอย่างหนึ่งเท่านั้น

    หมายเหตุ: regexFilter ต้องประกอบด้วยอักขระ ASCII เท่านั้น ซึ่งจะจับคู่กับ URL ที่โฮสต์เข้ารหัสในรูปแบบ Punycode (ในกรณีที่เป็นโดเมนสากล) และอักขระอื่นๆ ที่ไม่ใช่ ASCII จะเข้ารหัส URL ใน UTF-8

  • requestDomains

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

    Chrome 101 ขึ้นไป

    กฎจะจับคู่คำขอเครือข่ายก็ต่อเมื่อโดเมนตรงกับโดเมนจากรายการ requestDomains เท่านั้น หากละเว้นรายการ ระบบจะใช้กฎกับคำขอจากโดเมนทั้งหมด ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

    หมายเหตุ:

    • นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
    • รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
    • ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
    • โดเมนย่อยของโดเมนที่ระบุจะตรงกันด้วย
  • requestMethods

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

    Chrome 91 ขึ้นไป

    รายการเมธอดคำขอ HTTP ที่กฎสามารถจับคู่ได้ ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

    หมายเหตุ: การระบุเงื่อนไขกฎ requestMethods จะยกเว้นคำขอที่ไม่ใช่ HTTP(S) ด้วย ส่วนการระบุ excludedRequestMethods จะไม่ยกเว้น

  • resourceTypes

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

    รายการประเภททรัพยากรที่กฎสามารถจับคู่ได้ ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

    หมายเหตุ: ต้องระบุค่านี้สำหรับกฎ allowAllRequests และอาจรวมเฉพาะประเภททรัพยากร sub_frame และ main_frame เท่านั้น

  • responseHeaders

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

    Chrome 128 ขึ้นไป

    กฎจะตรงกันหากคำขอตรงกับเงื่อนไขส่วนหัวการตอบกลับในรายการนี้ (หากระบุ)

  • tabIds

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

    Chrome 92 ขึ้นไป

    รายการ tabs.Tab.id ที่กฎควรตรงกัน รหัส tabs.TAB_ID_NONE จะจับคู่กับคำขอที่ไม่ได้มาจากแท็บ ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า รองรับเฉพาะกฎที่กำหนดขอบเขตระดับเซสชันเท่านั้น

  • topDomains

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

    Chrome 145 ขึ้นไป

    กฎจะจับคู่คำขอเครือข่ายก็ต่อเมื่อโดเมนของเฟรมระดับบนสุดที่เชื่อมโยงตรงกับโดเมนจากรายการ topDomains หากละเว้นรายการ ระบบจะใช้กฎกับคำขอที่เชื่อมโยงกับโดเมนเฟรมระดับบนสุดทั้งหมด ไม่อนุญาตให้ใช้รายการที่ว่างเปล่า

    หมายเหตุ:

    • นอกจากนี้ยังอนุญาตให้ใช้โดเมนย่อย เช่น "a.example.com" ด้วย
    • รายการต้องประกอบด้วยอักขระ ASCII เท่านั้น
    • ใช้การเข้ารหัส Punycode สำหรับโดเมนที่เป็นสากล
    • โดเมนย่อยของโดเมนที่ระบุจะตรงกันด้วย
    • สำหรับคำขอที่ไม่มีเฟรมระดับบนสุดที่เชื่อมโยง (เช่น คำขอที่เริ่มต้นโดย ServiceWorker) ระบบจะพิจารณาโดเมนของผู้เริ่มต้นคำขอแทน
  • urlFilter

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

    รูปแบบที่ตรงกับ URL คำขอเครือข่าย โครงสร้างที่รองรับ:

    '*' : ไวลด์การ์ด: จับคู่อักขระจำนวนเท่าใดก็ได้

    '|' : Anchor ซ้าย/ขวา: หากใช้ที่ส่วนท้ายของรูปแบบ จะระบุจุดเริ่มต้น/จุดสิ้นสุดของ URL ตามลำดับ

    '||' : Anchor ชื่อโดเมน: หากใช้ที่จุดเริ่มต้นของรูปแบบ จะระบุจุดเริ่มต้นของ (โดเมนย่อย) ของ URL

    '^' : อักขระตัวคั่น: อักขระนี้จะจับคู่กับอักขระใดก็ได้ ยกเว้นตัวอักษร ตัวเลข หรืออักขระต่อไปนี้ _, -, . หรือ % ซึ่งจะจับคู่กับส่วนท้ายของ URL ด้วย

    ดังนั้น urlFilter จึงประกอบด้วยส่วนต่างๆ ต่อไปนี้ (Anchor ด้านซ้าย/ชื่อโดเมนที่ไม่บังคับ) + รูปแบบ + (Anchor ด้านขวาที่ไม่บังคับ)

    หากละเว้น ระบบจะจับคู่ URL ทั้งหมด ไม่อนุญาตให้ใช้สตริงว่างเปล่า

    ไม่อนุญาตให้ใช้รูปแบบที่ขึ้นต้นด้วย ||* โปรดใช้ * แทน

    หมายเหตุ: คุณระบุได้เพียง urlFilter หรือ regexFilter อย่างใดอย่างหนึ่งเท่านั้น

    หมายเหตุ: urlFilter ต้องประกอบด้วยอักขระ ASCII เท่านั้น ซึ่งจะจับคู่กับ URL ที่โฮสต์เข้ารหัสในรูปแบบ Punycode (ในกรณีที่เป็นโดเมนสากล) และอักขระอื่นๆ ที่ไม่ใช่ ASCII จะเข้ารหัส URL ใน UTF-8 ตัวอย่างเช่น เมื่อ URL คำขอคือ http://abc.рф?q=ф ระบบจะจับคู่ urlFilter กับ URL http://abc.xn--p1ai/?q=%D1%84

RuleConditionKeys

Chrome 145 ขึ้นไป

ค่าแจกแจง

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

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

  • เปิดอยู่

    บูลีน

    เปิดใช้ชุดกฎโดยค่าเริ่มต้นหรือไม่

  • id

    สตริง

    สตริงที่ไม่ใช่ค่าว่างซึ่งระบุชุดกฎโดยไม่ซ้ำกัน รหัสที่ขึ้นต้นด้วย "_" สงวนไว้สำหรับการใช้งานภายใน

  • เส้นทาง

    สตริง

    เส้นทางของกฎ JSON ที่สัมพันธ์กับไดเรกทอรีส่วนขยาย

RulesMatchedDetails

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

  • rulesMatchedInfo

    MatchedRuleInfo[]

    กฎที่ตรงกับตัวกรองที่ระบุ

TabActionCountUpdate

Chrome 89 ขึ้นไป

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

  • การเพิ่มขึ้น

    ตัวเลข

    จำนวนที่จะเพิ่มจำนวนการดำเนินการของแท็บ ค่าลบจะลดจำนวนลง

  • tabId

    ตัวเลข

    แท็บที่จะอัปเดตจำนวนการดำเนินการ

TestMatchOutcomeResult

Chrome 103 ขึ้นไป

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

  • matchedRules

    MatchedRule[]

    กฎ (หากมี) ที่ตรงกับคำขอสมมติ

TestMatchRequestDetails

Chrome 103 ขึ้นไป

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

  • ผู้เริ่ม

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

    URL ของตัวเริ่มต้น (หากมี) สำหรับคำขอสมมติ

  • method

    RequestMethod ไม่บังคับ

    เมธอด HTTP มาตรฐานของคำขอสมมติ ค่าเริ่มต้นคือ "get" สำหรับคำขอ HTTP และระบบจะไม่สนใจสำหรับคำขอที่ไม่ใช่ HTTP

  • responseHeaders

    object ไม่บังคับ

    Chrome 129 ขึ้นไป

    ส่วนหัวที่ได้จากการตอบกลับสมมติในกรณีที่คำขอไม่ถูกบล็อกหรือเปลี่ยนเส้นทางก่อนที่จะส่ง แสดงเป็นออบเจ็กต์ที่แมปชื่อส่วนหัวกับรายการค่าสตริง หากไม่ได้ระบุ การตอบกลับสมมติจะแสดงส่วนหัวการตอบกลับที่ว่างเปล่า ซึ่งอาจตรงกับกฎที่ตรงกับการไม่มีส่วนหัว เช่น {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number ไม่บังคับ

    รหัสของแท็บที่คำขอสมมติเกิดขึ้น ไม่จำเป็นต้องสอดคล้องกับรหัสแท็บจริง ค่าเริ่มต้นคือ -1 ซึ่งหมายความว่าคำขอไม่เกี่ยวข้องกับแท็บ

  • topUrl

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

    Chrome 145 ขึ้นไป

    URL เฟรมระดับบนสุดที่เชื่อมโยง (หากมี) สำหรับคำขอ

  • ประเภท

    ResourceType

    ประเภททรัพยากรของคำขอสมมติ

  • URL

    สตริง

    URL ของคำขอสมมติ

UnsupportedRegexReason

Chrome 87 ขึ้นไป

อธิบายสาเหตุที่ระบบไม่รองรับนิพจน์ทั่วไปที่ระบุ

ค่าแจกแจง

"syntaxError"
นิพจน์ทั่วไปมีไวยากรณ์ไม่ถูกต้อง หรือใช้ฟีเจอร์ที่ไม่มีในไวยากรณ์ RE2

"memoryLimitExceeded"
นิพจน์ทั่วไปเกินขีดจำกัดหน่วยความจำ

UpdateRuleOptions

Chrome 87 ขึ้นไป

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

  • addRules

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

    กฎที่จะเพิ่ม

  • removeRuleIds

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

    รหัสของกฎที่จะนำออก ระบบจะไม่สนใจรหัสที่ไม่ถูกต้อง

UpdateRulesetOptions

Chrome 87 ขึ้นไป

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

  • disableRulesetIds

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

    ชุดรหัสที่สอดคล้องกับ Ruleset แบบคงที่ซึ่งควรปิดใช้

  • enableRulesetIds

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

    ชุดรหัสที่สอดคล้องกับ Ruleset แบบคงที่ที่ควรเปิดใช้

UpdateStaticRulesOptions

Chrome 111 ขึ้นไป

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

  • disableRuleIds

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

    ชุดรหัสที่สอดคล้องกับกฎใน Ruleset ที่จะปิดใช้

  • enableRuleIds

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

    ชุดรหัสที่สอดคล้องกับกฎใน Ruleset ที่จะเปิดใช้

  • rulesetId

    สตริง

    รหัสที่สอดคล้องกับ Ruleset แบบคงที่

URLTransform

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

  • Fragment

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

    ส่วนย่อยใหม่สำหรับคำขอ ควรเว้นว่างไว้ ซึ่งในกรณีนี้ระบบจะล้าง Fragment ที่มีอยู่ หรือควรขึ้นต้นด้วย "#"

  • ผู้จัด

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

    โฮสต์ใหม่สำหรับคำขอ

  • รหัสผ่าน

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

    รหัสผ่านใหม่สำหรับคำขอ

  • เส้นทาง

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

    เส้นทางใหม่สำหรับคำขอ หากเว้นว่างไว้ ระบบจะล้างเส้นทางที่มีอยู่

  • พอร์ต

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

    พอร์ตใหม่สำหรับคำขอ หากเว้นว่างไว้ ระบบจะล้างพอร์ตที่มีอยู่

  • query

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

    คำค้นหาใหม่สำหรับคำขอ ควรเว้นว่างไว้ ซึ่งในกรณีนี้ระบบจะล้างการค้นหาที่มีอยู่ หรือควรขึ้นต้นด้วย "?"

  • queryTransform

    QueryTransform ไม่บังคับ

    เพิ่ม นำออก หรือแทนที่คู่คีย์-ค่าของคำค้นหา

  • สคีม

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

    รูปแบบใหม่สำหรับคำขอ ค่าที่อนุญาตคือ "http", "https", "ftp" และ "chrome-extension"

  • ชื่อผู้ใช้

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

    ชื่อผู้ใช้ใหม่สำหรับคำขอ

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

DYNAMIC_RULESET_ID

รหัสชุดกฎสำหรับกฎแบบไดนามิกที่เพิ่มโดยส่วนขยาย

ค่า

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

ช่วงเวลาที่สามารถโทรออกได้ MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules ครั้ง โดยระบุเป็นนาที การเรียกใช้เพิ่มเติมจะล้มเหลวทันทีและตั้งค่า runtime.lastError หมายเหตุ: การเรียก getMatchedRules ที่เชื่อมโยงกับท่าทางผู้ใช้จะได้รับการยกเว้นจากโควต้า

ค่า

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 ขึ้นไป

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

ค่า

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

จำนวนครั้งที่เรียกใช้ getMatchedRules ได้ภายในระยะเวลา GETMATCHEDRULES_QUOTA_INTERVAL

ค่า

20

MAX_NUMBER_OF_DYNAMIC_RULES

จำนวนกฎแบบไดนามิกสูงสุดที่ส่วนขยายสามารถเพิ่มได้

ค่า

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ขึ้นไป

จำนวนสูงสุดของ Rulesets แบบคงที่ที่ส่วนขยายสามารถเปิดใช้ได้ในแต่ละครั้ง

ค่า

50

MAX_NUMBER_OF_REGEX_RULES

จำนวนกฎนิพจน์ทั่วไปสูงสุดที่ส่วนขยายเพิ่มได้ ระบบจะประเมินขีดจำกัดนี้แยกกันสำหรับชุดกฎแบบไดนามิกและกฎที่ระบุไว้ในไฟล์ทรัพยากรกฎ

ค่า

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ขึ้นไป

จำนวนกฎที่กำหนดขอบเขตเซสชันสูงสุดที่ส่วนขยายสามารถเพิ่มได้

ค่า

5000

MAX_NUMBER_OF_STATIC_RULESETS

จำนวนสูงสุดของ Rulesets แบบคงที่ที่ส่วนขยายสามารถระบุได้เป็นส่วนหนึ่งของคีย์ไฟล์ Manifest "rule_resources"

ค่า

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ขึ้นไป

จำนวนกฎแบบไดนามิกที่ "ไม่ปลอดภัย" สูงสุดที่ส่วนขยายสามารถเพิ่มได้

ค่า

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ขึ้นไป

จำนวนสูงสุดของกฎที่กำหนดขอบเขตเซสชัน "ไม่ปลอดภัย" ที่ส่วนขยายสามารถเพิ่มได้

ค่า

5000

SESSION_RULESET_ID

Chrome 90 ขึ้นไป

รหัสชุดกฎสำหรับกฎระดับเซสชันซึ่งเพิ่มโดยส่วนขยาย

ค่า

"_session"

เมธอด

getAvailableStaticRuleCount()

Promise Chrome 89 ขึ้นไป 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

แสดงผลจำนวนกฎแบบคงที่ที่ส่วนขยายสามารถเปิดใช้ได้ก่อนที่จะถึงขีดจำกัดกฎแบบคงที่ทั่วโลก

พารามิเตอร์

  • callback

    function ไม่บังคับ

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

    (count: number) => void

    • การกวาดแขน

      ตัวเลข

การคืนสินค้า

  • Promise<number>

    Chrome 91 ขึ้นไป

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getDisabledRuleIds()

Promise Chrome 111 ขึ้นไป 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
): Promise<number[]>

แสดงรายการกฎแบบคงที่ใน Ruleset ที่ระบุซึ่งปิดใช้อยู่ในปัจจุบัน

พารามิเตอร์

  • ตัวเลือก

    GetDisabledRuleIdsOptions

    ระบุชุดกฎที่จะค้นหา

  • callback

    function ไม่บังคับ

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

การคืนสินค้า

  • Promise<number[]>

    Promise ที่แก้ไขด้วยรายการรหัสที่สอดคล้องกับกฎที่ปิดใช้ในชุดกฎนั้น

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getDynamicRules()

Promise 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

แสดงผลชุดกฎแบบไดนามิกปัจจุบันสำหรับส่วนขยาย ผู้โทรสามารถเลือกกรองรายการกฎที่ดึงข้อมูลมาได้โดยระบุ filter

พารามิเตอร์

  • ตัวกรอง

    GetRulesFilter ไม่บังคับ

    Chrome 111 ขึ้นไป

    ออบเจ็กต์สำหรับกรองรายการกฎที่ดึงมา

  • callback

    function ไม่บังคับ

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

    (rules: Rule[]) => void

การคืนสินค้า

  • Promise<Rule[]>

    Chrome 91 ขึ้นไป

    Promise ที่แก้ไขด้วยชุดกฎแบบไดนามิก ระบบอาจปฏิเสธ Promise ในกรณีที่เกิดข้อผิดพลาดภายในชั่วคราว

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

แสดงรหัสสำหรับชุดกฎแบบคงที่ที่เปิดใช้ในปัจจุบัน

พารามิเตอร์

  • callback

    function ไม่บังคับ

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

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

การคืนสินค้า

  • Promise<string[]>

    Chrome 91 ขึ้นไป

    Promise ที่แก้ไขด้วยรายการรหัส โดยที่รหัสแต่ละรายการสอดคล้องกับ Ruleset แบบคงที่ที่เปิดใช้

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getMatchedRules()

Promise 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
): Promise<RulesMatchedDetails>

แสดงกฎทั้งหมดที่ตรงกับส่วนขยาย ผู้โทรสามารถเลือกกรองรายการกฎที่ตรงกันได้โดยระบุ filter วิธีนี้ใช้ได้กับส่วนขยายที่มีสิทธิ์ "declarativeNetRequestFeedback" หรือได้รับสิทธิ์ "activeTab" สำหรับ tabId ที่ระบุใน filter เท่านั้น หมายเหตุ: ระบบจะไม่แสดงกฎที่ไม่ได้เชื่อมโยงกับเอกสารที่ใช้งานอยู่ซึ่งมีการจับคู่มากกว่า 5 นาทีที่ผ่านมา

พารามิเตอร์

  • ตัวกรอง

    MatchedRulesFilter ไม่บังคับ

    ออบเจ็กต์สำหรับกรองรายการกฎที่ตรงกัน

  • callback

    function ไม่บังคับ

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

    (details: RulesMatchedDetails) => void

การคืนสินค้า

  • Chrome 91 ขึ้นไป

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

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getSessionRules()

Promise Chrome 90 ขึ้นไป 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

แสดงผลชุดกฎที่กำหนดขอบเขตเซสชันปัจจุบันสำหรับส่วนขยาย ผู้โทรสามารถเลือกกรองรายการกฎที่ดึงข้อมูลมาได้โดยระบุ filter

พารามิเตอร์

  • ตัวกรอง

    GetRulesFilter ไม่บังคับ

    Chrome 111 ขึ้นไป

    ออบเจ็กต์สำหรับกรองรายการกฎที่ดึงมา

  • callback

    function ไม่บังคับ

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

    (rules: Rule[]) => void

การคืนสินค้า

  • Promise<Rule[]>

    Chrome 91 ขึ้นไป

    Promise ที่แก้ไขด้วยชุดกฎที่กำหนดขอบเขตเซสชัน

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

isRegexSupported()

Promise Chrome 87 ขึ้นไป 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): Promise<IsRegexSupportedResult>

ตรวจสอบว่าระบบจะรองรับนิพจน์ทั่วไปที่ระบุเป็นเงื่อนไขของกฎ regexFilter หรือไม่

พารามิเตอร์

  • regexOptions

    RegexOptions

    นิพจน์ทั่วไปที่จะตรวจสอบ

  • callback

    function ไม่บังคับ

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

    (result: IsRegexSupportedResult) => void

การคืนสินค้า

  • Chrome 91 ขึ้นไป

    Promise ที่แก้ไขด้วยรายละเอียดที่ประกอบด้วยข้อมูลว่าระบบรองรับนิพจน์ทั่วไปหรือไม่ และเหตุผลหากไม่รองรับ

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

setExtensionActionOptions()

Promise Chrome 88 ขึ้นไป 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): Promise<void>

กำหนดค่าว่าควรแสดงจำนวนการดำเนินการสำหรับแท็บเป็นข้อความป้ายของการดำเนินการของส่วนขยายหรือไม่ และระบุวิธีเพิ่มจำนวนการดำเนินการนั้น

พารามิเตอร์

  • ตัวเลือก

    ExtensionActionOptions

  • callback

    function ไม่บังคับ

    Chrome 89 ขึ้นไป

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

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 91 ขึ้นไป

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

testMatchOutcome()

Promise Chrome 103 ขึ้นไป 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

ตรวจสอบว่ากฎ declarativeNetRequest ของส่วนขยายตรงกับคำขอสมมติหรือไม่ หมายเหตุ: ใช้ได้กับส่วนขยายที่ไม่ได้แพ็กเท่านั้น เนื่องจากมีไว้เพื่อใช้ในระหว่างการพัฒนาส่วนขยายเท่านั้น

พารามิเตอร์

การคืนสินค้า

  • Promise ที่แก้ไขด้วยรายละเอียดของกฎที่ตรงกัน

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

updateDynamicRules()

Promise 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

แก้ไขชุดกฎแบบไดนามิกปัจจุบันสำหรับส่วนขยาย ระบบจะนำกฎที่มีรหัสที่ระบุไว้ใน options.removeRuleIds ออกก่อน จากนั้นจึงเพิ่มกฎที่ระบุไว้ใน options.addRules หมายเหตุ:

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

พารามิเตอร์

  • ตัวเลือก

    UpdateRuleOptions

    Chrome 87 ขึ้นไป
  • callback

    function ไม่บังคับ

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

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 91 ขึ้นไป

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

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

updateEnabledRulesets()

Promise 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
): Promise<void>

อัปเดตชุดกฎแบบคงที่ที่เปิดใช้สำหรับส่วนขยาย ระบบจะนำชุดกฎที่มีรหัสที่ระบุไว้ใน options.disableRulesetIds ออกก่อน จากนั้นจึงเพิ่มชุดกฎที่ระบุไว้ใน options.enableRulesetIds โปรดทราบว่าชุดกฎแบบคงที่ที่เปิดใช้จะยังคงอยู่ตลอดเซสชัน แต่จะไม่คงอยู่ตลอดการอัปเดตส่วนขยาย กล่าวคือ คีย์ไฟล์ Manifest rule_resources จะกำหนดชุดกฎแบบคงที่ที่เปิดใช้ในการอัปเดตส่วนขยายแต่ละครั้ง

พารามิเตอร์

  • ตัวเลือก

    UpdateRulesetOptions

    Chrome 87 ขึ้นไป
  • callback

    function ไม่บังคับ

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

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 91 ขึ้นไป

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

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

updateSessionRules()

Promise Chrome 90 ขึ้นไป 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

แก้ไขชุดกฎที่กำหนดขอบเขตเซสชันปัจจุบันสำหรับส่วนขยาย ระบบจะนำกฎที่มีรหัสที่ระบุไว้ใน options.removeRuleIds ออกก่อน จากนั้นจึงเพิ่มกฎที่ระบุไว้ใน options.addRules หมายเหตุ:

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

พารามิเตอร์

  • ตัวเลือก

    UpdateRuleOptions

  • callback

    function ไม่บังคับ

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

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 91 ขึ้นไป

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

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

updateStaticRules()

Promise Chrome 111 ขึ้นไป 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
): Promise<void>

ปิดใช้และเปิดใช้กฎแบบคงที่แต่ละข้อใน Ruleset การเปลี่ยนแปลงกฎที่เป็นของ Ruleset ที่ปิดใช้อยู่จะมีผลในครั้งถัดไปที่เปิดใช้

พารามิเตอร์

  • ตัวเลือก

    UpdateStaticRulesOptions

  • callback

    function ไม่บังคับ

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

    () => void

การคืนสินค้า

  • Promise<void>

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

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

เริ่มทำงานเมื่อกฎตรงกับคำขอ ใช้ได้กับส่วนขยายที่ไม่ได้แพ็กซึ่งมีสิทธิ์ "declarativeNetRequestFeedback" เท่านั้น เนื่องจากมีไว้เพื่อใช้สำหรับการแก้ไขข้อบกพร่องเท่านั้น

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (info: MatchedRuleInfoDebug) => void