chrome.browserAction

توضیحات

از اقدامات مرورگر برای قرار دادن نمادها در نوار ابزار اصلی 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 نزدیک‌ترین نماد را انتخاب می‌کند و آن را به اندازه مناسب تغییر می‌دهد تا فضای 16 شیب را پر کند. با این حال، اگر اندازه دقیق ارائه نشده باشد، این مقیاس‌بندی می‌تواند باعث شود که نماد جزئیات را از دست بدهد یا مبهم به نظر برسد.

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

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

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

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

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

نماد

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

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

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

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

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

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

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

نشان

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

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

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

پنجره بازشو

اگر یک عملکرد مرورگر دارای یک پنجره بازشو باشد، هنگامی که کاربر روی نماد برنامه افزودنی کلیک می کند، پنجره بازشو ظاهر می شود. پنجره بازشو می تواند حاوی هر محتوای HTML مورد نظر شما باشد و به طور خودکار اندازه آن متناسب با محتوای آن باشد. پنجره بازشو نمی تواند کوچکتر از 25x25 باشد و نمی تواند بزرگتر از 800x600 باشد.

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

نکات

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

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

نمونه ها

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

انواع

ColorArray

تایپ کنید

[شماره، شماره، شماره، شماره]

ImageDataType

داده های پیکسل برای یک تصویر. باید یک شی ImageData باشد. به عنوان مثال، از یک عنصر canvas .

تایپ کنید

ImageData

TabDetails

Chrome 88+

خواص

• tabId

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

  شناسه برگه مورد نظر برای درخواست. اگر هیچ برگه ای مشخص نشده باشد، حالت غیر اختصاصی تب برگردانده می شود.

روش ها

disable()

قول بده

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

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

پارامترها

• tabId

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

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

• پاسخ به تماس

  عملکرد اختیاری

  Chrome 67+

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

enable()

قول بده

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

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

پارامترها

• tabId

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

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

• پاسخ به تماس

  عملکرد اختیاری

  Chrome 67+

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

getBadgeBackgroundColor()

قول بده

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

پارامترها

• جزئیات

  TabDetails

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (result: ColorArray) => void

  • نتیجه

    ColorArray

برمی گرداند

• Promise< ColorArray >

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

getBadgeText()

قول بده

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

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

پارامترها

• جزئیات

  TabDetails

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (result: string) => void

  • نتیجه

    رشته

برمی گرداند

• قول<رشته>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

getPopup()

قول بده

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

پارامترها

• جزئیات

  TabDetails

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (result: string) => void

  • نتیجه

    رشته

برمی گرداند

• قول<رشته>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

getTitle()

قول بده

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

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

پارامترها

• جزئیات

  TabDetails

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (result: string) => void

  • نتیجه

    رشته

برمی گرداند

• قول<رشته>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

setBadgeBackgroundColor()

قول بده

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

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

پارامترها

• جزئیات

  شی

  • رنگ

    رشته | ColorArray

    آرایه ای از چهار عدد صحیح در محدوده 0-255 که رنگ RGBA نشان را تشکیل می دهد. همچنین می تواند رشته ای با مقدار رنگ هگزا CSS باشد. به عنوان مثال، #FF0000 یا #F00 (قرمز). رنگ ها را با شفافیت کامل نمایش می دهد.

  • tabId

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

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

• پاسخ به تماس

  عملکرد اختیاری

  Chrome 67+

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

setBadgeText()

قول بده

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

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

پارامترها

• جزئیات

  شی

  • tabId

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

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

  • متن

    رشته اختیاری

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

• پاسخ به تماس

  عملکرد اختیاری

  Chrome 67+

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

setIcon()

قول بده

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

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

پارامترها

• جزئیات

  شی

  • داده های تصویری

    ImageData | شی اختیاری

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

  • مسیر

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

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

  • tabId

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

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

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 116+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

setPopup()

قول بده

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

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

پارامترها

• جزئیات

  شی

  • پنجره بازشو

    رشته

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

  • tabId

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

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

• پاسخ به تماس

  عملکرد اختیاری

  Chrome 67+

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

setTitle()

قول بده

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

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

پارامترها

• جزئیات

  شی

  • tabId

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

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

  • عنوان

    رشته

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

• پاسخ به تماس

  عملکرد اختیاری

  Chrome 67+

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 88+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

رویدادها

onClicked

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

هنگامی که نماد عملکرد مرورگر کلیک می شود فعال می شود. اگر عملکرد مرورگر دارای یک پنجره بازشو باشد، فعال نمی شود.

پارامترها

• پاسخ به تماس

  تابع

  پارامتر callback به نظر می رسد:

  (tab: tabs.Tab) => void

  • برگه

    Tabs.Tab