chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

ใช้ chrome.declarativeContent API เพื่อดำเนินการตามเนื้อหาของหน้าเว็บโดยไม่ต้องมีสิทธิ์อ่านเนื้อหาของหน้าเว็บ

สิทธิ์

declarativeContent

การใช้งาน

Declarative Content API ช่วยให้คุณเปิดใช้การดำเนินการของส่วนขยายได้โดยขึ้นอยู่กับ URL ของ หน้าเว็บ หรือหากตัวเลือก CSS ตรงกับองค์ประกอบในหน้าเว็บ โดยไม่ต้อง เพิ่มสิทธิ์เข้าถึงโฮสต์หรือแทรกสคริปต์เนื้อหา

ใช้สิทธิ์ activeTab เพื่อโต้ตอบกับหน้าเว็บหลังจากที่ผู้ใช้คลิกการดำเนินการของส่วนขยาย

กติกา

กฎประกอบด้วยเงื่อนไขและการดำเนินการ หากเป็นไปตามเงื่อนไขใดเงื่อนไขหนึ่ง ระบบจะดำเนินการทั้งหมด การดำเนินการคือ setIcon และ showAction

PageStateMatcher จะจับคู่หน้าเว็บก็ต่อเมื่อตรงตามเกณฑ์ทั้งหมดที่ระบุไว้ เท่านั้น โดยอาจตรงกับ URL ของหน้าเว็บ ตัวเลือก CSS แบบผสม หรือสถานะที่คั่นหน้าของหน้าเว็บ กฎต่อไปนี้จะเปิดใช้ การดำเนินการของส่วนขยายในหน้า Google เมื่อมีช่องรหัสผ่าน

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

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

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

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

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

เมื่อมีสิทธิ์ activeTab ส่วนขยายจะไม่แสดงคำเตือนเรื่องสิทธิ์ และเมื่อผู้ใช้คลิกการดำเนินการของส่วนขยาย ส่วนขยายจะทํางานในหน้าเว็บที่เกี่ยวข้องเท่านั้น

การจับคู่ URL ของหน้าเว็บ

PageStateMatcher.pageurl จะตรงกันเมื่อเป็นไปตามเกณฑ์ URL เกณฑ์ที่พบบ่อยที่สุดคือการเชื่อมโยงของโฮสต์ เส้นทาง หรือ URL ตามด้วย มี เท่ากับ คำนำหน้า หรือ คำต่อท้าย ตารางต่อไปนี้แสดงตัวอย่างบางส่วน

เกณฑ์ การจับคู่
{ hostSuffix: 'google.com' } URL ของ Google ทั้งหมด
{ pathPrefix: '/docs/extensions' } URL เอกสารประกอบส่วนขยาย
{ urlContains: 'developer.chrome.com' } URL ของเอกสารสำหรับนักพัฒนาซอฟต์แวร์ Chrome ทั้งหมด

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

การจับคู่ CSS

เงื่อนไข PageStateMatcher.css ต้องเป็นตัวเลือกแบบผสม ซึ่งหมายความว่าคุณไม่สามารถใส่ตัวรวม เช่น ช่องว่างหรือ ">" ในตัวเลือก ได้ ซึ่งจะช่วยให้ Chrome จับคู่ตัวเลือกได้อย่างมีประสิทธิภาพมากขึ้น

ตัวเลือกแบบผสม (ตกลง) ตัวเลือกที่ซับซ้อน (ไม่ถูกต้อง)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

เงื่อนไข CSS จะตรงกับองค์ประกอบที่แสดงเท่านั้น หากองค์ประกอบที่ตรงกับตัวเลือกของคุณเป็น display:none หรือองค์ประกอบหลักรายการใดรายการหนึ่งเป็น display:none ก็จะไม่ทำให้เงื่อนไขตรงกัน องค์ประกอบที่จัดรูปแบบด้วย visibility:hidden, วางตำแหน่งนอกหน้าจอ หรือซ่อนโดยองค์ประกอบอื่นๆ ยังคงทำให้เงื่อนไขตรงกันได้

การจับคู่สถานะที่ทำบุ๊กมาร์ก

เงื่อนไข PageStateMatcher.isBookmarked ช่วยให้จับคู่สถานะ ที่คั่นหน้าของ URL ปัจจุบันในโปรไฟล์ของผู้ใช้ได้ หากต้องการใช้เงื่อนไขนี้ คุณต้องประกาศสิทธิ์ "บุ๊กมาร์ก" ในไฟล์ Manifest ของส่วนขยาย

ประเภท

ประเภท

ImageData

PageStateMatcher

จับคู่สถานะของหน้าเว็บตามเกณฑ์ต่างๆ

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

  • เครื่องมือสร้าง

    เป็นโมฆะ

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

    (arg: PageStateMatcher) => {...}

  • CSS

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

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

  • isBookmarked

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

    Chrome 45 ขึ้นไป

    ตรงกันหากสถานะที่คั่นหน้าของหน้าเว็บเท่ากับค่าที่ระบุ ต้องมีสิทธิ์เข้าถึงบุ๊กมาร์ก

  • pageUrl

    UrlFilter ไม่บังคับ

    ตรงกันหากเป็นไปตามเงื่อนไขของ UrlFilter สำหรับ URL ระดับบนสุดของหน้า

RequestContentScript

การดำเนินการของเหตุการณ์แบบประกาศที่แทรก Content Script

คำเตือน: การดำเนินการนี้ยังอยู่ในขั้นทดลองและไม่รองรับในบิลด์ที่เสถียรของ Chrome

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

  • เครื่องมือสร้าง

    เป็นโมฆะ

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

    (arg: RequestContentScript) => {...}

  • allFrames

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

    ไม่ว่า Content Script จะทำงานในเฟรมทั้งหมดของหน้าที่ตรงกันหรือเฉพาะในเฟรมบนสุด ค่าเริ่มต้นคือ false

  • CSS

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

    ชื่อไฟล์ CSS ที่จะแทรกเป็นส่วนหนึ่งของ Content Script

  • js

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

    ชื่อของไฟล์ JavaScript ที่จะแทรกเป็นส่วนหนึ่งของสคริปต์เนื้อหา

  • matchAboutBlank

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

    จะแทรกสคริปต์เนื้อหาใน about:blank และ about:srcdoc หรือไม่ ค่าเริ่มต้นคือ false

SetIcon

การดำเนินการของเหตุการณ์แบบประกาศที่ตั้งค่าไอคอนสี่เหลี่ยม n-dip สำหรับการดำเนินการในหน้าเว็บหรือการดำเนินการของเบราว์เซอร์ของส่วนขยายในขณะที่ตรงตามเงื่อนไขที่เกี่ยวข้อง การดำเนินการนี้ใช้ได้โดยไม่ต้องมีสิทธิ์ของโฮสต์ แต่ส่วนขยายต้องมีการดำเนินการในหน้าเว็บหรือเบราว์เซอร์

ต้องระบุ imageData หรือ path อย่างใดอย่างหนึ่ง ทั้ง 2 อย่างเป็นพจนานุกรมที่แมปจำนวนพิกเซลกับการแสดงรูปภาพ การแสดงรูปภาพใน imageData คือออบเจ็กต์ ImageData เช่น จากองค์ประกอบ canvas ในขณะที่การแสดงรูปภาพใน path คือเส้นทางไปยังไฟล์รูปภาพที่เกี่ยวข้องกับไฟล์ Manifest ของส่วนขยาย หากscaleพิกเซลหน้าจอพอดีกับพิกเซลที่ไม่ขึ้นกับอุปกรณ์ ระบบจะใช้ไอคอน scale * n หากไม่มีมาตราส่วนดังกล่าว ระบบจะปรับขนาดรูปภาพอื่นให้เป็นขนาดที่ต้องการ

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

  • เครื่องมือสร้าง

    เป็นโมฆะ

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

    (arg: SetIcon) => {...}

    • อาร์กิวเมนต์

      SetIcon

  • imageData

    ImageData | ออบเจ็กต์ ไม่บังคับ

    ออบเจ็กต์ ImageData หรือพจนานุกรม {size -> ImageData} ที่แสดงไอคอนที่จะตั้งค่า หากระบุไอคอนเป็นพจนานุกรม ระบบจะเลือกรูปภาพที่ใช้ตามความหนาแน่นของพิกเซลของหน้าจอ หากจำนวนพิกเซลของรูปภาพที่พอดีกับหน่วยพื้นที่หน้าจอ 1 หน่วยเท่ากับ scale ระบบจะเลือกรูปภาพที่มีขนาด scale * n โดยที่ n คือขนาดของไอคอนใน UI ต้องระบุรูปภาพอย่างน้อย 1 รูป โปรดทราบว่า details.imageData = foo เทียบเท่ากับ details.imageData = {'16': foo}

ShowAction

Chrome 97 ขึ้นไป

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

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

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

  • เครื่องมือสร้าง

    เป็นโมฆะ

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

    (arg: ShowAction) => {...}

ShowPageAction

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

โปรดใช้ declarativeContent.ShowAction

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

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

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

  • เครื่องมือสร้าง

    เป็นโมฆะ

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

    (arg: ShowPageAction) => {...}

กิจกรรม

onPageChanged

มี Declarative Event API ซึ่งประกอบด้วย addRules, removeRules และ getRules

เงื่อนไข

PageStateMatcher

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

RequestContentScript

SetIcon

ShowPageAction

ShowAction