browser.contextMenus

شرح

از chrome.contextMenus API برای افزودن موارد به منوِ بافت Google Chrome استفاده کنید. می‌توانید انتخاب کنید که موارد اضافه‌شده به منوی بافت برای چه نوع اشیایی اعمال شود، مثلاً تصاویر، اَبَرپیوندها، و صفحه‌ها.

اجازه‌ها

contextMenus

برای استفاده از API، باید اجازه "contextMenus" را در مانیفست افزونه‌تان اعلام کنید. همچنین، باید نمادی ۱۶ در ۱۶ پیکسلی برای نمایش در کنار گزینه منو مشخص کنید. برای مثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

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

گزینه‌های منوِ بافت می‌توانند در هر سندی (یا چارچوبی در سند)، حتی آن‌هایی که نشانی‌های وب file://‎ یا chrome:// ‎ دارند، ظاهر شوند. برای کنترل اینکه گزینه‌های شما در کدام سندها ظاهر شوند، هنگام فراخوانی روش‌های create() یا update()، فیلد documentUrlPatterns را مشخص کنید.

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

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

مثال‌ها

برای امتحان کردن این API، نمونه contextMenus API را از مخزن chrome-extension-samples نصب کنید.

انواع

ContextType

Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸

بافت‌های مختلفی که منو می‌تواند در آن‌ها ظاهر شود. مشخص کردن «همه» معادل ترکیب همه زمینه‌های دیگر به‌جز «راه‌انداز» و «برگه» است. بافت «راه‌انداز» فقط توسط برنامه‌ها پشتیبانی می‌شود و برای افزودن گزینه‌های منو به منوِ زمینه‌ای که هنگام کلیک کردن روی نماد برنامه در راه‌انداز/ نوار وظیفه/ جایگاه/ و غیره ظاهر می‌شود استفاده می‌شود. پلاتفرم‌های مختلف ممکن است محدودیت‌هایی برای آنچه واقعاً در منوِ زمینه‌ای راه‌انداز پشتیبانی می‌شود اعمال کنند.

شمارشی

«همه»

«صفحه»

"frame"

«انتخاب»

"link"

«editable»

"image"

"video"

"audio"

«راه‌انداز»

«کنش»
برای منوِ زمینه‌ای کنش افزونه (نماد نوارابزار آن) اعمال می‌شود.

«tab»
برای منوِ بافت زبانه در نوار زبانه اعمال می‌شود.

CreateProperties

Chrome نسخه ۱۲۳ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

ویژگی‌های مورد منوِ بافت جدید.

مشخصات

  • دارای علامت

    بولی اختیاری

    وضعیت اولیه چارگوش انتخاب یا دکمه رادیویی: true برای انتخاب‌شده، false برای انتخاب‌نشده. در هر گروه، فقط یک دکمه رادیویی را می‌توان در هر بار انتخاب کرد.

  • بافت‌ها

    [ContextType, ...ContextType[]] اختیاری

    فهرست زمینه‌هایی که این گزینه منو در آن‌ها نشان داده خواهد شد. پیش‌فرض‌ها به ['page'].

  • documentUrlPatterns

    رشته[] اختیاری

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

  • فعال شد

    بولی اختیاری

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

  • id

    رشته اختیاری

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

  • parentId

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

    شناسه گزینه منوِ والد؛ این شناسه گزینه را به فرزند گزینه اضافه‌شده قبلی تبدیل می‌کند.

  • targetUrlPatterns

    رشته[] اختیاری

    مشابه documentUrlPatterns، فیلترها براساس مشخصه src برچسب‌های img، audio، و video و مشخصه href برچسب‌های a است.

  • عنوان

    رشته اختیاری

    نوشتاری که باید در مورد نمایش داده شود؛ این مورد الزامی است مگراینکه type، separator باشد. وقتی زمینه selection است، از %s در رشته استفاده کنید تا نوشتار انتخاب‌شده نشان داده شود. برای مثال، اگر مقدار این پارامتر «ترجمه کردن ‘%s’ به زبان ساختگی Pig Latin» باشد و کاربر کلمه «cool» را انتخاب کند، گزینه منوِ بافت برای انتخاب «ترجمه کردن ‘cool’ به زبان ساختگی Pig Latin» است.

  • نوع

    ItemType اختیاری

    نوع گزینه منو. پیش‌فرض‌ها به normal.

  • قابل رؤیت

    بولی اختیاری

    آیا مورد در منو قابل‌مشاهده است یا نه.

  • onclick

    void اختیاری

    تابعی که هنگام کلیک کردن روی گزینه منو فراخوانده می‌شود. این مورد در داخل یک سرویس‌کار دردسترس نیست؛ درعوض، باید یک شنونده برای contextMenus.onClicked ثبت کنید.

    تابع onclick به‌صورت زیر است: 

    (info: OnClickData, tab: Tab) => {...}

    • اطلاعات

      OnClickData

      اطلاعات مربوط به موردی که روی آن کلیک شده و بافتی که کلیک در آن اتفاق افتاده است.

    • جهش

      برگه

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

ItemType

Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸

نوع گزینه منو.

شمارشی

«عادی»

"checkbox"

"radio"

«جداساز»

OnClickData

اطلاعاتی که هنگام کلیک کردن روی گزینه منوِ زمینه‌ای ارسال می‌شود.

مشخصات

  • دارای علامت

    بولی اختیاری

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

  • ویرایش‌شدنی

    بولی

    پرچمی که نشان می‌دهد آیا عنصر قابل‌ویرایش است (ورودی نوشتار، ناحیه نوشتار، و غیره).

  • frameId

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

    Chrome نسخه ۵۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

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

  • frameUrl

    رشته اختیاری

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

  • linkUrl

    رشته اختیاری

    اگر عنصر پیوند باشد، نشانی وبی که به آن اشاره می‌کند.

  • mediaType

    رشته اختیاری

    یکی از «تصویر»، «ویدیو»، یا «صدا» اگر منوِ بافت روی یکی از این نوع عناصر فعال شده باشد.

  • menuItemId

    رشته | عدد

    شناسه گزینه منو که روی آن کلیک شده است.

  • pageUrl

    رشته اختیاری

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

  • parentMenuItemId

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

    شناسه والد، درصورت وجود، برای مورد کلیک‌شده.

  • selectionText

    رشته اختیاری

    نوشتار انتخاب زمینه، درصورت وجود.

  • srcUrl

    رشته اختیاری

    برای عناصری که نشانی وب «src» دارند وجود خواهد داشت.

  • wasChecked

    بولی اختیاری

    پرچمی که وضعیت چارگوش انتخاب یا دکمه رادیویی را قبل‌از کلیک شدن نشان می‌دهد.

مشخصات

ACTION_MENU_TOP_LEVEL_LIMIT

حداکثر تعداد موارد افزونه سطح بالا که می‌توان به منوِ زمینه‌ای کنش افزونه اضافه کرد. هر موردی فراتر از این حد نادیده گرفته خواهد شد.

مقدار

۶

روش‌ها

create()

browser.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
): number | string

مورد منوِ زمینه‌ای جدیدی ایجاد می‌کند. اگر خطایی درطول ایجاد رخ دهد، ممکن است تا زمانی که فراخوانی برگشتی ایجاد فعال نشود، شناسایی نشود؛ جزئیات در runtime.lastError خواهد بود.

پارامترها

  • createProperties

    CreateProperties

  • تماس برگشتی

    تابع اختیاری

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

    () => void

بازگشتی‌ها

  • عدد | رشته

    شناسه مورد جدیداً ایجادشده.

remove()

browser.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

موردی را از منوِ زمینه‌ای برمی‌دارد.

پارامترها

  • menuItemId

    رشته | عدد

    شناسه مورد منوِ بافت برای برداشتن.

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۲۳ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

    وقتی منوِ بافت برداشته شود، حل می‌شود.

removeAll()

browser.contextMenus.removeAll(): Promise<void>

همه موارد منوِ بافت را که این افزونه اضافه کرده است برمی‌دارد.

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۲۳ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

    وقتی برداشتن تکمیل شود، حل‌وفصل می‌شود.

update()

browser.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

مورد منوِ زمینه‌ای را که قبلاً ایجاد شده است به‌روز می‌کند.

پارامترها

  • id

    رشته | عدد

    شناسه موردی که باید به‌روز شود.

  • updateProperties

    شیء

    ویژگی‌هایی که باید به‌روز شود. مقادیر مشابه با تابع contextMenus.create را می‌پذیرد.

    • دارای علامت

      بولی اختیاری

    • بافت‌ها

      [ContextType, ...ContextType[]] اختیاری

    • documentUrlPatterns

      رشته[] اختیاری

    • فعال شد

      بولی اختیاری

    • parentId

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

      شناسه موردی که قرار است ولی این مورد شود. توجه: نمی‌توانید موردی را به‌عنوان فرزند نسل خودش تنظیم کنید.

    • targetUrlPatterns

      رشته[] اختیاری

    • عنوان

      رشته اختیاری

    • نوع

      ItemType اختیاری

    • قابل رؤیت

      بولی اختیاری

      Chrome نسخه ۶۲ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸ به‌بعد

      آیا مورد در منو قابل‌مشاهده است یا نه.

    • onclick

      void اختیاری

      تابع onclick به‌صورت زیر است: 

      (info: OnClickData, tab: Tab) => {...}

      • اطلاعات

        OnClickData

        Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸
      • جهش

        برگه

        Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸

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

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۲۳ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

    وقتی منوِ بافت به‌روزرسانی شود، حل می‌شود.

رویدادها

onClicked

browser.contextMenus.onClicked.addListener(
  callback: function,
)

وقتی روی موردی در منوِ زمینه‌ای کلیک شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

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

    (info: OnClickData, tab?: tabs.Tab) => void