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.5 หรือ 1.2 เท่า เริ่มได้รับความนิยมมากขึ้น เราจึงขอแนะนำให้คุณเตรียมขนาดสำหรับไอคอนไว้หลายๆ ขนาด การทำเช่นนี้จะช่วยให้ส่วนขยายของคุณรับมือกับการเปลี่ยนแปลงขนาดการแสดงผลไอคอนที่อาจเกิดขึ้นได้ อย่างไรก็ตาม หากระบุเพียงขนาดเดียว คุณจะตั้งค่าคีย์ "default_icon" เป็นสตริงที่มีเส้นทางไปยังไอคอนเดียวแทนพจนานุกรมได้ด้วย

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

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 การตั้งค่านี้จะถือว่าเป็นการตั้งค่าส่วนกลาง การตั้งค่าเฉพาะแท็บจะมีลำดับความสำคัญสูงกว่าการตั้งค่าส่วนกลาง

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

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

ตัวอย่าง

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

แสดงป๊อปอัป

เป็นเรื่องปกติที่ส่วนขยายจะแสดงป๊อปอัปเมื่อผู้ใช้คลิกการทำงานของส่วนขยาย หากต้องการติดตั้งวิธีนี้ในส่วนขยายของคุณเอง ให้ประกาศป๊อปอัปใน 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>

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

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

// 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,
  callback?: function,
)

chrome.action.enable(
  tabId?: number,
  callback?: function,
)

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.action.getUserSettings(
  callback?: function,
)

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

chrome.action.setIcon(
  details: object,
  callback?: function,
)

chrome.action.setPopup(
  details: object,
  callback?: function,
)

chrome.action.setTitle(
  details: object,
  callback?: function,
)

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