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

از نسخه ۱۷، دیگر e.persist() کاری انجام نمی‌دهد به دلیل این‌که SyntheticEvent پول (pool) نمی‌شود.

توجه:

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

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

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

کنترل کنندگان رویدادهایی که در زیر می بینید، در فاز 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

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>
  );
}

رویداد‌های فرم (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

یادداشت

با شروع ری‌اکت ۱۷، رویداد onScroll در ری‌اکت به بالا منتشر (bubble) نخواهد شد. این [تغییر] با رفتار مرورگر تطبیق دارد و از رخداد اشتباه جلوگیری می‌کند، هنگامی که یک المنت داخلی که دارای اسکرول است یک رویداد را برای یک والد مرتبه‌بالا رها می‌کند.

ویژگی‌ها:

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