mirror of
https://github.com/facebook/react.git
synced 2025-11-01 09:12:30 +00:00
Paul O’Shannessy
458 lines
23 KiB
HTML
458 lines
23 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
|
<title>React | Component Specs and Lifecycle</title>
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta property="og:title" content="React | Component Specs and Lifecycle" />
|
|
<meta property="og:type" content="website" />
|
|
<meta property="og:url" content="http://facebook.github.io/react/docs/component-specs.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" />
|
|
<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="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">
|
|
<!-- 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>
|
|
|
|
</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/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/class-name-manipulation.html">
|
|
Class Name Manipulation
|
|
</a>
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/react/docs/examples.html">
|
|
Examples
|
|
</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" class="active">
|
|
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">
|
|
Event System
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/react/docs/dom-differences.html">
|
|
DOM Differences
|
|
</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>
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
|
|
<div class="inner-content">
|
|
<h1>Component Specs and Lifecycle</h1>
|
|
<div class="subHeader"></div>
|
|
<h2><a class="anchor" name="component-specifications"></a>Component Specifications <a class="hash-link" href="#component-specifications">#</a></h2>
|
|
<p>When creating a component class by invoking <code>React.createClass()</code>, you should provide a specification object that contains a <code>render</code> method and can optionally contain other lifecycle methods described here.</p>
|
|
<h3><a class="anchor" name="render"></a>render <a class="hash-link" href="#render">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">ReactComponent</span> <span class="nx">render</span><span class="p">()</span>
|
|
</code></pre></div>
|
|
<p>The <code>render()</code> method is required.</p>
|
|
|
|
<p>When called, it should examine <code>this.props</code> and <code>this.state</code> and return a single child component. This child component can be either a native DOM component (such as <code><div></code>) or another composite component that you've defined yourself.</p>
|
|
|
|
<p>The <code>render()</code> function should be <em>pure</em>, meaning that it does not modify component state, it returns the same result each time it's invoked, and it does not read from or write to the DOM or otherwise interact with the browser (e.g., by using <code>setTimeout</code>). If you need to interact with the browser, perform your work in <code>componentDidMount()</code> or the other lifecycle methods instead. Keeping <code>render()</code> pure makes server rendering more practical and makes components easier to think about.</p>
|
|
<h3><a class="anchor" name="getinitialstate"></a>getInitialState <a class="hash-link" href="#getinitialstate">#</a></h3><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>
|
|
</code></pre></div>
|
|
<p>Invoked once before the component is mounted. The return value will be used as the initial value of <code>this.state</code>.</p>
|
|
<h3><a class="anchor" name="getdefaultprops"></a>getDefaultProps <a class="hash-link" href="#getdefaultprops">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">object</span> <span class="nx">getDefaultProps</span><span class="p">()</span>
|
|
</code></pre></div>
|
|
<p>Invoked once when the component is mounted. Values in the mapping will be set on <code>this.props</code> if that prop is not specified by the parent component (i.e. using an <code>in</code> check).</p>
|
|
|
|
<p>This method is invoked before <code>getInitialState</code> and therefore cannot rely on <code>this.state</code> or use <code>this.setState</code>.</p>
|
|
<h3><a class="anchor" name="proptypes"></a>propTypes <a class="hash-link" href="#proptypes">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">object</span> <span class="nx">propTypes</span>
|
|
</code></pre></div>
|
|
<p>The <code>propTypes</code> object allows you to validate props being passed to your components. For more information about <code>propTypes</code>, see <a href="reusable-components.html">Reusable Components</a>.</p>
|
|
|
|
<!-- TODO: Document propTypes here directly. -->
|
|
<h3><a class="anchor" name="mixins"></a>mixins <a class="hash-link" href="#mixins">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">array</span> <span class="nx">mixins</span>
|
|
</code></pre></div>
|
|
<p>The <code>mixins</code> array allows you to use mixins to share behavior among multiple components. For more information about mixins, see <a href="reusable-components.html">Reusable Components</a>.</p>
|
|
|
|
<!-- TODO: Document mixins here directly. -->
|
|
<h2><a class="anchor" name="lifecycle-methods"></a>Lifecycle Methods <a class="hash-link" href="#lifecycle-methods">#</a></h2>
|
|
<p>Various methods are executed at specific points in a component's lifecycle.</p>
|
|
<h3><a class="anchor" name="mounting-componentwillmount"></a>Mounting: componentWillMount <a class="hash-link" href="#mounting-componentwillmount">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">componentWillMount</span><span class="p">()</span>
|
|
</code></pre></div>
|
|
<p>Invoked immediately before rendering occurs. If you call <code>setState</code> within this method, <code>render()</code> will see the updated state and will be executed only once despite the state change.</p>
|
|
<h3><a class="anchor" name="mounting-componentdidmount"></a>Mounting: componentDidMount <a class="hash-link" href="#mounting-componentdidmount">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">componentDidMount</span><span class="p">(</span><span class="nx">DOMElement</span> <span class="nx">rootNode</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Invoked immediately after rendering occurs. At this point in the lifecycle, the component has a DOM representation which you can access via the <code>rootNode</code> argument or by calling <code>this.getDOMNode()</code>.</p>
|
|
|
|
<p>If you want to integrate with other JavaScript frameworks, set timers using <code>setTimeout</code> or <code>setInterval</code>, or send AJAX requests, perform those operations in this method.</p>
|
|
<h3><a class="anchor" name="updating-componentwillreceiveprops"></a>Updating: componentWillReceiveProps <a class="hash-link" href="#updating-componentwillreceiveprops">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">componentWillReceiveProps</span><span class="p">(</span><span class="nx">object</span> <span class="nx">nextProps</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Invoked when a component is receiving new props. This method is not called for the initial render.</p>
|
|
|
|
<p>Use this as an opportunity to react to a prop transition before <code>render()</code> is called by updating the state using <code>this.setState()</code>. The old props can be accessed via <code>this.props</code>. Calling <code>this.setState()</code> within this function will not trigger an additional render.</p>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">componentWillReceiveProps</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">nextProps</span><span class="p">)</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">likesIncreasing</span><span class="o">:</span> <span class="nx">nextProps</span><span class="p">.</span><span class="nx">likeCount</span> <span class="o">></span> <span class="k">this</span><span class="p">.</span><span class="nx">props</span><span class="p">.</span><span class="nx">likeCount</span>
|
|
<span class="p">});</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
<blockquote>
|
|
<p>Note:</p>
|
|
|
|
<p>There is no analogous method <code>componentWillReceiveState</code>. An incoming prop transition may cause a state change, but the opposite is not true. If you need to perform operations in response to a state change, use <code>componentWillUpdate</code>.</p>
|
|
</blockquote>
|
|
<h3><a class="anchor" name="updating-shouldcomponentupdate"></a>Updating: shouldComponentUpdate <a class="hash-link" href="#updating-shouldcomponentupdate">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><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>
|
|
</code></pre></div>
|
|
<p>Invoked before rendering when new props or state are being received. This method is not called for the initial render or when <code>forceUpdate</code> is used.</p>
|
|
|
|
<p>Use this as an opportunity to <code>return false</code> when you're certain that the
|
|
transition to the new props and state will not require a component update.</p>
|
|
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">shouldComponentUpdate</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">nextProps</span><span class="p">,</span> <span class="nx">nextState</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="k">return</span> <span class="o">!</span><span class="nx">equal</span><span class="p">(</span><span class="nx">nextProps</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">props</span><span class="p">)</span> <span class="o">||</span> <span class="o">!</span><span class="nx">equal</span><span class="p">(</span><span class="nx">nextState</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">state</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
<p>If <code>shouldComponentUpdate</code> returns false, then <code>render()</code> will be completely skipped until the next state change. (In addition, <code>componentWillUpdate</code> and <code>componentDidUpdate</code> will not be called.)</p>
|
|
|
|
<p>By default, <code>shouldComponentUpdate</code> always returns true to prevent subtle bugs when <code>state</code> is mutated in place, but if you are careful to always treat <code>state</code> as immutable and to read only from <code>props</code> and <code>state</code> in <code>render()</code> then you can override <code>shouldComponentUpdate</code> with an implementation that compares the old props and state to their replacements.</p>
|
|
|
|
<p>If performance is a bottleneck, especially with dozens or hundreds of components, use <code>shouldComponentUpdate</code> to speed up your app.</p>
|
|
<h3><a class="anchor" name="updating-componentwillupdate"></a>Updating: componentWillUpdate <a class="hash-link" href="#updating-componentwillupdate">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><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>
|
|
</code></pre></div>
|
|
<p>Invoked immediately before rendering when new props or state are being received. This method is not called for the initial render.</p>
|
|
|
|
<p>Use this as an opportunity to perform preparation before an update occurs.</p>
|
|
|
|
<blockquote>
|
|
<p>Note:</p>
|
|
|
|
<p>You <em>cannot</em> use <code>this.setState()</code> in this method. If you need to update state in response to a prop change, use <code>componentWillReceiveProps</code> instead.</p>
|
|
</blockquote>
|
|
<h3><a class="anchor" name="updating-componentdidupdate"></a>Updating: componentDidUpdate <a class="hash-link" href="#updating-componentdidupdate">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><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">rootNode</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p>Invoked immediately after updating occurs. This method is not called for the initial render.</p>
|
|
|
|
<p>Use this as an opportunity to operate on the DOM when the component has been updated.</p>
|
|
<h3><a class="anchor" name="unmounting-componentwillunmount"></a>Unmounting: componentWillUnmount <a class="hash-link" href="#unmounting-componentwillunmount">#</a></h3><div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="nx">componentWillUnmount</span><span class="p">()</span>
|
|
</code></pre></div>
|
|
<p>Invoked immediately before a component is unmounted from the DOM.</p>
|
|
|
|
<p>Perform any necessary cleanup in this method, such as invalidating timers or cleaning up any DOM elements that were created in <code>componentDidMount</code>.</p>
|
|
|
|
|
|
<div class="docs-prevnext">
|
|
|
|
<a class="docs-prev" href="/react/docs/component-api.html">← Prev</a>
|
|
|
|
|
|
<a class="docs-next" href="/react/docs/tags-and-attributes.html">Next →</a>
|
|
|
|
</div>
|
|
|
|
<div class="fb-comments" data-width="650" data-num-posts="10" data-href="http://facebook.github.io/react/docs/component-specs.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>
|