mirror of
https://github.com/facebook/react.git
synced 2025-11-01 09:12:30 +00:00
Paul O’Shannessy
374 lines
20 KiB
HTML
374 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
|
<title>React | Reference</title>
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta property="og:title" content="React | Reference" />
|
|
<meta property="og:type" content="website" />
|
|
<meta property="og:url" content="http://facebook.github.io/react/docs/reference.html" />
|
|
<meta property="og:image" content="http://facebook.github.io/react/img/logo_og.png" />
|
|
<meta property="og:description" content="A JavaScript library for building user interfaces" />
|
|
|
|
<link rel="shortcut icon" href="/react/favicon.ico">
|
|
<link rel="alternate" type="application/rss+xml" title="React" href="http://facebook.github.io/react/feed.xml">
|
|
|
|
<link rel="stylesheet" href="/react/css/react.css">
|
|
<link rel="stylesheet" href="/react/css/syntax.css">
|
|
<link rel="stylesheet" href="/react/css/codemirror.css">
|
|
|
|
<script type="text/javascript" src="//use.typekit.net/vqa1hcx.js"></script>
|
|
<script type="text/javascript">try{Typekit.load();}catch(e){}</script>
|
|
|
|
<script type="text/javascript" src="/react/js/codemirror.js"></script>
|
|
<script type="text/javascript" src="/react/js/javascript.js"></script>
|
|
<script type="text/javascript" src="/react/js/react.min.js"></script>
|
|
<script type="text/javascript" src="/react/js/JSXTransformer.js"></script>
|
|
<script type="text/javascript" src="/react/js/live_editor.js"></script>
|
|
<script type="text/javascript" src="/react/js/showdown.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" alt="" src="/react/img/logo_small.png" width="38" height="38">
|
|
React
|
|
</a>
|
|
<ul class="nav-site">
|
|
<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>
|
|
<li><a href="http://github.com/facebook/react">github</a>
|
|
</ul>
|
|
<!-- <iframe src="http://ghbtns.com/github-btn.html?user=facebook&repo=react.js&type=fork"allowtransparency="true" frameborder="0" scrolling="0" width="62" height="20"></iframe> -->
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<section class="content wrap documentationContent">
|
|
<div class="nav-docs">
|
|
|
|
<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>
|
|
|
|
</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-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/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">
|
|
More About Refs
|
|
</a>
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/react/docs/tooling-integration.html">
|
|
Tooling integration
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/react/docs/reference.html" class="active">
|
|
Reference
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
|
|
<div class="inner-content">
|
|
<h1>Reference</h1>
|
|
<div class="subHeader"></div>
|
|
<h2>Examples</h2>
|
|
|
|
<h3>Production Apps</h3>
|
|
|
|
<ul>
|
|
<li>All of <a href="http://instagram.com/">Instagram.com</a> is built on React.</li>
|
|
<li>Many components on <a href="http://www.facebook.com/">Facebook.com</a>, including the commenting interface, ads creation flows, and page insights.</li>
|
|
<li><a href="http://khanacademy.org/">Khan Academy</a> is using React for its question editor.</li>
|
|
</ul>
|
|
|
|
<h3>Sample Code</h3>
|
|
|
|
<ul>
|
|
<li>We've included <a href="./tutorial.html">a step-by-step comment box tutorial</a>.</li>
|
|
<li><a href="/react/downloads.html">The React starter kit</a> includes several examples which you can <a href="https://github.com/facebook/react/tree/master/examples/">view online in our GitHub repository</a>.</li>
|
|
<li><a href="https://github.com/jordwalke/reactapp">reactapp</a> is a simple app template to get you up-and-running quickly with React.</li>
|
|
<li><a href="https://github.com/petehunt/react-one-hour-email/commits/master">React one-hour email</a> goes step-by-step from a static HTML mock to an interactive email reader (written in just one hour!)</li>
|
|
<li><a href="https://github.com/petehunt/rendr-react-template/">Rendr + React app template</a> demonstrates how to use React's server rendering capabilities.</li>
|
|
</ul>
|
|
|
|
<h2>API</h2>
|
|
|
|
<h3>React</h3>
|
|
|
|
<p><code>React</code> is the entry point to the React framework. If you're using one of the prebuilt packages it's available as a global; if you're using CommonJS modules you can <code>require()</code> it.</p>
|
|
|
|
<h4>React.DOM</h4>
|
|
|
|
<p><code>React.DOM</code> provides all of the standard HTML tags needed to build a React app. You generally don't use it directly; instead, just include it as part of the <code>/** @jsx React.DOM */</code> docblock.</p>
|
|
|
|
<h4>React.initializeTouchEvents</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">initializeTouchEvents</span><span class="p">(</span><span class="kr">boolean</span> <span class="nx">shouldUseTouch</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Configure React's event system to handle touch events on mobile devices.</p>
|
|
|
|
<h4>React.createClass</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="kd">function</span> <span class="nx">createClass</span><span class="p">(</span><span class="nx">object</span> <span class="nx">specification</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Creates a component given a specification. A component implements a <code>render</code> method which returns <strong>one single</strong> child. That child may have an arbitrarily deep child structure. One thing that makes components different than a standard prototypal classes is that you don't need to call new on them. They are convenience wrappers that construct backing instances (via new) for you.</p>
|
|
|
|
<h4>React.renderComponent</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">ReactComponent</span> <span class="nx">renderComponent</span><span class="p">(</span><span class="nx">ReactComponent</span> <span class="nx">container</span><span class="p">,</span> <span class="nx">DOMElement</span> <span class="nx">container</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Renders a React component into the DOM in the supplied <code>container</code>.</p>
|
|
|
|
<p>If the React component was previously rendered into <code>container</code>, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component.</p>
|
|
|
|
<h4>React.unmountAndReleaseReactRootNode</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">unmountAndReleaseReactRootNode</span><span class="p">(</span><span class="nx">DOMElement</span> <span class="nx">container</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Remove a mounted React component from the DOM and clean up its event handlers and state.</p>
|
|
|
|
<h4>React.renderComponentToString</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">renderComponentToString</span><span class="p">(</span><span class="nx">ReactComponent</span> <span class="nx">component</span><span class="p">,</span> <span class="kd">function</span> <span class="nx">callback</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Render a component to its initial HTML. This should only be used on the server. React will call <code>callback</code> with an HTML string when the markup is ready. You can use this method to create static site generators, or you can generate HTML on the server and send it down to have a very fast initial page load. If you call <code>React.renderComponent()</code> on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.</p>
|
|
|
|
<h3>AbstractEvent</h3>
|
|
|
|
<p>Your event handlers will be passed instances of <code>AbstractEvent</code>, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event (such as <code>stopPropagation()</code> and <code>preventDefault()</code>) except they work exactly the same 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.</p>
|
|
|
|
<h3>ReactComponent</h3>
|
|
|
|
<p>Component classses created by <code>createClass()</code> return instances of <code>ReactComponent</code> when called. Most of the time when you're using React you're either creating or consuming <code>ReactComponent</code>s.</p>
|
|
|
|
<h4>getDOMNode</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">DOMElement</span> <span class="nx">getDOMNode</span><span class="p">()</span>
|
|
</code></pre></div>
|
|
<p>If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements.</p>
|
|
|
|
<h4>setProps</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">setProps</span><span class="p">(</span><span class="nx">object</span> <span class="nx">nextProps</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with <code>renderComponent()</code>. Simply call <code>setProps()</code> to change its properties and trigger a re-render.</p>
|
|
|
|
<blockquote>
|
|
<p>Note:</p>
|
|
|
|
<p>This method can only be called on a root-level component. That is, it's only available on the component passed directly to <code>renderComponent()</code> and none of its children. If you're inclined to use <code>setProps()</code> on a child component, instead take advantage of reactive updates and pass the new prop to the child component when it's created in <code>render()</code>.</p>
|
|
</blockquote>
|
|
|
|
<h4>replaceProps</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">replaceProps</span><span class="p">(</span><span class="nx">object</span> <span class="nx">nextProps</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Like <code>setProps()</code> but deletes any pre-existing props that are not in nextProps.</p>
|
|
|
|
<h4>transferPropsTo</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">ReactComponent</span> <span class="nx">transferPropsTo</span><span class="p">(</span><span class="nx">ReactComponent</span> <span class="nx">targetComponent</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Transfer properties from this component to a target component that have not already been set on the target component. This is usually used to pass down properties to the returned root component. <code>targetComponent</code>, now updated with some new props is returned as a convenience.</p>
|
|
|
|
<h4>setState</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">setState</span><span class="p">(</span><span class="nx">object</span> <span class="nx">nextState</span><span class="p">[,</span> <span class="kd">function</span> <span class="nx">callback</span><span class="p">])</span>
|
|
</code></pre></div>
|
|
<p>Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks. In addition, you can supply an optional callback function that is executed once <code>setState</code> is completed.</p>
|
|
|
|
<blockquote>
|
|
<p>Note:</p>
|
|
|
|
<p><em>NEVER</em> mutate <code>this.state</code> directly. As calling <code>setState()</code> afterwards may replace the mutation you made. Treat <code>this.state</code> as if it were immutable.</p>
|
|
|
|
<p>Note:</p>
|
|
|
|
<p><code>setState()</code> does not immediately mutate <code>this.state</code> but creates a pending state transition. Accessing <code>this.state</code> after calling this method can potentially return the existing value.</p>
|
|
|
|
<p>Note:</p>
|
|
|
|
<p>There is no guarantee of synchronous operation of calls to <code>setState</code> and calls may be batched for performance gains.</p>
|
|
</blockquote>
|
|
|
|
<h4>replaceState</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">replaceState</span><span class="p">(</span><span class="nx">object</span> <span class="nx">nextState</span><span class="p">[,</span> <span class="kd">function</span> <span class="nx">callback</span><span class="p">])</span>
|
|
</code></pre></div>
|
|
<p>Like <code>setState()</code> but deletes any pre-existing state keys that are not in nextState.</p>
|
|
|
|
<h4>forceUpdate()</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">forceUpdate</span><span class="p">([</span><span class="kd">function</span> <span class="nx">callback</span><span class="p">])</span>
|
|
</code></pre></div>
|
|
<p>If your <code>render()</code> method reads from something other than <code>this.props</code> or <code>this.state</code> you'll need to tell React when it needs to re-run <code>render()</code>. Use <code>forceUpdate()</code> to cause React to automatically re-render. This will cause <code>render()</code> to be called on the component and all of its children but React will only update the DOM if the markup changes.</p>
|
|
|
|
<p>Normally you should try to avoid all uses of <code>forceUpdate()</code> and only read from <code>this.props</code> and <code>this.state</code> in <code>render()</code>. This makes your application much simpler and more efficient.</p>
|
|
|
|
<blockquote>
|
|
<p>Note:</p>
|
|
|
|
<p>There is no guarantee of synchronous operation of calls to <code>forceUpdate</code> and calls may be batched for performance gains.</p>
|
|
</blockquote>
|
|
|
|
<h4>Lifecycle methods</h4>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">object</span> <span class="nx">getInitialState</span><span class="p">()</span>
|
|
<span class="nx">componentWillMount</span><span class="p">()</span>
|
|
<span class="nx">componentDidMount</span><span class="p">(</span><span class="nx">DOMElement</span> <span class="nx">domNode</span><span class="p">)</span>
|
|
<span class="nx">componentWillReceiveProps</span><span class="p">(</span><span class="nx">object</span> <span class="nx">nextProps</span><span class="p">)</span>
|
|
<span class="kr">boolean</span> <span class="nx">shouldComponentUpdate</span><span class="p">(</span><span class="nx">object</span> <span class="nx">nextProps</span><span class="p">,</span> <span class="nx">object</span> <span class="nx">nextState</span><span class="p">)</span>
|
|
<span class="nx">componentWillUpdate</span><span class="p">(</span><span class="nx">object</span> <span class="nx">nextProps</span><span class="p">,</span> <span class="nx">object</span> <span class="nx">nextState</span><span class="p">)</span>
|
|
<span class="nx">ReactComponent</span> <span class="nx">render</span><span class="p">()</span>
|
|
<span class="nx">componentDidUpdate</span><span class="p">(</span><span class="nx">object</span> <span class="nx">prevProps</span><span class="p">,</span> <span class="nx">object</span> <span class="nx">prevState</span><span class="p">,</span> <span class="nx">DOMElement</span> <span class="nx">domNode</span><span class="p">)</span>
|
|
<span class="nx">componentWillUnmount</span><span class="p">()</span>
|
|
</code></pre></div>
|
|
<p>See the <a href="./working-with-the-browser.html">working with the browser</a> documentation for more details on these lifecycle methods.</p>
|
|
|
|
<h2>DOM Differences</h2>
|
|
|
|
<p>React has implemented a browser-independent events and DOM system for performance and cross-browser compatibility reasons. We took the opportunity to clean up a few rough edges in browser DOM implementations.</p>
|
|
|
|
<ul>
|
|
<li>All events (including submit) bubble correctly per the W3C spec</li>
|
|
<li>All event objects conform to the W3C spec</li>
|
|
<li>All DOM properties and attributes (including event handlers) should be camelCased to be consistent with standard JavaScript style. We intentionally break with the spec here, since the spec is inconsistent.</li>
|
|
<li>The <code>style</code> attribute accepts a JavaScript object with camelCased properties rather than a CSS string. This is consistent with the DOM <code>style</code> JavaScript property, is more efficient, and prevents XSS security holes.</li>
|
|
<li><code>onChange</code> behaves as you would expect it to: whenever a form field is changed this event is fired rather than inconsistently on blur. We intentionally break from existing browser behavior because <code>onChange</code> is a misnomer for its behavior and React relies on this event to react to user input in real time.</li>
|
|
</ul>
|
|
|
|
|
|
<div class="docs-prevnext">
|
|
|
|
<a class="docs-prev" href="/react/docs/tooling-integration.html">← Prev</a>
|
|
|
|
|
|
</div>
|
|
|
|
<div class="fb-comments" data-width="650" data-num-posts="10" data-href="http://facebook.github.io/react/docs/reference.html"></div>
|
|
</div>
|
|
</section>
|
|
|
|
|
|
<footer class="wrap">
|
|
<div class="left">A Facebook & Instagram collaboration.</div>
|
|
<div class="right">© 2013 Facebook Inc.</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>
|