التابع `‎‎.contextmenu()‎‎`‎ في jQuery

`‎.contextmenu( handler )‎`

القيمة المعادة

كائن jQuery.

الوصف

يُستخدَم التابع ‎‎.contextmenu()‎‎ في ربط مُعالِج أحداث (event handler) إلى الحدث ‎contextmenu‎ في JavaScript، أو إطلاق هذا الحدث على عنصر ما.

`‎.contextmenu( handler )‎`

أضيفت في الإصدار: 1.0.

`handler`

دالة على الشكل ‎Function( Event eventObject )‎، وتُمثِّل الدالة التي ستُنفَّذ في كل مرة يُطلَق فيها الحدث.

`‎.contextmenu( [eventData ], handler )‎`

أضيفت في الإصدار: 1.4.3.

`eventData`

أي شيء (وهو نوع افتراضي مُستخدَم في jQuery للإشارة إلى إمكانيّة استخدام أي نوع)، ويُمثِّل كائن يحتوي على البيانات التي ستُمرَّر إلى مُعالِج الأحداث.

`handler`

دالة على الشكل ‎Function( Event eventObject )‎، وتُمثِّل الدالة التي ستُنفَّذ في كل مرة يُطلَق فيها الحدث.

`‎.contextmenu()‎`

أضيفت في الإصدار: 1.0.

لا يقبل هذا الشكل من التّابع أيّة وسائط.

يُعدُّ هذا التّابع اختصارًا للتابع ‎.on( "contextmenu", handler )‎ في أول شكلين له، وللتّابع ‎.trigger( "contextmenu" )‎ في شكله الثّالث. يُرسَل الحدث contextmenu إلى العنصر عند النقر على زر الفأرة الأيمن، ولكن قبل ظهور القائمة المنبثقة (context menu)، وهي القائمة التي تظهر عندما ينقر المستخدم على زر الفأرة الأيمن. وفي حال ضغطنا على زر لوحة المفاتيح الذي يُظهِر القائمة المنبثقة، فسيُطلَق الحدث على العنصر <html‎> أو على العنصر قيد التركيز حاليًّا. بإمكان أي عنصر HTML أن يستقبل هذا الحدث، فلنأخذ هذا المثال:

<div id="target">
  انقر باليمين هنا
</div>

يُمكِن ربط مُعالِج الأحداث إلى عنصر <div‎> كما يلي:

$( "#target" ).contextmenu(function() {
  alert( "استدعي معالج الأحداث للتابع ‎.contextmenu()‎" );
});

سيعرض الآن النقر بالأيمن على هذا العنصر رسالة التنبيه التالية:

استدعي معالج الأحداث للتابع ‎.contextmenu()‎

لإطلاق الحدث يدويًّا، نستدعي التّابع ‎.contextmenu()‎ بدون أي وسيط:

$( "#target" ).contextmenu();

ملاحظات إضافية

لمّا كان التّابع ‎‎.contextmenu()‎‎ مُجرَّد اختصار للتابع ‎.on( "contextmenu", handler )‎، فمن الممكن إلغاء الحدث عبر استخدام ‎.off( "contextmenu" )‎.

أمثلة

لإظهار رسالة تنبيه "مرحبًا بالعالم" عند إطلاق الحدث contextmenu على فقرة في الصفحة:

$( "p" ).contextmenu(function() {
  alert( "مرحبًا بالعالم" );
});

انقر بالزر الأيمن للتبديل بين لوني الخلفيّة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>contextmenu مثال عن التابع</title>
  <style>
  div {
    background: blue;
    color: white;
    height: 100px;
    width: 150px;
 }
  div.contextmenu {
    background: yellow;
    color: black;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div></div>
<span>انقر بالزر الأيمن على هذه الكتلة</span>
 
<script>
var div = $( "div:first" );
div.contextmenu(function() {
  div.toggleClass( "contextmenu" );
});
</script>
 
</body>
</html>

مصادر

صفحة التابع ‎‎‎‎.contextmenu()‎ في توثيق jQuery الرسمي.