chrome.contextMenus

توضیحات

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

مجوزها

contextMenus

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

{
  "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، نمونه contextMenus API را از مخزن chrome-extension-samples نصب کنید.

انواع

ContextType

Chrome 44+

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

Enum

"همه"

"صفحه"

"قاب"

"انتخاب"

"پیوند"

"قابل ویرایش"

"تصویر"

"ویدئو"

"صوتی"

"پرتابگر"

"عمل_مرورگر"

"page_action"

"عمل"

CreateProperties

Chrome 123+

ویژگی های آیتم منوی زمینه جدید.

خواص

  • بررسی شد

    بولی اختیاری

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

  • زمینه ها

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

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

  • documentUrl Patterns

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

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

  • فعال شد

    بولی اختیاری

    آیا این آیتم منوی زمینه فعال یا غیرفعال است. پیش فرض ها به true

  • شناسه

    رشته اختیاری

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

  • شناسه والدین

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

    شناسه یک آیتم منوی والدین؛ این باعث می شود که مورد فرزند آیتمی که قبلاً اضافه شده باشد.

  • الگوهای targetUrl

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

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

  • عنوان

    رشته اختیاری

    متن برای نمایش در مورد؛ این مورد نیاز است مگر اینکه type separator باشد. هنگامی که زمینه selection است، از %s در رشته برای نمایش متن انتخاب شده استفاده کنید. به عنوان مثال، اگر مقدار این پارامتر "Translate '%s' to Pig Latin" باشد و کاربر کلمه "cool" را انتخاب کند، مورد منوی زمینه برای انتخاب "Translate 'cool' to Pig Latin" است.

  • نوع

    ItemType اختیاری است

    نوع آیتم منو پیش فرض به normal است.

  • قابل مشاهده است

    بولی اختیاری

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

  • onclick

    باطل اختیاری

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

    تابع onclick به شکل زیر است: 

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

    • اطلاعات

      OnClickData

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

    • برگه

      Tab

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

ItemType

Chrome 44+

نوع آیتم منو

Enum

"عادی"

"چک باکس"

"رادیو"

"جداکننده"

OnClickData

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

خواص

  • بررسی شد

    بولی اختیاری

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

  • قابل ویرایش

    بولی

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

  • frameId

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

    Chrome 51+

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

  • frameUrl

    رشته اختیاری

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

  • linkUrl

    رشته اختیاری

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

  • نوع رسانه

    رشته اختیاری

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

  • menuItemId

    رشته | شماره

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

  • آدرس صفحه

    رشته اختیاری

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

  • parentMenuItemId

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

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

  • انتخاب متن

    رشته اختیاری

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

  • srcUrl

    رشته اختیاری

    برای عناصر با URL 'src' وجود خواهد داشت.

  • بررسی شد

    بولی اختیاری

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

خواص

ACTION_MENU_TOP_LEVEL_LIMIT

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

ارزش

6

روش ها

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

یک آیتم منوی زمینه جدید ایجاد می کند. اگر خطایی در حین ایجاد رخ دهد، ممکن است تا زمانی که پاسخ تماس ایجاد نشود، آن را شناسایی نکند. جزئیات در runtime.lastError خواهد بود.

پارامترها

  • createProperties

    Create Properties

  • پاسخ به تماس

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

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

    () => void

برمی گرداند

  • شماره | رشته

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

remove()

قول بده
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

یک مورد منوی زمینه را حذف می کند.

پارامترها

  • menuItemId

    رشته | شماره

    شناسه مورد منوی زمینه برای حذف.

  • پاسخ به تماس

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

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

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 123+

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

removeAll()

قول بده
chrome.contextMenus.removeAll(
  callback?: function,
)

تمام موارد منوی زمینه اضافه شده توسط این برنامه افزودنی را حذف می کند.

پارامترها

  • پاسخ به تماس

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

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

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 123+

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

update()

قول بده
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

آیتم منوی زمینه ایجاد شده قبلی را به روز می کند.

پارامترها

  • شناسه

    رشته | شماره

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

  • updateProperties

    شی

    خواص برای به روز رسانی مقادیر مشابه تابع contextMenus.create را می پذیرد.

    • بررسی شد

      بولی اختیاری

    • زمینه ها

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

    • documentUrl Patterns

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

    • فعال شد

      بولی اختیاری

    • شناسه والدین

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

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

    • الگوهای targetUrl

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

    • عنوان

      رشته اختیاری

    • نوع

      ItemType اختیاری است

    • قابل مشاهده است

      بولی اختیاری

      Chrome 62+

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

    • onclick

      باطل اختیاری

      تابع onclick به شکل زیر است: 

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

      • اطلاعات

        OnClickData

        Chrome 44+
      • برگه

        Tab

        Chrome 44+

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

  • پاسخ به تماس

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

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

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 123+

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

رویدادها

onClicked

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

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

پارامترها

  • پاسخ به تماس

    تابع

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

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