SyntheticEvent

این صفحه، مرجع SyntheticEvent می‌باشد که بخشی از سیستم رویدادهای ری‌اکت (React’s Event System) را تشکیل می‌دهد. برای یادگیری بیشتر، Handling Events را ببینید.

مرور کلی

SyntheticEvent روکشی است بر رویدادهای ذاتی خود مرورگر که در تمام مرورگر‌ها کار می‌کند. کنترل کننده‌های رویداد (event handlers) شما instance هایی از SyntheticEvent دریافت خواهند کرد. رابط آن همانند رویدادهای ذاتی مرورگر است و شامل stopPropagation() و preventDefault() هم هست. با این تفاوت که رویدادها در تمام مرورگر‌ها عین هم کار می‌کنند.

اگر فکر می‌کنید که در جایی باید رویداد ذاتی خود مرورگر را استفاده کنید، کافی است که nativeEvent را به عنوان یک attribute اضافه کنید تا به آن دسترسی یابید. رویداد‌های سینتتیک متفاوت از رویداد‌های ذاتی مرورگر هستند و تناظر یک به یک بین آن‌ها وجود ندارد. برای مثال در onMouseLeave، مقدار event.nativeEvent به رویداد mouseout اشاره دارد. این تناظر بخشی از API عمومی نیست و ممکن است هر موقعی تغییر کند. هر آبجکت SyntheticEvent، attribute های زیر دارد:

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

توجه:

از نسخه ی ۰/۱۴، بازگشت دادن false از یک کنترل کننده ی رویداد، مانع انتشار یک رویداد نمی شود. بجای آن، e.stopPropagation() یا e.preventDefault() ، هر کدام به درخور موقعیت باید اجرا شوند

جمع آوری رویداد (event-pooling)

SyntheticEvent جمع آوری می‌شود. یعنی اینکه آبجکت SyntheticEvent پس از آنکه callback اش فراخوانی شد، تمام دارایی‌های خود را از دست خواهد داد و استفاده ی مجدد خواهد شد. این به خاطر ارتقای کارکرد است. از همین رو، شما نمی توانید به طور غیرهمزمان (asynchronous) به رویداد دسترسی داشته باشید.

function onClick(event) {
  console.log(event); // => nullified object.
  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 فقط حاوی متغیرهای تهی خواهد بود.
  this.setState({clickEvent: event});

  // همچنان قادر خواهید بود که دارایی‌های رویداد را صادر کنید
  this.setState({eventType: event.type});
}

توجه:

اگر می‌خواهید که به دارایی‌های رویداد، به طور غیرهمزمان دسترسی داشته باشید باید event.persist() را در رویداد فراخوانی کنید. این موجب خواهد شد که رویداد سینتاتیک از روند جمع‌آوری خارج شود و ارجاعات داده شده به آن رویداد در کد کاربر حفظ شود.

رویدادهای پشتیبانی شده

ری‌اکت فرایند نرمال سازی را روی رویدادها انجام می دهد تا در مرورگرهای مختلف، ویژگی های یکسانی داشته باشند.

کنترل کنندگان رویدادهایی که در زیر می بینید، در فاز bubbling اجرا می شوند. اگر می خواهید که رویدادی در فاز capture اجرا شود، 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)
• دیگر رویداد‌ها

مرجع

(Clipboard Events)

نام رویدادها

onCopy onCut onPaste

ویژگی‌ها

DOMDataTransfer clipboardData

Composition Events

نام رویدادها

onCompositionEnd onCompositionStart onCompositionUpdate

ویژگی‌ها

string data

رویداد‌های صفحه‌کلید (Keyboard Events)

نام رویدادها

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 Level 3 Events spec را داشته باشد.

رویداد‌های فکوس (Focus Events)

نام رویدادها

onFocus onBlur

رویدادهای فوق برای تمام المنت‌های React DOM کار خواهد کرد و نه فقط المنت‌های فرم.

ویژگی‌ها

DOMEventTarget relatedTarget

رویداد‌های فرم (Form Events)

نام رویدادها

onChange onInput onInvalid onReset onSubmit 

برای اطلاعات بیشتر در مورد رویداد onChange، Forms را ببینید.

رویدادهای عمومی (Generic Events)

نام رویدادها

onError onLoad

رویداد‌های ماوس (Mouse Events)

نام رویدادها

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

رویدادهای onMouseEnter و onMouseLeave از المنت ترک شده به المنت وارد شده تکثیر می‌شوند. آنها فاز capture ندارند و bubbling معمول هم در آنها اتفاق نمی افتد.

ویژگی‌ها

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

رویداد‌های اشاره‌گر (Pointer Events)

نام رویدادها

onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture
onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut

رویدادهای onPointerEnter و onPointerLeave از المنت ترک شده به المنت وارد شده تکثیر می‌شوند. آنها فاز capture ندارند و bubbling معمول هم در آنها اتفاق نمی افتد.

ویژگی‌ها

طبق W3 spec، رویدادهای متعلق به نشانگر ماوس، رویدادهای مربوط به ماوس (Mouse Events) را با ویژگی‌های زیر توسعه می‌دهند.

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

نکته ای در مورد پشتیبانی در مرورگرهای مختلف:

رویدادهای متعلق به نشانگر ماوس در تمام مرورگرها پشتیبانی نمی شوند. در زمان نوشتن این مقاله مرورگرهایی که از آن پشتیبانی می‌کنند عبارتند از: کروم، فایرفاکس، اج، و اینترنت اکسپلورر. ری‌اکت تعمدا از کد جایگزین برای پشتیبانی در مرورگرهای دیگر استفاده نمی کند، چون این کد باعث افزایش چشمگیر حجم react-dom می‌شود.

اگر اپلیکیشن شما نیازمند رویدادهای نشانگر ماوس است، توصیه می‌کنیم که از کدهای جایگزین third party استفاده کنید.

رویداد‌های انتخاب (Selection Events)

نام رویدادها

onSelect

رویداد‌های لمسی (Touch Events)

نام رویدادها

onTouchCancel onTouchEnd onTouchMove onTouchStart

ویژگی‌ها

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

رویداد‌های رابط کاربری (UI Events)

نام رویدادها

onScroll

ویژگی‌ها

number detail
DOMAbstractView view

رویداد‌های اسکرول ماوس (Wheel Events)

نام رویدادها

onWheel

ویژگی‌ها

number deltaMode
number deltaX
number deltaY
number deltaZ

رویداد‌های مدیا (Media Events)

نام رویدادها

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

رویداد‌های تصویر (Image Events)

نام رویدادها

onLoad onError

رویداد‌های انیمیشن (Animation Events)

نام رویدادها

onAnimationStart onAnimationEnd onAnimationIteration

ویژگی‌ها

string animationName
string pseudoElement
float elapsedTime

رویداد‌های انتقال (Transition Events)

نام رویدادها

onTransitionEnd

ویژگی‌ها

string propertyName
string pseudoElement
float elapsedTime

دیگر رویداد‌ها

نام رویدادها

onToggle