chrome.action

توضیحات

در دسترس بودن

آشکار

برای استفاده از chrome.action API، "manifest_version" 3 را مشخص کنید و کلید "action" را در فایل مانیفست خود بگنجانید.

{
  "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" را وارد کنید.

مفاهیم و کاربرد

بخش هایی از رابط کاربری

نماد

این نماد تصویر اصلی در نوار ابزار برنامه افزودنی شما است و توسط کلید "default_icon" در کلید "action" مانیفست شما تنظیم می شود. نمادها باید 16 پیکسل مستقل از دستگاه (DIP) عرض و بلند داشته باشند.

کلید "default_icon" یک فرهنگ لغت از اندازه مسیرهای تصویر است. کروم از این نمادها برای انتخاب مقیاس تصویر استفاده می کند. اگر مطابقت دقیقی پیدا نشد، Chrome نزدیک‌ترین مورد موجود را انتخاب می‌کند و آن را متناسب با تصویر مقیاس می‌دهد، که ممکن است بر کیفیت تصویر تأثیر بگذارد.

از آنجایی که دستگاه‌هایی با فاکتورهای مقیاس کمتر رایج مانند 1.5x یا 1.2x رایج‌تر می‌شوند، توصیه می‌کنیم اندازه‌های متعددی را برای نمادهای خود ارائه دهید. این همچنین برنامه افزودنی شما را در برابر تغییرات بالقوه اندازه نمایش نمادها محافظت می کند. با این حال، اگر فقط یک اندازه را ارائه کند، کلید "default_icon" همچنین می تواند به جای دیکشنری روی یک رشته با مسیر یک نماد واحد تنظیم شود.

همچنین می‌توانید action.setIcon() را فراخوانی کنید تا نماد برنامه افزودنی خود را با مشخص کردن یک مسیر تصویر متفاوت یا ارائه یک نماد ایجاد شده به صورت پویا با استفاده از عنصر بوم HTML ، یا، در صورت تنظیم از یک کارگر خدمات افزودنی، API بوم خارج از صفحه ، به صورت برنامه‌نویسی تنظیم کنید.

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() آن را به صورت برنامه نویسی تنظیم کنید.

نشان

کنش‌ها می‌توانند به‌صورت اختیاری یک «نشان» را نمایش دهند - کمی متن لایه‌بندی شده روی نماد. این به شما امکان می‌دهد تا عملکرد را به‌روزرسانی کنید تا مقدار کمی از اطلاعات در مورد وضعیت برنامه افزودنی، مانند شمارنده، نمایش داده شود. نشان دارای یک جزء متن و یک رنگ پس زمینه است. از آنجایی که فضا محدود است، توصیه می کنیم متن نشان از چهار یا کمتر نویسه استفاده کند.

برای ایجاد یک نشان، با فراخوانی action.setBadgeBackgroundColor() و action.setBadgeText() آن را به صورت برنامه نویسی تنظیم کنید. تنظیم نشان پیش‌فرض در مانیفست وجود ندارد. مقادیر رنگ نشان می تواند آرایه ای از چهار عدد صحیح بین 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 در روش‌های تنظیم 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-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>

یک اسکریپت محتوا را روی کلیک تزریق کنید

یک الگوی رایج برای برنامه‌های افزودنی این است که ویژگی اصلی خود را با استفاده از عملکرد برنامه افزودنی نمایش دهند. مثال زیر این الگو را نشان می دهد. هنگامی که کاربر روی عملکرد کلیک می کند، برنامه افزودنی یک اسکریپت محتوا را به صفحه فعلی تزریق می کند. سپس اسکریپت محتوا یک هشدار نمایش می دهد تا تأیید کند که همه چیز مطابق انتظار کار می کند.

// 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!');

شبیه سازی اقدامات با محتوای اعلامی

این مثال نشان می‌دهد که چگونه منطق پس‌زمینه یک برنامه افزودنی می‌تواند (الف) یک عملکرد را به طور پیش‌فرض غیرفعال کند و (ب) از محتوای اعلامی برای فعال کردن عملکرد در سایت‌های خاص استفاده کند.

// 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,
)

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