عرض مصدر jQuery/keypress

<noinclude>{{DISPLAYTITLE:التابع <code>‎‎.keypress()‎</code>‎ في jQuery}}</noinclude>
== <code>‎.keypress( handler )‎</code> ==

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

=== الوصف ===
يربط هذا التابع معالج حدث معين مع الحدث <code>keypress</code> (الضغط على مفتاح في لوحة المفاتيح) في JavaScript، أو يستدعي ذلك الحدث لتطبيقه على عنصر.

=== <code>‎.keypress( handler )‎</code> ===
أُضيف مع الإصدار: 1.0.

==== <code>handler</code> ====
دالة من الشكل <code>[[JavaScript/Function|Function]]( [[JavaScript/Event|Event]] eventObject )‎</code>، وتُمثِّل الدالة التي ستُنفَّذ في كل مرة يُستدعى فيها الحدث.

=== <code>‎.keypress( [eventData ], handler )‎</code> ===
أُضيف مع الإصدار: 1.4.3.

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

==== <code>handler</code> ====
دالة من الشكل <code>[[JavaScript/Function|Function]]( [[JavaScript/Event|Event]] eventObject )</code>‎، وتُمثِّل الدالة التي ستُنفَّذ في كل مرة يُستدعى فيها الحدث.

=== <code>‎.keypress()‎</code> ===
أُضيف مع الإصدار: 1.0، ولا يقبل هذا الشكل من التابع أي معلامات.

'''ملاحظة''': لما كان الحدث <code>keypress</code> غير مشمول ضمن المواصفات القياسية، فقد تواجه اختلافًا في السلوك الأساسي عند استعماله باختلاف المتصفحات، وإصدارات المتصفح، والمنصات.

هذا التابع هو اختصار للتابع <code>[[jQuery/on|‎.on( "keypress", handler )‎]]</code> في شكله الأول والثاني، واختصار للتابع <code>[[jQuery/trigger|‎.trigger( "keypress" )‎]]</code> في شكله الثالث.

يُرسل الحدث <code>keydown</code> إلى عنصر عندما يسجل المتصفح أية مدخلات من لوحة المفاتيح، وهذا مشابه للحدث <code>keydown</code> باستثناء أن مفاتيح التبديل والمفاتيح غير المطبوعة مثل المفتاح Shift، والمفتاح Esc، والمفتاح delete تستدعي أحداث <code>keydown</code> دون أحداث <code>keypass</code>. قد تظهر أيضًا اختلافات أخرى بين هذين الحدثين بناءً على المنصة والمتصفح المستعمل.

رغم إمكانية ارتباط الحدث <code>keypress</code> مع أي عنصر إلا أنَّه لا يُرسل إلا إلى العنصر الذي استقبل التركيز (focus [المركز عليه حاليًا]). تختلف العناصر التي يمكن التركيز عليها باختلاف المتصفحات ولكن عناصر النماذج <code>[[HTML/form|<form>]]</code> يمكنها دومًا الحصول على التركيز، لذا هي من أهم العناصر التي تستعمل بكثرة مع هذا النوع من الحدث.

انظر مثلًا إلى شيفرة HTML التالية:<syntaxhighlight lang="html">
<form>
  <fieldset>
    <input id="target" type="text" value="مرحبًا يا صديق">
  </fieldset>
</form>
<div id="other">
  استدعِ المعالج
</div>
</syntaxhighlight>يمكن أن يُربط معالج الحدث مع حقل الإدخال:<syntaxhighlight lang="javascript">
$( "#target" ).keypress(function() {
 console.log( "Handler for .keypress() called." );
});
</syntaxhighlight>عندما يصبح الآن مؤشر الإدخال داخل الحقل، فإن الضغط على أي مفتاح سيُظهر التنبيه التالي:<syntaxhighlight lang="text">
Handler for .keypress() called.
</syntaxhighlight>استعمل لاستدعاء الحدث يدويًا التابع <code>‎.keypress()‎</code> دون أي معاملات:<syntaxhighlight lang="javascript">
$( "#other" ).click(function() {
 $( "#target" ).keypress();
});
</syntaxhighlight>بعد تنفيذ هذه الشيفرة، ستظهر الرسالة السابقة بالضغط على "استدعِ المعالج".

إن احتجت تحسُّس ضغط المفتاح في أي مكان في الصفحة (مثل استعمال مفاتيح اختصار عامة في الصفحة)، فاربط هذا السلوك مع الكائن <code>[[JavaScript/Document|document]]</code>. بسبب توقف انتقال الحدث (bubbling)، فإنَّ جميع ضغطات المفتاح ستسلك طريقها عبر شجرة DOM إلى الكائن <code>[[JavaScript/Document|document]]</code> إلا إذا أُوقف هذا السلوك صراحةً.

إن أردت معرفة المفتاح الذي ضُغط، فافحص الكائن <code>event</code> المُمرَّر إلى دالة معالجة الحدث (handler). لما كانت المتصفحات تستعمل خصائص مختلفة لتخزين هذه المعلومات، اعتمدت jQuery على ذلك لتسوية هذه المعضلة بتوفير الخاصية <code>‎.which</code>، لذا يمكنك استخدامها بكل ثقة لجلب رمز المفتاح المضغوط.

الجدير بالملاحظة أن الحدث <code>keydown</code> والحدث <code>keyup</code> يوفران رمزًا يشير إلى أي مفتاح ضُغط، بينما يشير الرمز الذي يوفره الحدث <code>keypress</code> إلى الحرف الذي أُدخل. سيُشار إلى الحرف "a" الصغير مثلًا بالرمز 65 باستعمال الحدث <code>keydown</code> والحدث <code>keyup</code>، بينما سيُشار إليه بالرمز 97 باستعمال الحدث <code>keypress</code>؛ سيُشار إلى الحرف "A" الكبير بالرمز 65 باستعمال جميع الأحداث. بناءً على هذا الاختلاف، إن كنت تريد معرفة المفتاح المضغوط عمومًا أو مفاتيح مخصصة مثل مفاتيح الأسهم فاستعمل التابع <code>[[jQuery/keydown|‎.keydown()‎]]</code> أو التابع <code>[[jQuery/keyup|‎.keyup()‎]]</code> بينما إن كنت تهتم بمعرفة الحرف المضغوط فاستعمل التابع <code>‎.keypress()‎</code>.

=== ملاحظات إضافية ===
لما كان التابع <code>‎.keypress()‎</code> اختزالٌ للتابع <code>[[jQuery/on|‎.on( "keypress", handler )‎]]</code>، فمن الممكن استعمال <code>[[jQuery/off|‎.off( "keypress" )‎]]</code> لإزالة الحدث <code>keypress</code> أي عملية معاكسة لما سبق.

=== أمثلة ===
إظهار الكائن <code>event</code> لكل معالج <code>keydown</code> عند الضغط على أي مفتاح في حقل الإدخال <code>[[HTML/input|<input>]]</code>:

(ملاحظة: تعتمد التجربة الحية لهذا المثال على الإضافة <code>‎$.print()‎</code> البسيطة [https://api.jquery.com/resources/events.js<nowiki>] من أجل مخرجات الكائن للحدث).</nowiki><syntaxhighlight lang="html">
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>keypress مثال عن الحدث</title>
  <style>
  fieldset {
    margin-bottom: 1em;
  }
  input {
    display: block;
    margin-bottom: .25em;
  }
  #print-output {
    width: 100%;
  }
  .print-output-line {
    white-space: pre;
    padding: 5px;
    font-family: monaco, monospace;
    font-size: .7em;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<form>
  <fieldset>
    <label for="target">اكتب شيئًا</label>
    <input id="target" type="text">
  </fieldset>
</form>
<button id="other">
  استدعِ الحدث
</button>
<script src="/resources/events.js"></script>
 
<script>
var xTriggered = 0;
$( "#target" ).keypress(function( event ) {
  if ( event.which == 13 ) {
     event.preventDefault();
  }
  xTriggered++;
  var msg = "Handler for .keypress() called " + xTriggered + " time(s).";
  $.print( msg, "html" );
  $.print( event );
});
 
$( "#other" ).click(function() {
  $( "#target" ).keypress();
});
</script>
 
</body>
</html>

</syntaxhighlight>

= مصادر =
* [http://api.jquery.com/keypress/ صفحة التابع ‎‎.keypress()‎ في توثيق jQuery الرسمي.]
[[تصنيف:jQuery]]
[[تصنيف:jQuery Events]]