chrome.action

คำอธิบาย

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

ไฟล์ Manifest

หากต้องการใช้ chrome.action API ให้ระบุ "manifest_version" เป็น 3 และใส่คีย์ "action" ในไฟล์ Manifest

{   "name": "Action Extension",   ...   "action": {     "default_icon": {              // optional       "16": "images/icon16.png",   // optional       "24": "images/icon24.png",   // optional       "32": "images/icon32.png"    // optional     },     "default_title": "Click Me",   // optional, shown in tooltip     "default_popup": "popup.html"  // optional   },   ... } 

คีย์ "action" (พร้อมกับคีย์ย่อย) เป็นค่าที่ไม่บังคับ หากไม่ได้ระบุไว้ ส่วนขยายจะยังคงแสดงในแถบเครื่องมือเพื่อให้เข้าถึงเมนูของส่วนขยายได้ ด้วยเหตุนี้ เราจึงขอแนะนำให้คุณใส่คีย์ "action" และ "default_icon" อย่างน้อยเสมอ

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

ส่วนต่างๆ ของ UI

Icon

ไอคอนคือรูปภาพหลักในแถบเครื่องมือของส่วนขยาย และตั้งค่าโดยคีย์ "default_icon" ในคีย์ "action" ของไฟล์ Manifest ไอคอนต้องมีความกว้างและความสูง 16 พิกเซลอิสระของอุปกรณ์ (DIP)

"default_icon"คีย์คือพจนานุกรมของขนาดไปยังเส้นทางรูปภาพ Chrome ใช้ไอคอนเหล่านี้ เพื่อเลือกขนาดรูปภาพที่จะใช้ หากไม่พบรายการที่ตรงกันทั้งหมด Chrome จะเลือกรายการที่ใกล้เคียงที่สุด และปรับขนาดให้พอดีกับรูปภาพ ซึ่งอาจส่งผลต่อคุณภาพของรูปภาพ

เนื่องจากอุปกรณ์ที่มีปัจจัยการปรับขนาดที่ไม่ค่อยพบ เช่น 1.5x หรือ 1.2x กำลังได้รับความนิยมมากขึ้น เราจึงขอแนะนำให้คุณระบุไอคอนหลายขนาด นอกจากนี้ยังช่วยให้ส่วนขยายของคุณพร้อมรับมือกับการเปลี่ยนแปลงขนาดการแสดงไอคอนที่อาจเกิดขึ้นในอนาคตด้วย อย่างไรก็ตาม หากระบุเพียงขนาดเดียว คุณจะตั้งค่าคีย์ "default_icon" เป็นสตริงที่มีเส้นทางไปยังไอคอนเดียวแทนพจนานุกรมได้ด้วย

นอกจากนี้ คุณยังเรียกใช้ action.setIcon() เพื่อตั้งค่าไอคอนของส่วนขยายแบบเป็นโปรแกรมได้ โดยการระบุเส้นทางรูปภาพอื่น หรือระบุไอคอนที่สร้างแบบไดนามิกโดยใช้องค์ประกอบ Canvas HTML หรือหากตั้งค่าจาก Service Worker ของส่วนขยาย ก็ใช้ API Offscreen Canvas ได้

const canvas = new OffscreenCanvas(16, 16); const context = canvas.getContext('2d'); context.clearRect(0, 0, 16, 16); context.fillStyle = '#00FF00';  // Green context.fillRect(0, 0, 16, 16); const imageData = context.getImageData(0, 0, 16, 16); chrome.action.setIcon({imageData: imageData}, () => { /* ... */ }); 

สำหรับส่วนขยายที่แพ็ก (ติดตั้งจากไฟล์ .crx) รูปภาพจะอยู่ในรูปแบบส่วนใหญ่ที่เครื่องมือแสดงผล Blink แสดงได้ ซึ่งรวมถึง PNG, JPEG, BMP, ICO และอื่นๆ ไม่รองรับ SVG ส่วนขยายที่ไม่ได้แพ็กต้องใช้รูปภาพ PNG

เคล็ดลับเครื่องมือ (ชื่อ)

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

ระบบจะตั้งค่าเคล็ดลับเริ่มต้นโดยใช้ฟิลด์ "default_title" ของคีย์ "action" ใน manifest.json นอกจากนี้ คุณยังตั้งค่าโดยใช้โปรแกรมได้ด้วยการเรียกใช้ action.setTitle()

ป้าย

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

หากต้องการสร้างป้าย ให้ตั้งค่าแบบเป็นโปรแกรมโดยเรียกใช้ action.setBadgeBackgroundColor() และ action.setBadgeText() ไม่มีการตั้งค่าป้ายเริ่มต้นในไฟล์ Manifest ค่าสีของป้าย อาจเป็นอาร์เรย์ของจำนวนเต็ม 4 รายการระหว่าง 0 ถึง 255 ที่ประกอบกันเป็นสี RGBA ของ ป้าย หรือสตริงที่มีค่าสี CSS

chrome.action.setBadgeBackgroundColor(   {color: [0, 255, 0, 0]},  // Green   () => { /* ... */ }, );  chrome.action.setBadgeBackgroundColor(   {color: '#00FF00'},  // Also green   () => { /* ... */ }, );  chrome.action.setBadgeBackgroundColor(   {color: 'green'},  // Also, also green   () => { /* ... */ }, ); 

ป๊อปอัป

ป๊อปอัปของการดำเนินการจะแสดงเมื่อผู้ใช้คลิกปุ่มการดำเนินการของส่วนขยายใน แถบเครื่องมือ ป๊อปอัปอาจมีเนื้อหา HTML ใดก็ได้ที่คุณต้องการ และจะปรับขนาดโดยอัตโนมัติให้พอดีกับเนื้อหา ป๊อปอัปต้องมีขนาดระหว่าง 25x25 ถึง 800x600 พิกเซล

โดยค่าเริ่มต้น ป๊อปอัปจะตั้งค่าโดยพร็อพเพอร์ตี้ "default_popup" ในคีย์ "action" ในไฟล์ manifest.json หากมี พร็อพเพอร์ตี้นี้ควรชี้ไปยังเส้นทางแบบสัมพัทธ์ภายในไดเรกทอรีส่วนขยาย นอกจากนี้ ยังอัปเดตแบบไดนามิกให้ชี้ไปยังเส้นทางแบบสัมพัทธ์อื่นได้โดยใช้เมธอด action.setPopup()

กรณีการใช้งาน

สถานะต่อแท็บ

การดำเนินการของส่วนขยายอาจมีสถานะแตกต่างกันสำหรับแต่ละแท็บ หากต้องการตั้งค่าสำหรับแท็บแต่ละรายการ ให้ใช้พร็อพเพอร์ตี้ tabId ในเมธอดการตั้งค่าของ API action เช่น หากต้องการ ตั้งค่าข้อความป้ายสำหรับแท็บที่เฉพาะเจาะจง ให้ทำดังนี้

function getTabId() { /* ... */} function getTabBadge() { /* ... */}  chrome.action.setBadgeText(   {     text: getTabBadge(tabId),     tabId: getTabId(),   },   () => { ... } ); 

หากละเว้นพร็อพเพอร์ตี้ tabId ระบบจะถือว่าการตั้งค่าเป็นการตั้งค่าส่วนกลาง การตั้งค่าเฉพาะแท็บ จะมีความสำคัญมากกว่าการตั้งค่าส่วนกลาง

สถานะที่เปิดใช้

โดยค่าเริ่มต้น การดำเนินการในแถบเครื่องมือจะเปิดใช้ (คลิกได้) ในทุกแท็บ คุณเปลี่ยนค่าเริ่มต้นนี้ได้ โดยตั้งค่าพร็อพเพอร์ตี้ default_state ในคีย์ action ของไฟล์ Manifest หากตั้งค่า default_state เป็น "disabled" ระบบจะปิดใช้การดำเนินการโดยค่าเริ่มต้นและต้องเปิดใช้ แบบเป็นโปรแกรมเพื่อให้คลิกได้ หากตั้งค่า default_state เป็น "enabled" (ค่าเริ่มต้น) ระบบจะเปิดใช้การดำเนินการและคลิกได้โดยค่าเริ่มต้น

คุณควบคุมสถานะได้โดยใช้เมธอด action.enable() และ action.disable() ซึ่งจะส่งผลต่อการส่งป๊อปอัป (หากมี) หรือเหตุการณ์ action.onClicked ไปยังส่วนขยายเท่านั้น และจะไม่ส่งผลต่อการแสดงการดำเนินการในแถบเครื่องมือ

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงวิธีทั่วไปบางอย่างที่ใช้การดำเนินการในส่วนขยาย หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง Action API จากที่เก็บchrome-extension-samples

แสดงป๊อปอัป

โดยปกติแล้วส่วนขยายจะแสดงป๊อปอัปเมื่อผู้ใช้คลิกการดำเนินการของส่วนขยาย หากต้องการ ใช้ฟีเจอร์นี้ในส่วนขยายของคุณเอง ให้ประกาศป๊อปอัปใน manifest.json และระบุ เนื้อหาที่ Chrome ควรแสดงในป๊อปอัป

// manifest.json {   "name": "Action popup demo",   "version": "1.0",   "manifest_version": 3,   "action": {     "default_title": "Click to view a popup",     "default_popup": "popup.html"   } } 

<!-- popup.html --> <!DOCTYPE html> <html> <head>   <style>     html {       min-height: 5em;       min-width: 10em;       background: salmon;     }   </style> </head> <body>   <p>Hello, world!</p> </body> </html> 

แทรกสคริปต์เนื้อหาเมื่อคลิก

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

// manifest.json {   "name": "Action script injection demo",   "version": "1.0",   "manifest_version": 3,   "action": {     "default_title": "Click to show an alert"   },   "permissions": ["activeTab", "scripting"],   "background": {     "service_worker": "background.js"   } } 

// background.js chrome.action.onClicked.addListener((tab) => {   chrome.scripting.executeScript({     target: {tabId: tab.id},     files: ['content.js']   }); }); 

// content.js alert('Hello, world!'); 

เลียนแบบการดำเนินการด้วย declarativeContent

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

// service-worker.js  // Wrap in an onInstalled callback to avoid unnecessary work // every time the service worker is run chrome.runtime.onInstalled.addListener(() => {   // Page actions are disabled by default and enabled on select tabs   chrome.action.disable();    // Clear all rules to ensure only our expected rules are set   chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {     // Declare a rule to enable the action on example.com pages     let exampleRule = {       conditions: [         new chrome.declarativeContent.PageStateMatcher({           pageUrl: {hostSuffix: '.example.com'},         })       ],       actions: [new chrome.declarativeContent.ShowAction()],     };      // Finally, apply our new array of rules     let rules = [exampleRule];     chrome.declarativeContent.onPageChanged.addRules(rules);   }); }); 

chrome.action.disable(
  tabId?: number,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

chrome.action.onClicked.addListener(
  callback: function,
)

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)