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 ด้วยวิดีโอ คุณสามารถเพิ่ม เงื่อนไข เนื่องจากแต่ละเงื่อนไขเพียงพอที่จะทริกเกอร์การดำเนินการที่ระบุทั้งหมด ดังนี้

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 ตามด้วย มี เท่ากับ คำนำหน้า หรือ คำต่อท้าย ตารางต่อไปนี้ประกอบด้วยตัวอย่าง 2-3 ข้อ

เกณฑ์ ตรงกับ
{ 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

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

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

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

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

    เป็นโมฆะ

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

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

  • allFrames

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

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

  • CSS

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

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

  • JS

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

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

  • matchAboutBlank

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

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

SetIcon

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

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

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

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

    เป็นโมฆะ

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

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

    • อาร์กิวเมนต์
  • ข้อมูลรูปภาพ

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

    ออบเจ็กต์ ImageData หรือพจนานุกรม {size -> ImageData} แสดงไอคอนที่จะตั้งค่า หากระบุไอคอนเป็นพจนานุกรม ระบบจะเลือกรูปภาพที่ใช้โดยขึ้นอยู่กับความหนาแน่นของพิกเซลของหน้าจอ หากจำนวนพิกเซลรูปภาพที่มีขนาดพอดีกับหน่วยพื้นที่หน้าจอหนึ่งเท่ากับ scale ระบบจะเลือกรูปภาพที่มีขนาด scale * n โดยที่ n คือขนาดของไอคอนใน UI ต้องระบุรูปภาพอย่างน้อยหนึ่งภาพ โปรดทราบว่า 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

เงื่อนไข