React/events

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

لمحة عامة

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

إن وجدت أنّك تحتاج حدث المتصفح الأصلي فاستخدم ببساطة الخاصيّة nativeEvent للحصول عليه. تختلف الأحداث المصطنعة عن أحداث المتصفح الأصلية، كما لا ترتبط بها مباشرة. على سبيل المثال في onMouseLeave، سيشير الحدثevent.nativeEvent  إلى حدث الفأرة mouseout. الربط بين الأحداث ليس جزءًا من الواجهة البرمجية العامة، وقد يتغير في أي وقت. يمتلك كل كائن SyntheticEvent الخاصيّات التالية:

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

ملاحظة: بدءًا من الإصدار 17، لا تفعل e.persist()‎ أي شيء لأن الحدث SyntheticEvent لم يعد مجمَّعًا – pooled – (أي أنّه سيُعاد استخدام الكائن SyntheticEvent  وستُعدَم (nullified) كل الخاصيات عقب استدعاء معالج الحدث).

ملاحظة: بدءًا من الإصدار 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

onFocus

يُستدعى الحدث onFocus عندما يتلقى العنصر (أو بعض العناصر داخله) التركيز. على سبيل المثال، يُستدعى عندما ينقر المستخدم على مربع إدخال نص.

function Example() {
  return (
    <input
      onFocus={(e) => {
        console.log('التركيز على عنصر الإدخال');
      }}
      placeholder="عند النقر على عنصر الإدخال onFocus يُطلق الحدث"
    />
  )
}

onBlur يُستدعى معالج الحدث onBlur عندما يفقد العنصر (أو بعض العناصر بداخله) التركيز. على سبيل المثال، يُستدعى عندما ينقر المستخدم خارج مربع إدخال نص.

function Example() {
  return (
    <input
      onBlur={(e) => {
        console.log('لقد فقد عنصر الإدخال التركيز');
      }}
      placeholder=" عند النقر على عنصر الإدخال ثمّ النقر خارجه onBlur يُطلق الحدث"

    />
  )
}

رصد دخول التركيز وخروجه

يمكنك استخدام CurrentTarget و relatedTarget  لتعلم إن كانت أحداث التركيز أو الخروج قد نشأت من خارج العنصر الرئيسي. إليك مثالا توضيحيا يوضح كيفية رصد حدث التركيز على عنصر ابن، أو التركيز على العنصر نفسه، أو دخول التركيز وخروجه من الشجرة الفرعية بأكملها.

function Example() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('التركيز على العنصر نفسه');
        } else {
          console.log('التركيز على عنصر ابن', e.target);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // لا يُطلَق عند انتقال التركيز من عنصر ابن إلى آخر
          console.log('دخول التركيز إلى العنصر نفسه');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('خروج التركيز من العنصر');
        } else {
          console.log('خروج التركيز من العنصر الابن', e.target);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // لا يُطلَق عند انتقال التركيز من عنصر ابن إلى آخر
          console.log('التركيز خرج من العنصر');
        }
      }}
    >
      <input id="1" />
      <input id="2" />
    </div>
  );
}

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

onChange onInput onInvalid onSubmit

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

أحداث عامة

أسماء الحدث:

onError onLoad

أحداث الفأرة

أسماء الحدث:

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

ملاحظة: بدءًا من الإصدار React 17، لم يعد الحدث onScroll ينتشر. يطابق هذا سلوك المتصفح ويمنع أي ارتباك في حال إطلاق عنصر متداخل قابل للتمرير حدثًا على أحد آبائه البعيدين. الخاصيّات:

number detail
DOMAbstractView view

أحداث دولاب الفأرة

أسماء الحدث:

onWheel

الخاصيّات:

number deltaMode
number deltaX
number deltaY
number deltaZ

أحداث الوسائط

أسماء الحدث:

onAbort onCanPlay onCanPlayThrough onDurationChange onEmptied onEncrypted
onEnded onError onLoadedData onLoadedMetadata onLoadStart onPause onPlay
onPlaying onProgress onRateChange onSeeked onSeeking onStalled onSuspend
onTimeUpdate onVolumeChange onWaiting

أحداث الصور

أسماء الحدث:

onLoad onError

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

أسماء الحدث:

onAnimationStart onAnimationEnd onAnimationIteration

الخاصيّات:

string animationName
string pseudoElement
float elapsedTime

أحداث الانتقال

أسماء الحدث:

onTransitionEnd

الخاصيّات:

string propertyName
string pseudoElement
float elapsedTime

أحداث أخرى

أسماء الحدث:

onToggle

انظر أيضًا

• واجهة برمجة التطبيق (API) ذات المستوى الأعلى في React
• الصنف React.Component
• الكائن ReactDOM
• الكائن ReactDOMServer
• عناصر DOM
• أدوات الاختبار
• التصيير السطحي (Shallow Rendering)
• مصير الاختبار (Test Renderer)
• متطلبات بيئة JavaScript

مصادر

• صفحة الأحداث المصطنعة (Synthetic Events) في توثيق React الرسمي.