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

  CreateProperties

• پاسخ به تماس

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

  پارامتر 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

  • اطلاعات

    OnClickData

  • برگه

    Tabs.Tab اختیاری است