Files
react/docs/events.html
T
2016-01-06 23:57:13 +00:00

614 lines
27 KiB
HTML

<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Event System | React</title>
<meta name="viewport" content="width=device-width">
<meta property="og:title" content="Event System | React">
<meta property="og:type" content="website">
<meta property="og:url" content="https://facebook.github.io/react/docs/events.html">
<meta property="og:image" content="https://facebook.github.io/react/img/logo_og.png">
<meta property="og:description" content="A JavaScript library for building user interfaces">
<meta property="fb:app_id" content="623268441017527">
<link rel="shortcut icon" href="/react/favicon.ico">
<link rel="alternate" type="application/rss+xml" title="React" href="https://facebook.github.io/react/feed.xml">
<link rel="stylesheet" href="/react/css/syntax.css">
<link rel="stylesheet" href="/react/css/codemirror.css">
<link rel="stylesheet" href="/react/css/react.css">
<script src="//use.typekit.net/vqa1hcx.js"></script>
<script>try{Typekit.load();}catch(e){}</script>
<!--[if lte IE 8]>
<script src="/react/js/html5shiv.min.js"></script>
<script src="/react/js/es5-shim.min.js"></script>
<script src="/react/js/es5-sham.min.js"></script>
<![endif]-->
<script src="/react/js/codemirror.js"></script>
<script src="/react/js/javascript.js"></script>
<script src="/react/js/react.js"></script>
<script src="/react/js/react-dom.js"></script>
<script src="/react/js/babel-browser.min.js"></script>
<script src="/react/js/live_editor.js"></script>
</head>
<body>
<div class="container">
<div class="nav-main">
<div class="wrap">
<a class="nav-home" href="/react/index.html">
<img class="nav-logo" src="/react/img/logo.svg" width="36" height="36">
React
</a>
<ul class="nav-site nav-site-internal">
<li><a href="/react/docs/getting-started.html" class="active">Docs</a></li>
<li><a href="/react/support.html">Support</a></li>
<li><a href="/react/downloads.html">Download</a></li>
<li><a href="/react/blog/">Blog</a></li>
</ul>
<ul class="nav-site nav-site-external">
<li><a href="https://github.com/facebook/react">GitHub</a></li>
<li><a href="https://facebook.github.io/react-native/">React Native</a></li>
</ul>
</div>
</div>
<section class="content wrap documentationContent">
<div class="nav-docs">
<!-- Docs Nav -->
<div class="nav-docs-section">
<h3>Quick Start</h3>
<ul>
<li>
<a href="/react/docs/getting-started.html">Getting Started</a>
</li>
<li>
<a href="/react/docs/tutorial.html">Tutorial</a>
</li>
<li>
<a href="/react/docs/thinking-in-react.html">Thinking in React</a>
</li>
</ul>
</div>
<div class="nav-docs-section">
<h3>Community Resources</h3>
<ul>
<li>
<a href="/react/docs/conferences.html">Conferences</a>
</li>
<li>
<a href="/react/docs/videos.html">Videos</a>
</li>
<li>
<a href="/react/docs/complementary-tools.html">Complementary Tools</a>
</li>
<li>
<a href="/react/docs/examples.html">Examples</a>
</li>
</ul>
</div>
<div class="nav-docs-section">
<h3>Guides</h3>
<ul>
<li>
<a href="/react/docs/why-react.html">Why React?</a>
</li>
<li>
<a href="/react/docs/displaying-data.html">Displaying Data</a>
<ul>
<li>
<a href="/react/docs/jsx-in-depth.html">JSX in Depth</a>
</li>
<li>
<a href="/react/docs/jsx-spread.html">JSX Spread Attributes</a>
</li>
<li>
<a href="/react/docs/jsx-gotchas.html">JSX Gotchas</a>
</li>
</ul>
</li>
<li>
<a href="/react/docs/interactivity-and-dynamic-uis.html">Interactivity and Dynamic UIs</a>
</li>
<li>
<a href="/react/docs/multiple-components.html">Multiple Components</a>
</li>
<li>
<a href="/react/docs/reusable-components.html">Reusable Components</a>
</li>
<li>
<a href="/react/docs/transferring-props.html">Transferring Props</a>
</li>
<li>
<a href="/react/docs/forms.html">Forms</a>
</li>
<li>
<a href="/react/docs/working-with-the-browser.html">Working With the Browser</a>
<ul>
<li>
<a href="/react/docs/more-about-refs.html">Refs to Components</a>
</li>
</ul>
</li>
<li>
<a href="/react/docs/tooling-integration.html">Tooling Integration</a>
</li>
<li>
<a href="/react/docs/addons.html">Add-Ons</a>
<ul>
<li>
<a href="/react/docs/animation.html">Animation</a>
</li>
<li>
<a href="/react/docs/two-way-binding-helpers.html">Two-Way Binding Helpers</a>
</li>
<li>
<a href="/react/docs/test-utils.html">Test Utilities</a>
</li>
<li>
<a href="/react/docs/clone-with-props.html">Cloning Elements</a>
</li>
<li>
<a href="/react/docs/create-fragment.html">Keyed Fragments</a>
</li>
<li>
<a href="/react/docs/update.html">Immutability Helpers</a>
</li>
<li>
<a href="/react/docs/pure-render-mixin.html">PureRenderMixin</a>
</li>
<li>
<a href="/react/docs/perf.html">Performance Tools</a>
</li>
<li>
<a href="/react/docs/shallow-compare.html">Shallow Compare</a>
</li>
</ul>
</li>
<li>
<a href="/react/docs/advanced-performance.html">Advanced Performance</a>
</li>
<li>
<a href="/react/docs/context.html">Context</a>
</li>
</ul>
</div>
<div class="nav-docs-section">
<h3>Reference</h3>
<ul>
<li>
<a href="/react/docs/top-level-api.html">Top-Level API</a>
</li>
<li>
<a href="/react/docs/component-api.html">Component API</a>
</li>
<li>
<a href="/react/docs/component-specs.html">Component Specs and Lifecycle</a>
</li>
<li>
<a href="/react/docs/tags-and-attributes.html">Supported Tags and Attributes</a>
</li>
<li>
<a href="/react/docs/events.html" class="active">Event System</a>
</li>
<li>
<a href="/react/docs/dom-differences.html">DOM Differences</a>
</li>
<li>
<a href="/react/docs/special-non-dom-attributes.html">Special Non-DOM Attributes</a>
</li>
<li>
<a href="/react/docs/reconciliation.html">Reconciliation</a>
</li>
<li>
<a href="/react/docs/webcomponents.html">Web Components</a>
</li>
<li>
<a href="/react/docs/glossary.html">React (Virtual) DOM Terminology</a>
</li>
</ul>
</div>
<div class="nav-docs-section">
<h3>Flux</h3>
<ul>
<li>
<a href="https://facebook.github.io/flux/docs/overview.html">Flux Overview</a>
</li>
<li>
<a href="https://facebook.github.io/flux/docs/todo-list.html">Flux TodoMVC Tutorial</a>
</li>
</ul>
</div>
<!-- Tips Nav -->
<div class="nav-docs-section">
<h3>Tips</h3>
<ul>
<li>
<a href="/react/tips/introduction.html">Introduction</a>
</li>
<li>
<a href="/react/tips/inline-styles.html">Inline Styles</a>
</li>
<li>
<a href="/react/tips/if-else-in-JSX.html">If-Else in JSX</a>
</li>
<li>
<a href="/react/tips/self-closing-tag.html">Self-Closing Tag</a>
</li>
<li>
<a href="/react/tips/maximum-number-of-jsx-root-nodes.html">Maximum Number of JSX Root Nodes</a>
</li>
<li>
<a href="/react/tips/style-props-value-px.html">Shorthand for Specifying Pixel Values in style props</a>
</li>
<li>
<a href="/react/tips/children-props-type.html">Type of the Children props</a>
</li>
<li>
<a href="/react/tips/controlled-input-null-value.html">Value of null for Controlled Input</a>
</li>
<li>
<a href="/react/tips/componentWillReceiveProps-not-triggered-after-mounting.html">componentWillReceiveProps Not Triggered After Mounting</a>
</li>
<li>
<a href="/react/tips/props-in-getInitialState-as-anti-pattern.html">Props in getInitialState Is an Anti-Pattern</a>
</li>
<li>
<a href="/react/tips/dom-event-listeners.html">DOM Event Listeners in a Component</a>
</li>
<li>
<a href="/react/tips/initial-ajax.html">Load Initial Data via AJAX</a>
</li>
<li>
<a href="/react/tips/false-in-jsx.html">False in JSX</a>
</li>
<li>
<a href="/react/tips/communicate-between-components.html">Communicate Between Components</a>
</li>
<li>
<a href="/react/tips/expose-component-functions.html">Expose Component Functions</a>
</li>
<li>
<a href="/react/tips/children-undefined.html">this.props.children undefined</a>
</li>
<li>
<a href="/react/tips/use-react-with-other-libraries.html">Use React with Other Libraries</a>
</li>
<li>
<a href="/react/tips/dangerously-set-inner-html.html">Dangerously Set innerHTML</a>
</li>
</ul>
</div>
</div>
<div class="inner-content">
<h1>
Event System
<a class="edit-page-link" href="https://github.com/facebook/react/tree/master/docs/docs/ref-05-events.md" target="_blank">Edit on GitHub</a>
</h1>
<div class="subHeader"></div>
<h2><a class="anchor" name="syntheticevent"></a>SyntheticEvent <a class="hash-link" href="#syntheticevent">#</a></h2>
<p>Your event handlers will be passed instances of <code>SyntheticEvent</code>, a cross-browser wrapper around the browser&#39;s native event. It has the same interface as the browser&#39;s native event, including <code>stopPropagation()</code> and <code>preventDefault()</code>, except the events work identically across all browsers.</p>
<p>If you find that you need the underlying browser event for some reason, simply use the <code>nativeEvent</code> attribute to get it. Every <code>SyntheticEvent</code> object has the following attributes:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="kr">boolean</span> <span class="nx">bubbles</span>
<span class="kr">boolean</span> <span class="nx">cancelable</span>
<span class="nx">DOMEventTarget</span> <span class="nx">currentTarget</span>
<span class="kr">boolean</span> <span class="nx">defaultPrevented</span>
<span class="nx">number</span> <span class="nx">eventPhase</span>
<span class="kr">boolean</span> <span class="nx">isTrusted</span>
<span class="nx">DOMEvent</span> <span class="nx">nativeEvent</span>
<span class="k">void</span> <span class="nx">preventDefault</span><span class="p">()</span>
<span class="kr">boolean</span> <span class="nx">isDefaultPrevented</span><span class="p">()</span>
<span class="k">void</span> <span class="nx">stopPropagation</span><span class="p">()</span>
<span class="kr">boolean</span> <span class="nx">isPropagationStopped</span><span class="p">()</span>
<span class="nx">DOMEventTarget</span> <span class="nx">target</span>
<span class="nx">number</span> <span class="nx">timeStamp</span>
<span class="nx">string</span> <span class="nx">type</span>
</code></pre></div>
<blockquote>
<p>Note:</p>
<p>As of v0.14, returning <code>false</code> from an event handler will no longer stop event propagation. Instead, <code>e.stopPropagation()</code> or <code>e.preventDefault()</code> should be triggered manually, as appropriate.</p>
</blockquote>
<h2><a class="anchor" name="event-pooling"></a>Event pooling <a class="hash-link" href="#event-pooling">#</a></h2>
<p>The <code>SyntheticEvent</code> is pooled. This means that the <code>SyntheticEvent</code> object will be reused and all properties will be nullified after the event callback has been invoked.
This is for performance reasons.
As such, you cannot access the event in an asynchronous way.</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="kd">function</span> <span class="nx">onClick</span><span class="p">(</span><span class="nx">event</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">event</span><span class="p">);</span> <span class="c1">// =&gt; nullified object.</span>
<span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">event</span><span class="p">.</span><span class="nx">type</span><span class="p">);</span> <span class="c1">// =&gt; &quot;click&quot;</span>
<span class="kd">var</span> <span class="nx">eventType</span> <span class="o">=</span> <span class="nx">event</span><span class="p">.</span><span class="nx">type</span><span class="p">;</span> <span class="c1">// =&gt; &quot;click&quot;</span>
<span class="nx">setTimeout</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">event</span><span class="p">.</span><span class="nx">type</span><span class="p">);</span> <span class="c1">// =&gt; null</span>
<span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="nx">eventType</span><span class="p">);</span> <span class="c1">// =&gt; &quot;click&quot;</span>
<span class="p">},</span> <span class="mi">0</span><span class="p">);</span>
<span class="k">this</span><span class="p">.</span><span class="nx">setState</span><span class="p">({</span><span class="nx">clickEvent</span><span class="o">:</span> <span class="nx">event</span><span class="p">});</span> <span class="c1">// Won&#39;t work. this.state.clickEvent will only contain null values.</span>
<span class="k">this</span><span class="p">.</span><span class="nx">setState</span><span class="p">({</span><span class="nx">eventType</span><span class="o">:</span> <span class="nx">event</span><span class="p">.</span><span class="nx">type</span><span class="p">});</span> <span class="c1">// You can still export event properties.</span>
<span class="p">}</span>
</code></pre></div>
<blockquote>
<p>Note:</p>
<p>If you want to access the event properties in an asynchronous way, you should call <code>event.persist()</code> on the event, which will remove the synthetic event from the pool and allow references to the event to be retained by user code.</p>
</blockquote>
<h2><a class="anchor" name="supported-events"></a>Supported Events <a class="hash-link" href="#supported-events">#</a></h2>
<p>React normalizes events so that they have consistent properties across
different browsers.</p>
<p>The event handlers below are triggered by an event in the bubbling phase. To register an event handler for the capture phase, append <code>Capture</code> to the event name; for example, instead of using <code>onClick</code>, you would use <code>onClickCapture</code> to handle the click event in the capture phase.</p>
<h3><a class="anchor" name="clipboard-events"></a>Clipboard Events <a class="hash-link" href="#clipboard-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onCopy onCut onPaste
</code></pre></div>
<p>Properties:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="nx">DOMDataTransfer</span> <span class="nx">clipboardData</span>
</code></pre></div><h3><a class="anchor" name="composition-events"></a>Composition Events <a class="hash-link" href="#composition-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onCompositionEnd onCompositionStart onCompositionUpdate
</code></pre></div>
<p>Properties:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="nx">string</span> <span class="nx">data</span>
</code></pre></div><h3><a class="anchor" name="keyboard-events"></a>Keyboard Events <a class="hash-link" href="#keyboard-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onKeyDown onKeyPress onKeyUp
</code></pre></div>
<p>Properties:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="kr">boolean</span> <span class="nx">altKey</span>
<span class="nx">number</span> <span class="nx">charCode</span>
<span class="kr">boolean</span> <span class="nx">ctrlKey</span>
<span class="kr">boolean</span> <span class="nx">getModifierState</span><span class="p">(</span><span class="nx">key</span><span class="p">)</span>
<span class="nx">string</span> <span class="nx">key</span>
<span class="nx">number</span> <span class="nx">keyCode</span>
<span class="nx">string</span> <span class="nx">locale</span>
<span class="nx">number</span> <span class="nx">location</span>
<span class="kr">boolean</span> <span class="nx">metaKey</span>
<span class="kr">boolean</span> <span class="nx">repeat</span>
<span class="kr">boolean</span> <span class="nx">shiftKey</span>
<span class="nx">number</span> <span class="nx">which</span>
</code></pre></div><h3><a class="anchor" name="focus-events"></a>Focus Events <a class="hash-link" href="#focus-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onFocus onBlur
</code></pre></div>
<p>Properties:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="nx">DOMEventTarget</span> <span class="nx">relatedTarget</span>
</code></pre></div><h3><a class="anchor" name="form-events"></a>Form Events <a class="hash-link" href="#form-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onChange onInput onSubmit
</code></pre></div>
<p>For more information about the onChange event, see <a href="/react/docs/forms.html">Forms</a>.</p>
<h3><a class="anchor" name="mouse-events"></a>Mouse Events <a class="hash-link" href="#mouse-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit
onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
onMouseMove onMouseOut onMouseOver onMouseUp
</code></pre></div>
<p>The <code>onMouseEnter</code> and <code>onMouseLeave</code> events propagate from the element being left to the one being entered instead of ordinary bubbling and do not have a capture phase.</p>
<p>Properties:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="kr">boolean</span> <span class="nx">altKey</span>
<span class="nx">number</span> <span class="nx">button</span>
<span class="nx">number</span> <span class="nx">buttons</span>
<span class="nx">number</span> <span class="nx">clientX</span>
<span class="nx">number</span> <span class="nx">clientY</span>
<span class="kr">boolean</span> <span class="nx">ctrlKey</span>
<span class="kr">boolean</span> <span class="nx">getModifierState</span><span class="p">(</span><span class="nx">key</span><span class="p">)</span>
<span class="kr">boolean</span> <span class="nx">metaKey</span>
<span class="nx">number</span> <span class="nx">pageX</span>
<span class="nx">number</span> <span class="nx">pageY</span>
<span class="nx">DOMEventTarget</span> <span class="nx">relatedTarget</span>
<span class="nx">number</span> <span class="nx">screenX</span>
<span class="nx">number</span> <span class="nx">screenY</span>
<span class="kr">boolean</span> <span class="nx">shiftKey</span>
</code></pre></div><h3><a class="anchor" name="selection-events"></a>Selection Events <a class="hash-link" href="#selection-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onSelect
</code></pre></div><h3><a class="anchor" name="touch-events"></a>Touch Events <a class="hash-link" href="#touch-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onTouchCancel onTouchEnd onTouchMove onTouchStart
</code></pre></div>
<p>Properties:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="kr">boolean</span> <span class="nx">altKey</span>
<span class="nx">DOMTouchList</span> <span class="nx">changedTouches</span>
<span class="kr">boolean</span> <span class="nx">ctrlKey</span>
<span class="kr">boolean</span> <span class="nx">getModifierState</span><span class="p">(</span><span class="nx">key</span><span class="p">)</span>
<span class="kr">boolean</span> <span class="nx">metaKey</span>
<span class="kr">boolean</span> <span class="nx">shiftKey</span>
<span class="nx">DOMTouchList</span> <span class="nx">targetTouches</span>
<span class="nx">DOMTouchList</span> <span class="nx">touches</span>
</code></pre></div><h3><a class="anchor" name="ui-events"></a>UI Events <a class="hash-link" href="#ui-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onScroll
</code></pre></div>
<p>Properties:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="nx">number</span> <span class="nx">detail</span>
<span class="nx">DOMAbstractView</span> <span class="nx">view</span>
</code></pre></div><h3><a class="anchor" name="wheel-events"></a>Wheel Events <a class="hash-link" href="#wheel-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onWheel
</code></pre></div>
<p>Properties:</p>
<div class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="nx">number</span> <span class="nx">deltaMode</span>
<span class="nx">number</span> <span class="nx">deltaX</span>
<span class="nx">number</span> <span class="nx">deltaY</span>
<span class="nx">number</span> <span class="nx">deltaZ</span>
</code></pre></div><h3><a class="anchor" name="media-events"></a>Media Events <a class="hash-link" href="#media-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onAbort onCanPlay onCanPlayThrough onDurationChange onEmptied onEncrypted onEnded onError onLoadedData onLoadedMetadata onLoadStart onPause onPlay onPlaying onProgress onRateChange onSeeked onSeeking onStalled onSuspend onTimeUpdate onVolumeChange onWaiting
</code></pre></div><h3><a class="anchor" name="image-events"></a>Image Events <a class="hash-link" href="#image-events">#</a></h3>
<p>Event names:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text">onLoad onError
</code></pre></div>
<div class="docs-prevnext">
<a class="docs-prev" href="/react/docs/tags-and-attributes.html">&larr; Prev</a>
<a class="docs-next" href="/react/docs/dom-differences.html">Next &rarr;</a>
</div>
</div>
</section>
<footer class="wrap">
<div class="left">
A Facebook &amp; Instagram collaboration.<br>
<a href="/react/acknowledgements.html">Acknowledgements</a>
</div>
<div class="right">
&copy; 2013&ndash;2016 Facebook Inc.<br>
Documentation licensed under <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>.
</div>
</footer>
</div>
<div id="fb-root"></div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-41298772-1', 'facebook.github.io');
ga('send', 'pageview');
!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="https://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
(function(d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); js.id = id;
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1&appId=623268441017527";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));
</script>
</body>
</html>