chrome.pageAction

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.pageAction API برای قرار دادن نمادها در نوارابزار اصلی Google Chrome، در سمت چپ نوار نشانی، استفاده کنید. کنش‌های صفحه نشان‌دهنده کنش‌هایی است که می‌توان در صفحه فعلی انجام داد، اما برای همه صفحه‌ها قابل‌اجرا نیست. کنش‌های صفحه وقتی غیرفعال باشند خاکستری می‌شوند.

دردسترس بودن

≤ MV2

چند مثال:

  • مشترک شدن در فید RSS این صفحه
  • از عکس‌های این صفحه نمایش اسلایدی بسازید

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

کنش‌های صفحه پنهان به‌صورت خاکستری نشان داده می‌شود. برای مثال، فید RSS زیر خاکستری شده است، زیرا نمی‌توانید در فید صفحه فعلی مشترک شوید:

لطفاً به‌جای آن از کنش مرورگر استفاده کنید تا کاربران همیشه بتوانند با افزونه شما تعامل داشته باشند.

مانیفست

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

{
  "name": "My extension",
  ...
  "page_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 نزدیک‌ترین مورد را انتخاب می‌کند و آن را مقیاس‌بندی می‌کند تا فضای ۱۶ پیکسلی مستقل از تراکم را پر کند. این کار همچنین تضمین می‌کند که اگر اندازه نمایش نماد تغییر کند، نیازی نیست کار بیشتری برای ارائه نمادهای مختلف انجام دهید! اما اگر تفاوت اندازه خیلی زیاد باشد، این مقیاس‌بندی می‌تواند باعث شود نماد جزئیاتش را ازدست بدهد یا تار به‌نظر برسد.

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

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

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

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

بااستفاده از روش‌های pageAction.show و pageAction.hide، می‌توانید کنش صفحه را به‌ترتیب نمایش دهید و خاکستری کنید. به‌طور پیش‌فرض، کنش صفحه به‌صورت خاکستری نشان داده می‌شود. وقتی آن را نشان می‌دهید، برگه‌ای را که نماد باید در آن نشان داده شود مشخص می‌کنید. این نماد تا زمانی‌که برگه بسته شود یا نشانی وب دیگری را نمایش دهد (مثلاً به‌دلیل کلیک کردن کاربر روی پیوند) نمایان می‌ماند.

نکته‌ها

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

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

انواع

ImageDataType

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

نوع

ImageData

TabDetails

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

مشخصات

  • tabId

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

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

روش‌ها

getPopup()

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

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

پارامترها

  • جزئیات

    TabDetails

  • تماس برگشتی

    تابع اختیاری

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

    (result: string) => void

    • نتیجه

      رشته

بازگشتی‌ها

  • Promise<string>

    Chrome نسخه ۱۰۱ به بالا

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

getTitle()

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

عنوان کنش صفحه را دریافت می‌کند.

پارامترها

  • جزئیات

    TabDetails

  • تماس برگشتی

    تابع اختیاری

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

    (result: string) => void

    • نتیجه

      رشته

بازگشتی‌ها

  • Promise<string>

    Chrome نسخه ۱۰۱ به بالا

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

hide()

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

کنش صفحه را پنهان می‌کند. کنش‌های پنهان صفحه همچنان در نوارابزار Chrome نشان داده می‌شوند، اما خاکستری هستند.

پارامترها

  • tabId

    شماره

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

  • تماس برگشتی

    تابع اختیاری

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

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

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۰۱ به بالا

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

setIcon()

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

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

پارامترها

  • جزئیات

    شیء

    • iconIndex

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

      منسوخ‌شده. این آرگومان نادیده گرفته می‌شود.

    • 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.pageAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

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

پارامترها

  • جزئیات

    شیء

    • بالاپر

      رشته

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

    • tabId

      شماره

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

  • تماس برگشتی

    تابع اختیاری

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

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

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۰۱ به بالا

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

setTitle()

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

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

پارامترها

  • جزئیات

    شیء

    • tabId

      شماره

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

    • عنوان

      رشته

      رشته نکته‌ابزار.

  • تماس برگشتی

    تابع اختیاری

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

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

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۰۱ به بالا

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

show()

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

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

پارامترها

  • tabId

    شماره

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

  • تماس برگشتی

    تابع اختیاری

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

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

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۰۱ به بالا

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

رویدادها

onClicked

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

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

پارامترها

  • تماس برگشتی

    عملکرد

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

    (tab: tabs.Tab) => void