مرورگر.اکشن

توضیحات

در دسترس بودن

مانیفست

برای استفاده از API browser.action ، مقدار "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" را فعال کنید.

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

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

آیکون

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

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

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

همچنین می‌توانید action.setIcon() را برای تنظیم آیکون افزونه خود به صورت برنامه‌نویسی شده با مشخص کردن یک مسیر تصویر متفاوت یا ارائه یک آیکون تولید شده پویا با استفاده از عنصر canvas در HTML یا در صورت تنظیم از طریق یک سرویس دهنده افزونه، از طریق API 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);
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 مورد نظر شما باشد و به طور خودکار متناسب با محتوای آن تغییر اندازه می‌دهد. اندازه پنجره پاپ‌آپ باید بین ۲۵x۲۵ تا ۸۰۰x۶۰۰ پیکسل باشد.

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

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

وضعیت هر تب

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

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() کنترل کنید. این فقط بر ارسال رویداد popup (در صورت وجود) یا action.onClicked به افزونه شما تأثیر می‌گذارد؛ این موضوع بر حضور action در نوار ابزار تأثیری ندارد.

مثال‌ها

مثال‌های زیر برخی از روش‌های رایج استفاده از اکشن‌ها در افزونه‌ها را نشان می‌دهند. برای امتحان کردن این API، نمونه Action API را از مخزن chrome-extension-samples نصب کنید.

نمایش یک پنجره پاپ‌آپ

نمایش یک پنجره پاپ‌آپ هنگام کلیک کاربر روی اکشن افزونه امری رایج است. برای پیاده‌سازی این مورد در افزونه خودتان، پنجره پاپ‌آپ را در manifest.json خود تعریف کنید و محتوایی را که کروم باید در پنجره پاپ‌آپ نمایش دهد، مشخص کنید.

// 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 برای فعال کردن آن عمل در سایت‌های خاص استفاده کند.

// 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);
  });
});

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