الأحداث المصطنعة (Synthetic 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
الخاصيّات:
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
- الأحداث المصطنعة (Synthetic Events) (الصفحة الحالية)
- أدوات الاختبار
- التصيير السطحي (Shallow Rendering)
- مصير الاختبار (Test Renderer)
- متطلبات بيئة JavaScript