browser.action

شرح

دردسترس بودن

مانیفست

برای استفاده از میانای برنامه‌سازی کاربردی browser.action، "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" مانیفست شما تنظیم می‌شود. نمادها باید ۱۶ پیکسل مستقل از دستگاه (DIP) عرض و ارتفاع داشته باشند.

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

ازآنجایی‌که دستگاه‌هایی با ضریب مقیاس کمتر رایج مانند ۱٫۵ برابر یا ۱٫۲ برابر درحال رایج‌تر شدن هستند، توصیه می‌کنیم چندین اندازه برای نمادهایتان ارائه دهید. این کار همچنین افزونه شما را دربرابر تغییرات احتمالی اندازه نمایش نماد در آینده مقاوم می‌کند. اما اگر فقط یک اندازه ارائه شود، کلید "default_icon" را می‌توان به‌جای واژه‌نامه روی رشته‌ای با مسیر یک نماد تنظیم کرد.

You can also call action.setIcon() to set your extension's icon programmatically by specifying a different image path or providing a dynamically-generated icon using the HTML canvas element, or, if setting from an extension service worker, the offscreen canvas 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);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });

برای افزونه‌های بسته‌بندی‌شده (نصب‌شده از فایل crx.)، تصاویر می‌توانند در اکثر قالب‌هایی باشند که موتور پردازش Blink می‌تواند نمایش دهد، ازجمله PNG،‏ JPEG،‏ BMP،‏ ICO، و غیره. SVG پشتیبانی نمی‌شود. افزونه‌های از حالت فشرده خارج‌شده باید از تصاویر PNG استفاده کنند.

نکته‌ابزار (عنوان)

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

نکته‌ابزار پیش‌فرض بااستفاده از فیلد "default_title" کلید "action" در manifest.json تنظیم می‌شود. همچنین می‌توانید آن را به‌صورت برنامه‌نویسی با فراخوانی action.setTitle() تنظیم کنید.

نشان

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

برای ایجاد نشان، آن را به‌صورت برنامه‌ریزی‌شده با فراخوانی action.setBadgeBackgroundColor() و action.setBadgeText() تنظیم کنید. تنظیم نشان پیش‌فرضی در مانیفست وجود ندارد. مقادیر رنگ نشان می‌تواند آرایه‌ای از چهار عدد صحیح بین ۰ و ۲۵۵ باشد که رنگ RGBA نشان را تشکیل می‌دهد یا رشته‌ای با مقدار رنگ CSS باشد.

browser.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

بازشو

وقتی کاربر روی دکمه کنش افزونه در نوارابزار کلیک می‌کند، بالاپر کنش نشان داده می‌شود. پنجره بالاپر می‌تواند حاوی هر محتوای HTML که دوست دارید باشد و به‌طور خودکار برای تناسب با محتوایش تغییر اندازه می‌دهد. اندازه بالاپر باید بین ۲۵×۲۵ و ۸۰۰×۶۰۰ پیکسل باشد.

بالاپر در ابتدا توسط ویژگی "default_popup" در کلید "action" در فایل manifest.json تنظیم می‌شود. درصورت وجود، این ویژگی باید به مسیر نسبی در دایرکتوری افزونه اشاره کند. همچنین می‌توان آن را به‌صورت پویا به‌روزرسانی کرد تا بااستفاده از روش action.setPopup() به مسیر نسبی دیگری اشاره کند.

موارد استفاده

وضعیت هر برگه

کنش‌های افزونه می‌تواند برای هر برگه حالت‌های متفاوتی داشته باشد. برای تنظیم مقدار برای یک برگه جداگانه، از ویژگی tabId در روش‌های تنظیم action API استفاده کنید. برای مثال، برای تنظیم نوشتار نشان برای برگه‌ای خاص، کاری شبیه به این انجام دهید:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

browser.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

اگر خصوصیت tabId حذف شود، تنظیم به‌عنوان تنظیم جهانی درنظر گرفته می‌شود. تنظیمات مختص برگه بر تنظیمات کلی اولویت دارد.

حالت فعال‌شده

به‌طور پیش‌فرض، کنش‌های نوارابزار در هر برگه فعال (قابل‌کلیک) هستند. می‌توانید این پیش‌فرض را با تنظیم ویژگی default_state در کلید action مانیفست تغییر دهید. اگر default_state روی "disabled" تنظیم شده باشد، کنش به‌طور پیش‌فرض غیرفعال است و باید به‌صورت برنامه‌نویسی‌شده فعال شود تا قابل‌کلیک باشد. اگر default_state روی "enabled" (پیش‌فرض) تنظیم شده باشد، کنش به‌طور پیش‌فرض فعال و قابل‌کلیک است.

می‌توانید وضعیت را به‌صورت برنامه‌نویسی بااستفاده از روش‌های action.enable() و action.disable() کنترل کنید. این فقط بر ارسال شدن یا نشدن بالاپر (درصورت وجود) یا رویداد action.onClicked به افزونه شما تأثیر می‌گذارد؛ بر حضور کنش در نوارابزار تأثیری ندارد.

مثال‌ها

نمونه‌های زیر برخی‌از روش‌های رایج استفاده از کنش‌ها در افزونه‌ها را نشان می‌دهد. برای امتحان کردن این میانای برنامه‌سازی کاربردی، نمونه میانای برنامه‌سازی کاربردی Action را از مخزن 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
browser.action.onClicked.addListener((tab) => {
  browser.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
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.declarativeContent.onPageChanged.addRules(rules);
  });
});

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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