mirror of
https://github.com/facebook/react.git
synced 2025-11-01 09:12:30 +00:00
389 lines
18 KiB
HTML
389 lines
18 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||
<title>React | Working With the Browser</title>
|
||
<meta name="viewport" content="width=device-width">
|
||
<meta property="og:title" content="React | Working With the Browser" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="http://facebook.github.io/react/docs/working-with-the-browser.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">
|
||
|
||
<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" class="active">
|
||
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>
|
||
|
||
</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">
|
||
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>
|
||
|
||
</div>
|
||
|
||
|
||
<div class="inner-content">
|
||
<h1>Working With the Browser</h1>
|
||
<div class="subHeader"></div>
|
||
<p>React provides powerful abstractions that free you from touching the DOM directly in most cases, but sometimes you simply need to access the underlying API, perhaps to work with a third-party library or existing code.</p>
|
||
<h2 id="the-mock-dom" class="anchor"><a href="#the-mock-dom">The Mock DOM</a></h2>
|
||
<p>React is so fast because it never talks to the DOM directly. React maintains a fast in-memory representation of the DOM. <code>render()</code> methods return a <em>description</em> of the DOM, and React can diff this description with the in-memory representation to compute the fastest way to update the browser.</p>
|
||
|
||
<p>Additionally, React implements a full synthetic event system such that all event objects are guaranteed to conform to the W3C spec despite browser quirks, and everything bubbles consistently and in a performant way cross-browser. You can even use some HTML5 events in IE8!</p>
|
||
|
||
<p>Most of the time you should stay within React's "faked browser" world since it's more performant and easier to reason about. However, sometimes you simply need to access the underlying API, perhaps to work with a third-party library like a jQuery plugin. React provides escape hatches for you to use the underlying DOM API directly.</p>
|
||
<h2 id="refs-and-getdomnode" class="anchor"><a href="#refs-and-getdomnode">Refs and getDOMNode()</a></h2>
|
||
<p>To interact with the browser, you'll need a reference to a DOM node. Every mounted React component has a <code>getDOMNode()</code> function which you can call to get a reference to it.</p>
|
||
|
||
<blockquote>
|
||
<p>Note:</p>
|
||
|
||
<p><code>getDOMNode()</code> only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling <code>getDOMNode()</code> in <code>render()</code> on a component that has yet to be created) an exception will be thrown.</p>
|
||
</blockquote>
|
||
|
||
<p>In order to get a reference to a React component, you can either use <code>this</code> to get the current React component, or you can use refs to refer to a component you own. They work like this:</p>
|
||
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="cm">/** @jsx React.DOM */</span>
|
||
|
||
<span class="kd">var</span> <span class="nx">MyComponent</span> <span class="o">=</span> <span class="nx">React</span><span class="p">.</span><span class="nx">createClass</span><span class="p">({</span>
|
||
<span class="nx">handleClick</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
|
||
<span class="c1">// Explicitly focus the text input using the raw DOM API.</span>
|
||
<span class="k">this</span><span class="p">.</span><span class="nx">refs</span><span class="p">.</span><span class="nx">myTextInput</span><span class="p">.</span><span class="nx">getDOMNode</span><span class="p">().</span><span class="nx">focus</span><span class="p">();</span>
|
||
<span class="p">},</span>
|
||
<span class="nx">render</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
|
||
<span class="c1">// The ref attribute adds a reference to the component to</span>
|
||
<span class="c1">// this.refs when the component is mounted.</span>
|
||
<span class="k">return</span> <span class="p">(</span>
|
||
<span class="o"><</span><span class="nx">div</span><span class="o">></span>
|
||
<span class="o"><</span><span class="nx">input</span> <span class="nx">type</span><span class="o">=</span><span class="s2">"text"</span> <span class="nx">ref</span><span class="o">=</span><span class="s2">"myTextInput"</span> <span class="o">/></span>
|
||
<span class="o"><</span><span class="nx">input</span>
|
||
<span class="nx">type</span><span class="o">=</span><span class="s2">"button"</span>
|
||
<span class="nx">value</span><span class="o">=</span><span class="s2">"Focus the text input"</span>
|
||
<span class="nx">onClick</span><span class="o">=</span><span class="p">{</span><span class="k">this</span><span class="p">.</span><span class="nx">handleClick</span><span class="p">}</span>
|
||
<span class="o">/></span>
|
||
<span class="o"><</span><span class="err">/div></span>
|
||
<span class="p">);</span>
|
||
<span class="p">}</span>
|
||
<span class="p">});</span>
|
||
|
||
<span class="nx">React</span><span class="p">.</span><span class="nx">renderComponent</span><span class="p">(</span>
|
||
<span class="o"><</span><span class="nx">MyComponent</span> <span class="o">/></span><span class="p">,</span>
|
||
<span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s1">'example'</span><span class="p">)</span>
|
||
<span class="p">);</span>
|
||
</code></pre></div><h2 id="more-about-refs" class="anchor"><a href="#more-about-refs">More About Refs</a></h2>
|
||
<p>To learn more about refs, including ways to use them effectively, see our <a href="./more-about-refs.html">more about refs</a> documentation.</p>
|
||
<h2 id="component-lifecycle" class="anchor"><a href="#component-lifecycle">Component Lifecycle</a></h2>
|
||
<p>Components have three main parts of their lifecycle:</p>
|
||
|
||
<ul>
|
||
<li><strong>Mounting:</strong> A component is being inserted into the DOM.</li>
|
||
<li><strong>Updating:</strong> A component is being re-rendered to determine if the DOM should be updated.</li>
|
||
<li><strong>Unmounting:</strong> A component is being removed from the DOM.</li>
|
||
</ul>
|
||
|
||
<p>React provides lifecycle methods that you can specify to hook into this process. We provide <strong>will</strong> methods, which are called right before something happens, and <strong>did</strong> methods which are called right after something happens.</p>
|
||
<h3 id="mounting" class="anchor"><a href="#mounting">Mounting</a></h3>
|
||
<ul>
|
||
<li><code>getInitialState(): object</code> is invoked before a component is mounted. Stateful components should implement this and return the initial state data.</li>
|
||
<li><code>componentWillMount()</code> is invoked immediately before mounting occurs.</li>
|
||
<li><code>componentDidMount(DOMElement rootNode)</code> is invoked immediately after mounting occurs. Initialization that requires DOM nodes should go here.</li>
|
||
</ul>
|
||
<h3 id="updating" class="anchor"><a href="#updating">Updating</a></h3>
|
||
<ul>
|
||
<li><code>componentWillReceiveProps(object nextProps)</code> is invoked when a mounted component receives new props. This method should be used to compare <code>this.props</code> and <code>nextProps</code> to perform state transitions using <code>this.setState()</code>.</li>
|
||
<li><code>shouldComponentUpdate(object nextProps, object nextState): boolean</code> is invoked when a component decides whether any changes warrant an update to the DOM. Implement this as an optimization to compare <code>this.props</code> with <code>nextProps</code> and <code>this.state</code> with <code>nextState</code> and return false if React should skip updating.</li>
|
||
<li><code>componentWillUpdate(object nextProps, object nextState)</code> is invoked immediately before updating occurs. You cannot call <code>this.setState()</code> here.</li>
|
||
<li><code>componentDidUpdate(object prevProps, object prevState, DOMElement rootNode)</code> is invoked immediately after updating occurs.</li>
|
||
</ul>
|
||
<h3 id="unmounting" class="anchor"><a href="#unmounting">Unmounting</a></h3>
|
||
<ul>
|
||
<li><code>componentWillUnmount()</code> is invoked immediately before a component is unmounted and destroyed. Cleanup should go here.</li>
|
||
</ul>
|
||
<h3 id="mounted-methods" class="anchor"><a href="#mounted-methods">Mounted Methods</a></h3>
|
||
<p><em>Mounted</em> composite components also support the following methods:</p>
|
||
|
||
<ul>
|
||
<li><code>getDOMNode(): DOMElement</code> can be invoked on any mounted component in order to obtain a reference to its rendered DOM node.</li>
|
||
<li><code>forceUpdate()</code> can be invoked on any mounted component when you know that some deeper aspect of the component's state has changed without using <code>this.setState()</code>.</li>
|
||
</ul>
|
||
|
||
<blockquote>
|
||
<p>Note:</p>
|
||
|
||
<p>The <code>DOMElement rootNode</code> argument of <code>componentDidMount()</code> and
|
||
<code>componentDidUpdate()</code> is a convenience. The same node can be obtained by
|
||
calling <code>this.getDOMNode()</code>.</p>
|
||
</blockquote>
|
||
<h2 id="browser-support-and-polyfills" class="anchor"><a href="#browser-support-and-polyfills">Browser Support and Polyfills</a></h2>
|
||
<p>At Facebook, we support older browsers, including IE8. We've had polyfills in place for a long time to allow us to write forward-thinking JS. This means we don't have a bunch of hacks scattered throughout our codebase and we can still expect our code to "just work". For example, instead of seeing <code>+new Date()</code>, we can just write <code>Date.now()</code>. Since the open source React is the same as what we use internally, we've carried over this philosophy of using forward thinking JS.</p>
|
||
|
||
<p>In addition to that philosophy, we've also taken the stance that we, as authors of a JS library, should not be shipping polyfills as a part of our library. If every library did this, there's a good chance you'd be sending down the same polyfill multiple times, which could be a sizable chunk of dead code. If your product needs to support older browsers, chances are you're already using something like <a href="https://github.com/kriskowal/es5-shim">es5-shim</a>.</p>
|
||
<h3 id="polyfills-needed-to-support-older-browsers" class="anchor"><a href="#polyfills-needed-to-support-older-browsers">Polyfills Needed to Support Older Browsers</a></h3>
|
||
<p>These six functions can be polyfilled using <code>es5-shim.js</code> from <a href="https://github.com/kriskowal/es5-shim">kriskowal's es5-shim</a>:</p>
|
||
|
||
<ul>
|
||
<li><code>Array.isArray</code></li>
|
||
<li><code>Array.prototype.forEach</code></li>
|
||
<li><code>Array.prototype.indexOf</code></li>
|
||
<li><code>Array.prototype.some</code></li>
|
||
<li><code>Date.now</code></li>
|
||
<li><code>Function.prototype.bind</code></li>
|
||
</ul>
|
||
|
||
<p>Other required polyfills:</p>
|
||
|
||
<ul>
|
||
<li><code>Object.create</code> – Provided by <code>es5-sham.js</code> from <a href="https://github.com/kriskowal/es5-shim">kriskowal's es5-shim</a>.</li>
|
||
<li><code>console.*</code> – Only needed when using the unminified build. If you need to polyfill this, try <a href="https://github.com/paulmillr/console-polyfill">paulmillr's console-polyfill</a>.</li>
|
||
</ul>
|
||
|
||
|
||
<div class="docs-prevnext">
|
||
|
||
<a class="docs-prev" href="/react/docs/forms.html">← Prev</a>
|
||
|
||
|
||
<a class="docs-next" href="/react/docs/more-about-refs.html">Next →</a>
|
||
|
||
</div>
|
||
|
||
<div class="fb-comments" data-width="650" data-num-posts="10" data-href="http://facebook.github.io/react/docs/working-with-the-browser.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>
|