الأحداث المصطنعة (Synthetic Events)

These docs are old and won’t be updated. Go to react.dev for the new React docs.

These new documentation pages teach modern React and include live examples:

Common components (e.g. <div>)

يوثّق هذا الدليل مُغلِّف الأحداث المصطنعة 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 لم تعد مجمعة.

ملاحظة:

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

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

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

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

Clipboard Events
Composition Events
Keyboard Events
Focus Events
Form Events
Generic Events
Mouse Events
Pointer Events
Selection Events
Touch Events
UI Events
Wheel Events
Media Events
Image Events
Animation Events
Transition Events
Other Events

مرجع

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

أسماء الحدث:

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

The onFocus event is called when the element (or some element inside of it) receives focus. For example, it’s called when the user clicks on a text input.

function Example() {
  return (
    <input
      onFocus={(e) => {
        console.log('Focused on input');
      }}
      placeholder="onFocus is triggered when you click this input."
    />
  )
}

onBlur

The onBlur event handler is called when focus has left the element (or left some element inside of it). For example, it’s called when the user clicks outside of a focused text input.

function Example() {
  return (
    <input
      onBlur={(e) => {
        console.log('Triggered because this input lost focus');
      }}
      placeholder="onBlur is triggered when you click this input and then you click outside of it."
    />
  )
}

Detecting Focus Entering and Leaving

You can use the currentTarget and relatedTarget to differentiate if the focusing or blurring events originated from outside of the parent element. Here is a demo you can copy and paste that shows how to detect focusing a child, focusing the element itself, and focus entering or leaving the whole subtree.

function Example() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused self');
        } else {
          console.log('focused child', e.target);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus entered self');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused self');
        } else {
          console.log('unfocused child', e.target);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus left self');
        }
      }}
    >
      <input id="1" />
      <input id="2" />
    </div>
  );
}

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

أسماء الحدث:

onChange onInput onInvalid onReset 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 المعيار, تُمد أحداث Mouse Events بالخاصيّات التالية:

number pointerId
number width
number height
number pressure
number tangentialPressure
number tiltX
number tiltY
number twist
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

Note

اعتبارًا من الإصدار 17, حدث onScroll does not bubble في React. حيث يطابق هذا سلوك المتصفح ويمنع الارتباك عند قيام عنصر متداخل قابل للتمرير بإطلاق أحداث على أحد العناصر الأخرى.

الخاصيّات:

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

Is this page useful?تحرير هذه الصفحة