chrome.declarativeContent

คำอธิบาย

ใช้ 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 จับคู่ตัวเลือกได้อย่างมีประสิทธิภาพมากขึ้น

ตัวเลือกแบบผสม (OK) ตัวเลือกที่ซับซ้อน (ไม่ถูกต้อง)
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

    โมฆะ

    ฟังก์ชัน constructor มีรูปแบบดังนี้ 

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

  • CSS

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

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

  • isBookmarked

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

    Chrome 45 ขึ้นไป

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

  • pageUrl

    UrlFilter ไม่บังคับ

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

RequestContentScript

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

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

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

  • constructor

    โมฆะ

    ฟังก์ชัน 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

    โมฆะ

    ฟังก์ชัน 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

    โมฆะ

    ฟังก์ชัน constructor มีรูปแบบดังนี้ 

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

ShowPageAction

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

โปรดใช้ declarativeContent.ShowAction

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

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

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

  • constructor

    โมฆะ

    ฟังก์ชัน constructor มีรูปแบบดังนี้ 

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

กิจกรรม

onPageChanged

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

เงื่อนไข

PageStateMatcher

การทำงาน

RequestContentScript

SetIcon

ShowPageAction

ShowAction