React/events

يوثّق هذا الدليل مُغلِّف الأحداث المصطنعة SyntheticEvent والذي يُشكِّل جزءًا من نظام أحداث React. انظر توثيق معالجة الأحداث لتعلّم المزيد.

لمحة عامّة

ستُمرِّر مُعالجات الأحداث لديك نُسخًا من SyntheticEvent، وهو عبارة عن تغليف للأحداث متوافق عبر المتصفحات لأجل نظام الأحداث الأصلي في المتصفّح، حيث يمتلك نفس الواجهة بما في ذلك stopPropagation()‎ و preventDefault()‎، فيما عدا أنّ هذه الأحداث تعمل عبر جميع المتصفحات.

إن وجدت أنّك تحتاج حدث المتصفح الأصلي فاستخدم ببساطة الخاصيّة nativeEvent للحصول عليه. يمتلك كل كائن SyntheticEvent الخاصيّات التالية:

boolean bubbles
boolean cancelable
DOMEventTarget currentTarget
boolean defaultPrevented
number eventPhase
boolean isTrusted
DOMEvent nativeEvent
void preventDefault()
boolean isDefaultPrevented()
void stopPropagation()
boolean isPropagationStopped()
DOMEventTarget target
number timeStamp
string type

ملاحظة: بدءًا من الإصدار v0.14 لن تؤدي إعادة false من مُعالِج الحدث إلى إيقاف انتشار الحدث، بل يجب إطلاق ذلك يدويًّا عن طريق التابع e.stopPropagation()‎ أو e.preventDefault()‎ بحسب ما هو ملائم.

مسح الأحداث وإعادة تدويرها

يُعاد استخدام الكائن SyntheticEvent وتُعيَّن كافّة خاصيّاته إلى القيمة null بعد استدعاء الحدث. يتم ذلك لأسباب تتعلّق بالأداء. وكنتيجة لهذا لا يمكنك الوصول إلى الحدث بطريقة غير متزامنة:

function onClick(event) {
  console.log(event); // => كائن ذو قيمة null
  console.log(event.type); // => "click"
  const eventType = event.type; // => "click"

  setTimeout(function() {
    console.log(event.type); // => null
    console.log(eventType); // => "click"
  }, 0);

  // لن يعمل. حيث تحتوي this.state.clickEvent على قيم null
  this.setState({clickEvent: event});

  // لا يزال بإمكانك تصدير خاصيات الحدث
  this.setState({eventType: event.type});
}

ملاحظة: إن أردت الوصول إلى خاصيّات الحدث بطريقة غير متزامنة فيجب عليك استدعاء التابع event.persist()‎ على الحدث والذي سيزيل الحدث المصطنع ويسمح للمراجع التي تشير للحدث بأن تحتفظ بها شيفرة المستخدم.

الأحداث المدعومة

تُوحِّد React الأحداث بحيث تمتلك خاصيّات متوافقة عبر المتصفحات المختلفة.

تُطلَق معالجات الأحداث التالية عن طريق حدث في طور مضاعفة الأحداث. لتسجيل مُعالِج حدث لأجل طور الالتقاط أضف Capture إلى اسم الحدث. على سبيل المثال بدلًا من كتابة onClick تستخدم onClickCapture للتعامل مع حدث الضغط في طور الالتقاط.

مرجع

أحداث الحافظة

أسماء الحدث:

onCopy onCut onPaste

الخاصيّات:

DOMDataTransfer clipboardData

أحداث التركيب

أسماء الحدث:

onCompositionEnd onCompositionStart onCompositionUpdate

الخاصيّات:

string data

أحداث لوحة المفاتيح

أسماء الحدث:

onKeyDown onKeyPress onKeyUp

الخاصيّات:

boolean altKey
number charCode
boolean ctrlKey
boolean getModifierState(key)
string key
number keyCode
string locale
number location
boolean metaKey
boolean repeat
boolean shiftKey
number which

تستطيع الخاصيّة key أن تأخذ أي من القيم الموثقة في مواصفات أحداث DOM من المستوى الثالث.

أحداث التركيز

أسماء الحدث:

onFocus onBlur

تعمل أحداث التركيز هذه على جميع العناصر في React DOM، وليس فقط على عناصر حقول الإدخال. الخاصيّات:

DOMEventTarget relatedTarget

أحداث حقول الإدخال

onChange onInput onInvalid onSubmit

للمزيد من المعلومات حول الحدث onChange انظر إلى توثيق حقول الإدخال.

أحداث الفأرة

أسماء الحدث:

onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit
onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
onMouseMove onMouseOut onMouseOver onMouseUp

ينتشر الحدثان onMouseEnter و onMouseLeave من العنصر الذي نغادره إلى العنصر الذي ندخل إليه بدلًا من التضاعف الاعتيادي ولا يمتلكان طور التقاط. الخاصيّات:

boolean altKey
number button
number buttons
number clientX
number clientY
boolean ctrlKey
boolean getModifierState(key)
boolean metaKey
number pageX
number pageY
DOMEventTarget relatedTarget
number screenX
number screenY
boolean shiftKey

أحداث المؤشر

أسماء الحدث:

onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture
onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut

ينتشر الحدثان onPointerEnter و onPointerLeave من العنصر الذي نغادره إلى العنصر الذي ندخل إليه بدلًا من التضاعف الاعتيادي ولا يمتلكان طور التقاط.

الخاصيّات:

كما هو مُعرَّف في المعيار W3، تُمد أحداث المؤشر أحداث الفأرة بالخاصيّات التالية:

number pointerId
number width
number height
number pressure
number tiltX
number tiltY
string pointerType
boolean isPrimary

ملاحظة على دعم التوافقية بين المتصفحات: إنّ أحداث المؤشر غير مدعومة حتى الآن في كل متصفّح (في وقت كتابة هذا المقال المتصفحات المدعومة هي: Chrome، و Firefox، و Edge، و Internet Explorer). لا تُضيف React بشكل افتراضي دعمًا للـ polyfills لمتصفحات أخرى لأنّها ستزيد بشكل ملحوظ من حجم الحزمة react-dom.

إن كان تطبيقك يتطلّب أحداث المؤشر، فنوصي بإضافة polyfill للأحداث مُقدَّمة من قبل طرف ثالث.

أحداث الاختيار

أسماء الحدث:

onSelect

أحداث اللمس

أسماء الحدث:

onTouchCancel onTouchEnd onTouchMove onTouchStart

الخاصيّات:

boolean altKey
DOMTouchList changedTouches
boolean ctrlKey
boolean getModifierState(key)
boolean metaKey
boolean shiftKey
DOMTouchList targetTouches
DOMTouchList touches

أحداث واجهة المستخدم

أسماء الحدث:

onScroll