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

`‎.mousemove( handler )‎`

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

يعيد كائنًا من النوع jQuery.

الوصف

يربط هذا التابع معالج حدث معين مع الحدث mousemove (التحرك داخل العنصر) في JavaScript، أو يستدعي ذلك الحدث لتطبيقه على عنصر.

`‎.mousemove( handler )‎`

أُضيف مع الإصدار: 1.0.

`handler`

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

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

أُضيف مع الإصدار: 1.4.3.

`eventData`

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

`handler`

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

`‎.mousemove()‎`

أُضيف مع الإصدار: 1.0، ولا يقبل هذا الشكل من التابع أي معلامات.

هذا التابع هو اختصار للتابع ‎.on( "mousemove", handler )‎ في شكله الأول والثاني، واختصار للتابع ‎.trigger( "mousemove" )‎ في شكله الثالث.

يُرسَل الحدث mousemove إلى عنصر عندما يتحرك مؤشِّر الفأرة داخل حيِّزه. يمكن أن تستقبل جميع عناصر HTML هذا الحدث.

انظر مثلًا إلى شيفرة HTML التالية:

<div id="target">
  Move here
</div>
<div id="other">
  Trigger the handler
</div>
<div id="log"></div>

يمكن أن يُربَط معالج الحدث مع أي عنصر:

$( "#target" ).mousemove(function( event ) {
  var msg = "Handler for .mousemove() called at ";
  msg += event.pageX + ", " + event.pageY;
  $( "#log" ).append( "<div>" + msg + "</div>" );
});

عندما يتحرك مؤشِّر الفأرة داخل حيِّز العنصر <div> ذي المعرِّف target فستضاف الرسائل التالية إلى العنصر <div id="log">:

Handler for .mousemove() called at (399, 48) 
Handler for .mousemove() called at (398, 46) 
Handler for .mousemove() called at (397, 44) 
Handler for .mousemove() called at (396, 42)

يمكن أيضًا استدعاء الحدث يدويًا بتطبيقه دون أي وسائط:

$( "#other" ).click(function() {
 $( "#target" ).mousemove();
});

بعد تنفيذ هذه الشيفرة، ستُضاف الرسالة التالية أيضًا بالضغط على "Trigger the handler":

Handler for .mousemove() called at (undefined, undefined)

عند تتبُّع حركة مؤشِّر الفأرة، فستحتاج عادةً إلى معرفة الموقع الحقيقي للمؤشِّر. الكائن event الممرَّر إلى معالج الحدث يحوي بعض المعلومات عن إحداثيات المؤشِّر. هنالك خاصِّيَّاتٌ متاحةٌ مثل ‎.clientX و ‎.offsetX و ‎.pageX ولكن دعم كلِّ واحدة منهم يختلف باختلاف المتصفح. وفرَّت jQuery لحسن الحظ دعمًا للخاصيتين ‎.pageX و ‎.pageY وبذلك يمكن استعمالهما مع جميع المتصفحات. تزوِّد هاتان الخاصِّيَّان المستخدم بمعلومات عن الإحداثيات X و Y لمؤشِّر الفأرة نسبةً إلى الزاوية العلوية اليسرى للصفحة كما بيَّنت مخرجات المثال السابق ذلك.

تذكر دومًا أنَّ الحدث mousemove يُستدعَى كلَّما تحرك مؤشِّر الفأرة داخل العنصر حتى لو كانت حركته مقدار بكسلٍ واحدٍ. هذا يعني أنَّه يمكن أن تتولَّد مئات الأحداث خلال فترة وجيزة، وإن توجَّب على المعالج أداء عمليات معالَجة مهمة أو كان هنالك معالِجات متعدِّدة لهذا الحدث، فهذا يؤدي إلى استنزاف كبير لأداء المتصفح. بناءً على ذلك، من المهم تحسين أداء معالجات الحدث mouseover قدر الإمكان وإلغاء ربطها متى لم يعد هنالك حاجة لذلك.

الطريقة الشائعة لربط معالج الحدث mousemove هي من ضمن معالج الحدث mousedown وإلغاء ربطه من ضمن معالج الحدث mouseup. إن طُبِّقت هذه السلسلة من الأحداث، فتذكر أنَّ الحدث mouseup قد يُرسَل إلى عنصر HTML مختلف عن العنصر الذي أُرسل إليه الحدث mousemove. لأخذ ذلك في الحسبان، يجب أن يربط معالج الحدث mousemove بعنصر أعلى في شجرة DOM مثل العنصر <body>.

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

لمَّا كان التابع ‎.mousemove()‎ اختزالٌ للتابع ‎.on( "mousemove", handler )‎، فمن الممكن استعمال ‎.off( "mousemove" )‎ لإزالة الحدث mousemove أي عمليَّة معاكسة لما سبق.

أمثلة

إظهار إحداثيات مؤشِّر الفأرة عندما يتحرك فوق العنصر <div> الأصفر. مبدأ الإحداثيات هو الزاوية العلوية اليسرى للنافذة والتي، في هذه الحالة، هي الإطار iframe:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>mousemove demo</title>
  <style>
  div {
    width: 220px;
    height: 170px;
    margin: 10px 50px 10px 10px;
    background: yellow;
    border: 2px groove;
    float: right;
  }
  p {
    margin: 0;
    margin-left: 10px;
    color: red;
    width: 220px;
    height: 120px;
    padding-top: 70px;
    float: left;
    font-size: 14px;
  }
  span {
    display: block;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>
  <span>Move the mouse over the div.</span>
  <span>&nbsp;</span>
</p>
<div></div>
 
<script>
$( "div" ).mousemove(function( event ) {
  var pageCoords = "( " + event.pageX + ", " + event.pageY + " )";
  var clientCoords = "( " + event.clientX + ", " + event.clientY + " )";
  $( "span:first" ).text( "( event.pageX, event.pageY ) : " + pageCoords );
  $( "span:last" ).text( "( event.clientX, event.clientY ) : " + clientCoords );
});
</script>
 
</body>
</html>

مصادر

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