chrome.browserAction

تاریخ به‌روزرسانی: 2026-09-25 ربات‌ها: noindex

توضیحات

در دسترس بودن

در شکل زیر، مربع چندرنگ سمت راست نوار آدرس، آیکون مربوط به یک اقدام مرورگر است. یک پنجره‌ی بازشو (popup) در زیر آیکون قرار دارد.

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

مانیفست

اکشن مرورگر خود را در مانیفست افزونه به این صورت ثبت کنید:

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

شما می‌توانید هر اندازه‌ای را برای آیکون مورد استفاده در کروم تعیین کنید و کروم نزدیکترین اندازه را انتخاب کرده و آن را به اندازه مناسب برای پر کردن فضای ۱۶ قسمتی تغییر می‌دهد. با این حال، اگر اندازه دقیق مشخص نشده باشد، این تغییر اندازه می‌تواند باعث از دست رفتن جزئیات آیکون یا تار شدن آن شود.

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

سینتکس قدیمی برای ثبت آیکون پیش‌فرض هنوز پشتیبانی می‌شود:

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

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

یک اکشن مرورگر می‌تواند شامل یک آیکون ، یک راهنمای ابزار ، یک نشان و یک پنجره‌ی بازشو باشد.

آیکون

آیکون‌های عملیاتی مرورگر در کروم، عرض و ارتفاعی برابر با ۱۶ پیکسل (پیکسل مستقل از دستگاه) دارند. آیکون‌های بزرگ‌تر برای تناسب، تغییر اندازه می‌دهند، اما برای بهترین نتیجه، از یک آیکون مربعی با ۱۶ پیکسل استفاده کنید.

شما می‌توانید آیکون را به دو روش تنظیم کنید: استفاده از یک تصویر ثابت یا استفاده از عنصر canvas در HTML5. استفاده از تصاویر ثابت برای برنامه‌های ساده آسان‌تر است، اما می‌توانید با استفاده از عنصر canvas رابط‌های کاربری پویاتری - مانند انیمیشن روان - ایجاد کنید.

تصاویر استاتیک می‌توانند در هر فرمتی که WebKit می‌تواند نمایش دهد، از جمله BMP، GIF، ICO، JPEG یا PNG باشند. برای افزونه‌های unpacked، تصاویر باید در قالب PNG باشند.

برای تنظیم آیکون، از فیلد default_icon مربوط به browser_action در فایل مانیفست استفاده کنید، یا متد browserAction.setIcon را فراخوانی کنید.

برای نمایش صحیح آیکون زمانی که چگالی پیکسل صفحه نمایش (نسبت size_in_pixel / size_in_dip ) متفاوت از ۱ باشد، می‌توان آیکون را به صورت مجموعه‌ای از تصاویر با اندازه‌های مختلف تعریف کرد. تصویر واقعی برای نمایش از بین مجموعه‌ای انتخاب می‌شود که به بهترین شکل با اندازه پیکسل ۱۶ dip مطابقت داشته باشد. مجموعه آیکون می‌تواند شامل هر اندازه‌ای از مشخصات آیکون باشد و کروم مناسب‌ترین آن را انتخاب خواهد کرد.

راهنمای ابزار

برای تنظیم tooltip، از فیلد default_title مربوط به browser_action در فایل manifest استفاده کنید، یا متد browserAction.setTitle را فراخوانی کنید. می‌توانید رشته‌های مختص به زبان را برای فیلد default_title مشخص کنید؛ برای جزئیات بیشتر به Internationalization مراجعه کنید.

نشان

اکشن‌های مرورگر می‌توانند به صورت اختیاری یک نشان (badge) را نمایش دهند - متنی که روی آیکون قرار می‌گیرد. نشان‌ها به‌روزرسانی اکشن مرورگر را برای نمایش مقدار کمی اطلاعات در مورد وضعیت افزونه آسان می‌کنند.

از آنجا که نشان فضای محدودی دارد، باید ۴ کاراکتر یا کمتر داشته باشد.

متن و رنگ نشان را به ترتیب با استفاده از browserAction.setBadgeText و browserAction.setBadgeBackgroundColor تنظیم کنید.

پاپ‌آپ

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

برای افزودن یک پنجره پاپ‌آپ به اکشن مرورگر خود، یک فایل HTML با محتوای پنجره ایجاد کنید. فایل HTML را در فیلد default_popup از browser_action در مانیفست مشخص کنید، یا متد browserAction.setPopup را فراخوانی کنید.

نکات

برای بهترین تاثیر بصری، این دستورالعمل‌ها را دنبال کنید:

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

مثال‌ها

می‌توانید مثال‌های ساده‌ای از استفاده از اکشن‌های مرورگر را در دایرکتوری examples/api/browserAction بیابید. برای مثال‌های دیگر و کمک در مشاهده کد منبع، به Samples مراجعه کنید.

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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