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 Sites ที่มีวิดีโอด้วย คุณสามารถเพิ่มเงื่อนไขที่ 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

    void

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

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

  • CSS

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

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

  • isBookmarked

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

    Chrome 45 ขึ้นไป

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

  • pageUrl

    UrlFilter ไม่บังคับ

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

RequestContentScript

การดำเนินการของเหตุการณ์ที่ประกาศซึ่งแทรกสคริปต์เนื้อหา

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

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

  • constructor

    void

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

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

  • allFrames

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

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

  • CSS

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

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

  • js

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

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

  • matchAboutBlank

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

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

SetIcon

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

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

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

  • constructor

    void

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

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

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

      SetIcon

  • imageData

    ImageData | object ไม่บังคับ

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

ShowAction

Chrome 97 ขึ้นไป

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

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

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

  • constructor

    void

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

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

ShowPageAction

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

โปรดใช้ declarativeContent.ShowAction

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

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

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

  • constructor

    void

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

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

กิจกรรม

onPageChanged

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

เงื่อนไข

PageStateMatcher

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

RequestContentScript

SetIcon

ShowPageAction

ShowAction