chrome.browserAction

refresh date: 2026-09-25 robots: noindex

شرح

از کنش‌های مرورگر برای قرار دادن نمادها در نوارابزار اصلی Google Chrome، در سمت چپ نوار نشانی استفاده کنید. علاوه‌بر نماد، کنش مرورگر می‌تواند نکته‌ابزار، نشان، و بالاپر داشته باشد.

دردسترس بودن

≤ MV2

در شکل زیر، مربع چندرنگ در سمت چپ نوار نشانی نماد کنش مرورگر است. بالاپری زیر نماد قرار دارد.

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

مانیفست

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

{
  "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
  },
  ...
}

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

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

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

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

بخش‌هایی از میانای کاربر

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

نماد

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

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

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

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

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

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

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

نشان

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

چون نشان فضای محدودی دارد، باید ۴ نویسه یا کمتر داشته باشد.

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

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

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

نکته‌ها

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

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

مثال‌ها

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

انواع

TabDetails

Chrome نسخه ۸۸ و بالاتر

مشخصات

  • tabId

    شماره اختیاری

    شناسه برگه‌ای که وضعیت آن پرس‌وجو می‌شود. اگر برگه‌ای مشخص نشده باشد، وضعیت غیرمختص برگه برگردانده می‌شود.

روش‌ها

disable()

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

کنش مرورگر را برای برگه غیرفعال می‌کند.

پارامترها

  • tabId

    شماره اختیاری

    شناسه برگه‌ای که کنش مرورگر برای آن اصلاح می‌شود.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۶۷ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

enable()

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

کنش مرورگر را برای برگه فعال می‌کند. به‌طور پیش‌فرض فعال است.

پارامترها

  • tabId

    شماره اختیاری

    شناسه برگه‌ای که کنش مرورگر برای آن اصلاح می‌شود.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۶۷ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getBadgeBackgroundColor()

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

رنگ پس‌زمینه کنش مرورگر را دریافت می‌کند.

پارامترها

  • جزئیات

    TabDetails

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (result: ColorArray) => void

بازگشتی‌ها

  • Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getBadgeText()

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

نوشتار نشان کنش مرورگر را دریافت می‌کند. اگر برگه‌ای مشخص نشده باشد، نوشتار نشان غیرمختص برگه برگردانده می‌شود.

پارامترها

  • جزئیات

    TabDetails

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (result: string) => void

    • نتیجه

      رشته

بازگشتی‌ها

  • Promise<string>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getPopup()

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

سند HTML را که به‌عنوان بالاپر برای این کنش مرورگر تنظیم شده است دریافت می‌کند.

پارامترها

  • جزئیات

    TabDetails

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (result: string) => void

    • نتیجه

      رشته

بازگشتی‌ها

  • Promise<string>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getTitle()

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

عنوان کنش مرورگر را دریافت می‌کند.

پارامترها

  • جزئیات

    TabDetails

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (result: string) => void

    • نتیجه

      رشته

بازگشتی‌ها

  • Promise<string>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setBadgeBackgroundColor()

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

رنگ پس‌زمینه نشان را تنظیم می‌کند.

پارامترها

  • جزئیات

    شیء

    • رنگ

      رشته | ColorArray

      آرایه‌ای از چهار عدد صحیح در محدوده ۰ تا ۲۵۵ که رنگ RGBA نشان را تشکیل می‌دهند. همچنین می‌تواند رشته‌ای با مقدار رنگ CSS بر مبنای شانزده باشد؛ برای مثال، #FF0000 یا #F00 (قرمز). رنگ‌ها را با ماتی کامل ارائه می‌کند.

    • tabId

      شماره اختیاری

      تغییر را به زمانی محدود می‌کند که برگه خاصی انتخاب شده باشد. وقتی برگه بسته می‌شود، به‌طور خودکار بازنشانی می‌شود.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۶۷ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setBadgeText()

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

نوشتار نشان را برای کنش مرورگر تنظیم می‌کند. نشان روی نماد نمایش داده می‌شود.

پارامترها

  • جزئیات

    شیء

    • tabId

      شماره اختیاری

      تغییر را به زمانی محدود می‌کند که برگه خاصی انتخاب شده باشد. وقتی برگه بسته می‌شود، به‌طور خودکار بازنشانی می‌شود.

    • نوشتار

      رشته اختیاری

      هر تعداد نویسه‌ای را می‌توان ارسال کرد، اما فقط حدود چهار نویسه در این فضا جا می‌شود. اگر رشته خالی ('') ارسال شود، نوشتار نشان پاک می‌شود. اگر tabId مشخص شده باشد و text تهی باشد، نوشتار برگه مشخص‌شده پاک می‌شود و به‌طور پیش‌فرض به نوشتار نشان جهانی تبدیل می‌شود.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۶۷ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setIcon()

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

نماد را برای کنش مرورگر تنظیم می‌کند. نماد را می‌توان به‌عنوان مسیر فایل تصویری، به‌عنوان داده‌های پیکسل از عنصر بوم، یا به‌عنوان فرهنگ لغت یکی از آن‌ها مشخص کرد. باید ویژگی path یا imageData مشخص شود.

پارامترها

  • جزئیات

    شیء

    • imageData

      ImageData | شیء اختیاری

      یا یک شیء ImageData یا یک واژه‌نامه {size -> ImageData} که نمادی را برای تنظیم نشان می‌دهد. اگر نماد به‌عنوان فرهنگ لغت مشخص شده باشد، تصویر استفاده‌شده براساس تراکم پیکسلی صفحه‌نمایش انتخاب می‌شود. اگر تعداد پیکسل‌های تصویر که در یک واحد فضای صفحه جا می‌شود برابر با scale باشد، تصویری با اندازه scale * n انتخاب می‌شود که در آن n اندازه نماد در واسط کاربر است. حداقل یک تصویر باید مشخص شود. توجه داشته باشید که «details.imageData = foo» معادل «details.imageData = {'16': foo}» است

    • مسیر

      رشته | شیء اختیاری

      مسیر تصویر نسبی یا واژه‌نامه {size -> relative image path} که به نمادی برای تنظیم اشاره می‌کند. اگر نماد به‌عنوان فرهنگ لغت مشخص شده باشد، تصویر استفاده‌شده براساس تراکم پیکسلی صفحه‌نمایش انتخاب می‌شود. اگر تعداد پیکسل‌های تصویر که در یک واحد فضای صفحه جا می‌شود برابر با scale باشد، تصویری با اندازه scale * n انتخاب می‌شود که در آن n اندازه نماد در میانای کاربر است. حداقل یک تصویر باید مشخص شود. توجه داشته باشید که «details.path = foo» معادل «details.path = {'16': foo}» است

    • tabId

      شماره اختیاری

      تغییر را به زمانی محدود می‌کند که برگه خاصی انتخاب شده باشد. وقتی برگه بسته می‌شود، به‌طور خودکار بازنشانی می‌شود.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۱۶ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setPopup()

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

سند HTML را تنظیم می‌کند تا وقتی کاربر روی نماد کنش مرورگر کلیک می‌کند، به‌عنوان بالاپر باز شود.

پارامترها

  • جزئیات

    شیء

    • بالاپر

      رشته

      مسیر نسبی به فایل HTML برای نمایش در بالاپر. اگر روی رشته خالی ('') تنظیم شود، هیچ بالاپری نشان داده نمی‌شود.

    • tabId

      شماره اختیاری

      تغییر را به زمانی محدود می‌کند که برگه خاصی انتخاب شده باشد. وقتی برگه بسته می‌شود، به‌طور خودکار بازنشانی می‌شود.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۶۷ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setTitle()

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

عنوان کنش مرورگر را تنظیم می‌کند. این عنوان در نکته‌ابزار نشان داده می‌شود.

پارامترها

  • جزئیات

    شیء

    • tabId

      شماره اختیاری

      تغییر را به زمانی محدود می‌کند که برگه خاصی انتخاب شده باشد. وقتی برگه بسته می‌شود، به‌طور خودکار بازنشانی می‌شود.

    • عنوان

      رشته

      رشته‌ای که کنش مرورگر باید هنگام قرار گرفتن موشواره روی آن نمایش دهد.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۶۷ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onClicked

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

وقتی روی نماد کنش مرورگر کلیک می‌شود، فعال می‌شود. اگر کنش مرورگر بالاپر داشته باشد، فعال نمی‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (tab: tabs.Tab) => void