chrome.contextMenus

توضیحات

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

مجوزها

contextMenus

شما باید مجوز "contextMenus" را در مانیفست افزونه خود برای استفاده از API اعلام کنید. همچنین، باید یک آیکون 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 را مشخص کنید.

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

مثال‌ها

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

انواع

ContextType

کروم ۴۴+

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

شمارشی

«همه»

«صفحه»

"قاب"

"انتخاب"

«پیوند»

«قابل ویرایش»

«تصویر»

«ویدئو»

"صوتی"

"پرتاب کننده"

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

"عملکرد صفحه"

«عمل»

CreateProperties

کروم ۱۲۳+

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

خواص

  • بررسی شده

    بولی اختیاری

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

  • زمینه‌ها

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

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

  • الگوهای documentUrl

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

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

  • فعال شده

    بولی اختیاری

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

  • شناسه

    رشته اختیاری

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

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

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

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

  • الگوهای targetUrl

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

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

  • عنوان

    رشته اختیاری

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

  • نوع

    نوع کالا اختیاری

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

  • قابل مشاهده

    بولی اختیاری

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

  • کلیک

    اختیاری باطل

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

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

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

    • اطلاعات

      OnClickData

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

    • تب

      تب

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

ItemType

کروم ۴۴+

نوع آیتم منو.

شمارشی

"عادی"

"کادر انتخاب"

«رادیو»

"جداکننده"

OnClickData

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

خواص

  • بررسی شده

    بولی اختیاری

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

  • قابل ویرایش

    بولی

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

  • شناسه قاب

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

    کروم ۵۱+

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

  • فریم‌ور

    رشته اختیاری

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

  • لینک‌آدرس

    رشته اختیاری

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

  • نوع رسانه

    رشته اختیاری

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

  • شناسه آیتم منو

    رشته | عدد

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

  • آدرس صفحه

    رشته اختیاری

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

  • شناسه آیتم منوی والد

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

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

  • متن انتخابی

    رشته اختیاری

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

  • srcUrl

    رشته اختیاری

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

  • بررسی شد

    بولی اختیاری

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

خواص

ACTION_MENU_TOP_LEVEL_LIMIT

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

ارزش

۶

روش‌ها

create()

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

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

پارامترها

  • ایجاد ویژگی‌ها

    ایجاد ویژگی‌ها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • عدد | رشته

    شناسه‌ی آیتم تازه ایجاد شده.

remove()

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

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

پارامترها

  • شناسه آیتم منو

    رشته | عدد

    شناسه‌ی آیتم منوی زمینه که باید حذف شود.

بازگشت‌ها

  • قول<void>

    کروم ۱۲۳+

    وقتی منوی زمینه حذف شده باشد، مشکل برطرف می‌شود.

removeAll()

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

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

بازگشت‌ها

  • قول<void>

    کروم ۱۲۳+

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

update()

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

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

پارامترها

  • شناسه

    رشته | عدد

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

  • به‌روزرسانی‌ها

    شیء

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

    • بررسی شده

      بولی اختیاری

    • زمینه‌ها

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

    • الگوهای documentUrl

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

    • فعال شده

      بولی اختیاری

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

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

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

    • الگوهای targetUrl

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

    • عنوان

      رشته اختیاری

    • نوع

      نوع کالا اختیاری

    • قابل مشاهده

      بولی اختیاری

      کروم ۶۲+

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

    • کلیک

      اختیاری باطل

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

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

      • اطلاعات

        OnClickData

        کروم ۴۴+
      • تب

        تب

        کروم ۴۴+

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

بازگشت‌ها

  • قول<void>

    کروم ۱۲۳+

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

رویدادها

onClicked

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

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

پارامترها