Pete Hunt
12 years ago
16 changed files with 690 additions and 218 deletions
@ -0,0 +1,22 @@ |
|||
--- |
|||
id: examples |
|||
title: Examples |
|||
layout: docs |
|||
permalink: examples.html |
|||
prev: tooling-integration.html |
|||
--- |
|||
|
|||
### Production Apps |
|||
|
|||
* All of [Instagram.com](http://instagram.com/) is built on React. |
|||
* Many components on [Facebook.com](http://www.facebook.com/), including the commenting interface, ads creation flows, and page insights. |
|||
* [Khan Academy](http://khanacademy.org/) is using React for its question editor. |
|||
|
|||
|
|||
### Sample Code |
|||
|
|||
* We've included [a step-by-step comment box tutorial](./tutorial.html). |
|||
* [The React starter kit](/react/downloads.html) includes several examples which you can [view online in our GitHub repository](https://github.com/facebook/react/tree/master/examples/). |
|||
* [React Page](https://github.com/facebook/react-page) is a simple React project creator to get you up-and-running quickly with React. It supports both server-side and client-side rendering, source transform and packaging JSX files using CommonJS modules, and instant reload. |
|||
* [React one-hour email](https://github.com/petehunt/react-one-hour-email/commits/master) goes step-by-step from a static HTML mock to an interactive email reader (written in just one hour!) |
|||
* [Rendr + React app template](https://github.com/petehunt/rendr-react-template/) demonstrates how to use React's server rendering capabilities. |
|||
@ -1,209 +0,0 @@ |
|||
--- |
|||
id: reference |
|||
title: Reference |
|||
layout: docs |
|||
permalink: reference.html |
|||
prev: tooling-integration.html |
|||
--- |
|||
|
|||
## Examples |
|||
|
|||
|
|||
### Production Apps |
|||
|
|||
* All of [Instagram.com](http://instagram.com/) is built on React. |
|||
* Many components on [Facebook.com](http://www.facebook.com/), including the commenting interface, ads creation flows, and page insights. |
|||
* [Khan Academy](http://khanacademy.org/) is using React for its question editor. |
|||
|
|||
|
|||
### Sample Code |
|||
|
|||
* We've included [a step-by-step comment box tutorial](./tutorial.html). |
|||
* [The React starter kit](/react/downloads.html) includes several examples which you can [view online in our GitHub repository](https://github.com/facebook/react/tree/master/examples/). |
|||
* [reactapp](https://github.com/jordwalke/reactapp) is a simple app template to get you up-and-running quickly with React. |
|||
* [React one-hour email](https://github.com/petehunt/react-one-hour-email/commits/master) goes step-by-step from a static HTML mock to an interactive email reader (written in just one hour!) |
|||
* [Rendr + React app template](https://github.com/petehunt/rendr-react-template/) demonstrates how to use React's server rendering capabilities. |
|||
|
|||
|
|||
## API |
|||
|
|||
### React |
|||
|
|||
`React` 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 `require()` it. |
|||
|
|||
|
|||
#### React.DOM |
|||
|
|||
`React.DOM` 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 `/** @jsx React.DOM */` docblock. |
|||
|
|||
|
|||
#### React.initializeTouchEvents |
|||
|
|||
```javascript |
|||
initializeTouchEvents(boolean shouldUseTouch) |
|||
``` |
|||
|
|||
Configure React's event system to handle touch events on mobile devices. |
|||
|
|||
|
|||
#### React.createClass |
|||
|
|||
```javascript |
|||
function createClass(object specification) |
|||
``` |
|||
|
|||
Creates a component given a specification. A component implements a `render` method which returns **one single** child. That child may have an arbitrarily deep child structure. One thing that makes components different than 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. |
|||
|
|||
|
|||
#### React.renderComponent |
|||
|
|||
```javascript |
|||
ReactComponent renderComponent(ReactComponent container, DOMElement container) |
|||
``` |
|||
|
|||
Renders a React component into the DOM in the supplied `container`. |
|||
|
|||
If the React component was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component. |
|||
|
|||
|
|||
#### React.unmountAndReleaseReactRootNode |
|||
|
|||
```javascript |
|||
unmountAndReleaseReactRootNode(DOMElement container) |
|||
``` |
|||
|
|||
Remove a mounted React component from the DOM and clean up its event handlers and state. |
|||
|
|||
|
|||
#### React.renderComponentToString |
|||
|
|||
```javascript |
|||
renderComponentToString(ReactComponent component, function callback) |
|||
``` |
|||
|
|||
Render a component to its initial HTML. This should only be used on the server. React will call `callback` 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 `React.renderComponent()` 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. |
|||
|
|||
|
|||
### AbstractEvent |
|||
|
|||
Your event handlers will be passed instances of `AbstractEvent`, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event (such as `stopPropagation()` and `preventDefault()`) except they work exactly the same across all browsers. |
|||
|
|||
If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it. |
|||
|
|||
|
|||
### ReactComponent |
|||
|
|||
Component classses created by `createClass()` return instances of `ReactComponent` when called. Most of the time when you're using React you're either creating or consuming `ReactComponent`s. |
|||
|
|||
|
|||
#### getDOMNode |
|||
|
|||
```javascript |
|||
DOMElement getDOMNode() |
|||
``` |
|||
|
|||
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. |
|||
|
|||
|
|||
#### setProps |
|||
|
|||
```javascript |
|||
setProps(object nextProps) |
|||
``` |
|||
|
|||
When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `renderComponent()`. Simply call `setProps()` to change its properties and trigger a re-render. |
|||
|
|||
> Note: |
|||
> |
|||
> This method can only be called on a root-level component. That is, it's only available on the component passed directly to `renderComponent()` and none of its children. If you're inclined to use `setProps()` on a child component, instead take advantage of reactive updates and pass the new prop to the child component when it's created in `render()`. |
|||
|
|||
|
|||
#### replaceProps |
|||
|
|||
```javascript |
|||
replaceProps(object nextProps) |
|||
``` |
|||
|
|||
Like `setProps()` but deletes any pre-existing props that are not in nextProps. |
|||
|
|||
|
|||
#### transferPropsTo |
|||
|
|||
```javascript |
|||
ReactComponent transferPropsTo(ReactComponent targetComponent) |
|||
``` |
|||
|
|||
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. `targetComponent`, now updated with some new props is returned as a convenience. |
|||
|
|||
|
|||
#### setState |
|||
|
|||
```javascript |
|||
setState(object nextState[, function callback]) |
|||
``` |
|||
|
|||
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 `setState` is completed. |
|||
|
|||
> Note: |
|||
> |
|||
> *NEVER* mutate `this.state` directly. As calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable. |
|||
|
|||
> Note: |
|||
> |
|||
> `setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value. |
|||
|
|||
> Note: |
|||
> |
|||
> There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains. |
|||
|
|||
|
|||
#### replaceState |
|||
|
|||
```javascript |
|||
replaceState(object nextState[, function callback]) |
|||
``` |
|||
|
|||
Like `setState()` but deletes any pre-existing state keys that are not in nextState. |
|||
|
|||
|
|||
#### forceUpdate() |
|||
|
|||
```javascript |
|||
forceUpdate([function callback]) |
|||
``` |
|||
|
|||
If your `render()` method reads from something other than `this.props` or `this.state` you'll need to tell React when it needs to re-run `render()`. Use `forceUpdate()` to cause React to automatically re-render. This will cause `render()` to be called on the component and all of its children but React will only update the DOM if the markup changes. |
|||
|
|||
Normally you should try to avoid all uses of `forceUpdate()` and only read from `this.props` and `this.state` in `render()`. This makes your application much simpler and more efficient. |
|||
|
|||
> Note: |
|||
> |
|||
> There is no guarantee of synchronous operation of calls to `forceUpdate` and calls may be batched for performance gains. |
|||
|
|||
|
|||
#### Lifecycle methods |
|||
|
|||
```javascript |
|||
object getInitialState() |
|||
componentWillMount() |
|||
componentDidMount(DOMElement domNode) |
|||
componentWillReceiveProps(object nextProps) |
|||
boolean shouldComponentUpdate(object nextProps, object nextState) |
|||
componentWillUpdate(object nextProps, object nextState) |
|||
ReactComponent render() |
|||
componentDidUpdate(object prevProps, object prevState, DOMElement domNode) |
|||
componentWillUnmount() |
|||
``` |
|||
|
|||
See the [working with the browser](./working-with-the-browser.html) documentation for more details on these lifecycle methods. |
|||
|
|||
|
|||
## DOM Differences |
|||
|
|||
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. |
|||
|
|||
* All events (including submit) bubble correctly per the W3C spec |
|||
* All event objects conform to the W3C spec |
|||
* 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. |
|||
* The `style` attribute accepts a JavaScript object with camelCased properties rather than a CSS string. This is consistent with the DOM `style` JavaScript property, is more efficient, and prevents XSS security holes. |
|||
* `onChange` 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 `onChange` is a misnomer for its behavior and React relies on this event to react to user input in real time. |
|||
@ -0,0 +1,73 @@ |
|||
--- |
|||
id: top-level-api |
|||
title: Top-Level API |
|||
layout: docs |
|||
permalink: top-level-api.html |
|||
next: component-api.html |
|||
--- |
|||
|
|||
## React |
|||
|
|||
`React` 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 `require()` it. |
|||
|
|||
|
|||
### React.DOM |
|||
|
|||
`React.DOM` 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 `/** @jsx React.DOM */` docblock. |
|||
|
|||
|
|||
### React.initializeTouchEvents |
|||
|
|||
```javascript |
|||
initializeTouchEvents(boolean shouldUseTouch) |
|||
``` |
|||
|
|||
Configure React's event system to handle touch events on mobile devices. |
|||
|
|||
|
|||
### React.createClass |
|||
|
|||
```javascript |
|||
function createClass(object specification) |
|||
``` |
|||
|
|||
Creates a component given a specification. A component implements a `render` method which returns **one single** child. That child may have an arbitrarily deep child structure. One thing that makes components different than 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. |
|||
|
|||
For more information about the specification object, see [Component Specs and Lifecycle](component-specs.html). |
|||
|
|||
|
|||
### React.renderComponent |
|||
|
|||
```javascript |
|||
ReactComponent renderComponent( |
|||
ReactComponent component, |
|||
DOMElement container, |
|||
[function callback] |
|||
) |
|||
``` |
|||
|
|||
Renders a React component into the DOM in the supplied `container`. |
|||
|
|||
If the React component was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component. |
|||
|
|||
If the optional callback is provided, it will be executed after the component is rendered or updated. |
|||
|
|||
|
|||
### React.unmountAndReleaseReactRootNode |
|||
|
|||
```javascript |
|||
unmountAndReleaseReactRootNode(DOMElement container) |
|||
``` |
|||
|
|||
Remove a mounted React component from the DOM and clean up its event handlers and state. |
|||
|
|||
|
|||
### React.renderComponentToString |
|||
|
|||
```javascript |
|||
renderComponentToString(ReactComponent component, function callback) |
|||
``` |
|||
|
|||
Render a component to its initial HTML. This should only be used on the server. React will call `callback` with an HTML string when the markup is ready. You can use this method to can generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes. |
|||
|
|||
If you call `React.renderComponent()` 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. |
|||
@ -0,0 +1,109 @@ |
|||
--- |
|||
id: component-api |
|||
title: Component API |
|||
layout: docs |
|||
permalink: component-api.html |
|||
prev: top-level-api.html |
|||
next: component-specs.html |
|||
--- |
|||
|
|||
## ReactComponent |
|||
|
|||
Component classses created by `createClass()` return instances of `ReactComponent` when called. Most of the time when you're using React you're either creating or consuming these component objects. |
|||
|
|||
|
|||
### getDOMNode |
|||
|
|||
```javascript |
|||
DOMElement getDOMNode() |
|||
``` |
|||
|
|||
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. |
|||
|
|||
|
|||
### setProps |
|||
|
|||
```javascript |
|||
setProps(object nextProps) |
|||
``` |
|||
|
|||
When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `renderComponent()`. Simply call `setProps()` to change its properties and trigger a re-render. |
|||
|
|||
> Note: |
|||
> |
|||
> This method can only be called on a root-level component. That is, it's only available on the component passed directly to `renderComponent()` and none of its children. If you're inclined to use `setProps()` on a child component, instead take advantage of reactive updates and pass the new prop to the child component when it's created in `render()`. |
|||
|
|||
|
|||
### replaceProps |
|||
|
|||
```javascript |
|||
replaceProps(object nextProps) |
|||
``` |
|||
|
|||
Like `setProps()` but deletes any pre-existing props instead of merging the two objects. |
|||
|
|||
|
|||
### transferPropsTo |
|||
|
|||
```javascript |
|||
ReactComponent transferPropsTo(ReactComponent targetComponent) |
|||
``` |
|||
|
|||
Transfer properties from this component to a target component that have not already been set on the target component. After the props are updated, `targetComponent` is returned as a convenience. This function is useful when creating simple HTML-like components: |
|||
|
|||
```javascript |
|||
var Avatar = React.createClass({ |
|||
render: function() { |
|||
return this.transferPropsTo( |
|||
<img src={"/avatars/" + this.props.userId + ".png"} userId={null} /> |
|||
); |
|||
} |
|||
}); |
|||
|
|||
// <AvatarImage userId={17} width={200} height={200} /> |
|||
``` |
|||
|
|||
Properties that are specified directly on the target component instance (such as `src` and `userId` in the above example) will not be overwritten by `transferPropsTo`. |
|||
|
|||
> Note: |
|||
> |
|||
> Use `transferPropsTo` with caution; it encourages tight coupling and makes it easy to accidentally introduce implicit dependencies between components. When in doubt, it's safer to explicitly copy the properties that you need onto the child component. |
|||
|
|||
|
|||
### setState |
|||
|
|||
```javascript |
|||
setState(object nextState[, function callback]) |
|||
``` |
|||
|
|||
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 `setState` is completed. |
|||
|
|||
> Notes: |
|||
> |
|||
> *NEVER* mutate `this.state` directly, as calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable. |
|||
> |
|||
> `setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value. |
|||
> |
|||
> There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains. |
|||
|
|||
|
|||
### replaceState |
|||
|
|||
```javascript |
|||
replaceState(object nextState[, function callback]) |
|||
``` |
|||
|
|||
Like `setState()` but deletes any pre-existing state keys that are not in nextState. |
|||
|
|||
|
|||
### forceUpdate() |
|||
|
|||
```javascript |
|||
forceUpdate([function callback]) |
|||
``` |
|||
|
|||
If your `render()` method reads from something other than `this.props` or `this.state`, you'll need to tell React when it needs to re-run `render()` by calling `forceUpdate()`. You'll also need to call `forceUpdate()` if you mutate `this.state` directly. |
|||
|
|||
Calling `forceUpdate()` will cause `render()` to be called on the component and its children, but React will still only update the DOM if the markup changes. |
|||
|
|||
Normally you should try to avoid all uses of `forceUpdate()` and only read from `this.props` and `this.state` in `render()`. This makes your application much simpler and more efficient. |
|||
@ -0,0 +1,176 @@ |
|||
--- |
|||
id: component-specs |
|||
title: Component Specs and Lifecycle |
|||
layout: docs |
|||
permalink: component-specs.html |
|||
prev: component-api.html |
|||
next: tags-and-attributes.html |
|||
--- |
|||
|
|||
## Component Specifications |
|||
|
|||
When creating a component class by invoking `React.createClass()`, you should provide a specification object that contains a `render` method and can optionally contain other lifecycle methods described here. |
|||
|
|||
|
|||
### render |
|||
|
|||
```javascript |
|||
ReactComponent render() |
|||
``` |
|||
|
|||
The `render()` method is required. |
|||
|
|||
When called, it should examine `this.props` and `this.state` and return a single child component. This child component can be either a native DOM component (such as `<div>`) or another composite component that you've defined yourself. |
|||
|
|||
The `render()` function should be *pure*, 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 `setTimeout`). If you need to interact with the browser, perform your work in `componentDidMount()` or the other lifecycle methods instead. Keeping `render()` pure makes server rendering more practical and makes components easier to think about. |
|||
|
|||
|
|||
### getInitialState |
|||
|
|||
```javascript |
|||
object getInitialState() |
|||
``` |
|||
|
|||
Invoked once when the component is mounted. The return value will be used as the initial value of `this.state`. |
|||
|
|||
|
|||
### getDefaultProps |
|||
|
|||
```javascript |
|||
object getDefaultProps() |
|||
``` |
|||
|
|||
Invoked once when the component is mounted. Values in the mapping will be set on `this.props` if that prop is not specified by the parent component (i.e. using an `in` check). |
|||
|
|||
This method is invoked before `getInitialState` and therefore cannot rely on `this.state` or use `this.setState`. |
|||
|
|||
|
|||
### propTypes |
|||
|
|||
```javascript |
|||
object propTypes |
|||
``` |
|||
|
|||
The `propTypes` object allows you to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](reusable-components.html). |
|||
|
|||
<!-- TODO: Document propTypes here directly. --> |
|||
|
|||
|
|||
### mixins |
|||
|
|||
```javascript |
|||
array mixins |
|||
``` |
|||
|
|||
The `mixins` array allows you to use mixins to share behavior among multiple components. For more information about mixins, see [Reusable Components](reusable-components.html). |
|||
|
|||
<!-- TODO: Document mixins here directly. --> |
|||
|
|||
|
|||
## Lifecycle Methods |
|||
|
|||
Various methods are executed at specific points in a component's lifecycle. |
|||
|
|||
|
|||
### Mounting: componentWillMount |
|||
|
|||
```javascript |
|||
componentWillMount() |
|||
``` |
|||
|
|||
Invoked immediately before rendering occurs. If you call `setState` within this method, `render()` will see the updated state and will be executed only once despite the state change. |
|||
|
|||
|
|||
### Mounting: componentDidMount |
|||
|
|||
```javascript |
|||
componentDidMount(DOMElement rootNode) |
|||
``` |
|||
|
|||
Invoked immediately after rendering occurs. At this point in the lifecycle, the component has a DOM representation which you can access via the `rootNode` argument or by calling `this.getDOMNode()`. |
|||
|
|||
If you want to integrate with other JavaScript frameworks, set timers using `setTimeout` or `setInterval`, or send AJAX requests, perform those operations in this method. |
|||
|
|||
|
|||
### Updating: componentWillReceiveProps |
|||
|
|||
```javascript |
|||
componentWillReceiveProps(object nextProps) |
|||
``` |
|||
|
|||
Invoked when a component is receiving new props. This method is not called for the initial render. |
|||
|
|||
Use this as an opportunity to react to a prop transition before `render()` is called by updating the state using `this.setState()`. The old props can be accessed via `this.props`. Calling `this.setState()` within this function will not trigger an additional render. |
|||
|
|||
```javascript |
|||
componentWillReceiveProps: function(nextProps) { |
|||
this.setState({ |
|||
likesIncreasing: nextProps.likeCount > this.props.likeCount |
|||
}); |
|||
} |
|||
``` |
|||
|
|||
> Note: |
|||
> |
|||
> There is no analogous method `componentWillReceiveState`. 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 `componentWillUpdate`. |
|||
|
|||
|
|||
### Updating: shouldComponentUpdate |
|||
|
|||
```javascript |
|||
boolean shouldComponentUpdate(object nextProps, object nextState) |
|||
``` |
|||
|
|||
Invoked before rendering when new props or state are being received. This method is not called for the initial render or when `forceUpdate` is used. |
|||
|
|||
Use this as an opportunity to `return false` when you're certain that the |
|||
transition to the new props and state will not require a component update. |
|||
|
|||
```javascript |
|||
shouldComponentUpdate: function(nextProps, nextState) { |
|||
return !equal(nextProps, this.props) || !equal(nextState, this.state); |
|||
} |
|||
``` |
|||
|
|||
If `shouldComponentUpdate` returns false, then `render()` will be completely skipped until the next state change. (In addition, `componentWillUpdate` and `componentDidUpdate` will not be called.) |
|||
|
|||
By default, `shouldComponentUpdate` always returns true to prevent subtle bugs when `state` is mutated in place, but if you are careful to always treat `state` as immutable and to read only from `props` and `state` in `render()` then you can override `shouldComponentUpdate` with an implementation that compares the old props and state to their replacements. |
|||
|
|||
If performance is a bottleneck, especially with dozens or hundreds of components, use `shouldComponentUpdate` to speed up your app. |
|||
|
|||
|
|||
### Updating: componentWillUpdate |
|||
|
|||
```javascript |
|||
componentWillUpdate(object nextProps, object nextState) |
|||
``` |
|||
|
|||
Invoked immediately before rendering when new props or state are being received. This method is not called for the initial render. |
|||
|
|||
Use this as an opportunity to perform preparation before an update occurs. |
|||
|
|||
> Note: |
|||
> |
|||
> You *cannot* use `this.setState()` in this method. If you need to update state in response to a prop change, use `componentWillReceiveProps` instead. |
|||
|
|||
|
|||
### Updating: componentDidUpdate |
|||
|
|||
```javascript |
|||
componentDidUpdate(object prevProps, object prevState, DOMElement rootNode) |
|||
``` |
|||
|
|||
Invoked immediately after updating occurs. This method is not called for the initial render. |
|||
|
|||
Use this as an opportunity to operate on the DOM when the component has been updated. |
|||
|
|||
|
|||
### Unmounting: componentWillUnmount |
|||
|
|||
```javascript |
|||
componentWillUnmount() |
|||
``` |
|||
|
|||
Invoked immediately before a component is unmounted from the DOM. |
|||
|
|||
Perform any necessary cleanup in this method, such as invalidating timers or cleaning up any DOM elements that were created in `componentDidMount`. |
|||
@ -0,0 +1,65 @@ |
|||
--- |
|||
id: tags-and-attributes |
|||
title: Tags and Attributes |
|||
layout: docs |
|||
permalink: tags-and-attributes.html |
|||
prev: component-specs.html |
|||
next: events.html |
|||
--- |
|||
|
|||
## Supported Tags |
|||
|
|||
React attempts to support all common elements. If you need an element that isn't listed here, please file an issue. |
|||
|
|||
The following elements are supported: |
|||
|
|||
|
|||
### HTML Elements |
|||
|
|||
``` |
|||
a abbr address area article aside audio b base bdi bdo big blockquote body br |
|||
button canvas caption cite code col colgroup data datalist dd del details dfn |
|||
div dl dt em embed fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 |
|||
head header hr html i iframe img input ins kbd keygen label legend li link |
|||
main map mark menu menuitem meta meter nav noscript object ol optgroup option |
|||
output p param pre progress q rp rt ruby s samp script section select small |
|||
source span strong style sub summary sup table tbody td textarea tfoot th |
|||
thead time title tr track u ul var video wbr |
|||
``` |
|||
|
|||
### SVG elements |
|||
|
|||
``` |
|||
circle g line path polyline rect svg text |
|||
``` |
|||
|
|||
|
|||
## Supported Attributes |
|||
|
|||
React supports all `data-*` and `aria-*` attributes as well as every attribute |
|||
in the following lists. Note that all attributes are camel-cased and the attributes `class` and `for` are `className` and `htmlFor`, respectively, to match the DOM API specification. |
|||
|
|||
For a list of events, see [Supported Events](events.html). |
|||
|
|||
### HTML Attributes |
|||
|
|||
``` |
|||
accessKey accept action ajaxify allowFullScreen allowTransparency alt |
|||
autoComplete autoFocus autoPlay cellPadding cellSpacing charSet checked |
|||
className colSpan content contentEditable contextMenu controls data dateTime |
|||
dir disabled draggable encType form frameBorder height hidden href htmlFor |
|||
httpEquiv icon id label lang list max maxLength method min multiple name |
|||
pattern poster preload placeholder radioGroup rel readOnly required role |
|||
rowSpan scrollLeft scrollTop selected size spellCheck src step style tabIndex |
|||
target title type value width wmode |
|||
``` |
|||
|
|||
In addition, the non-standard `autoCapitalize` attribute is supported for Mobile Safari. |
|||
|
|||
### SVG Attributes |
|||
|
|||
``` |
|||
cx cy d fill fx fy points r stroke strokeLinecap strokeWidth transform x x1 x2 |
|||
version viewBox y y1 y2 spreadMethod offset stopColor stopOpacity |
|||
gradientUnits gradientTransform |
|||
``` |
|||
@ -0,0 +1,205 @@ |
|||
--- |
|||
id: events |
|||
title: Event System |
|||
layout: docs |
|||
permalink: events.html |
|||
prev: tags-and-attributes.html |
|||
next: dom-differences.html |
|||
--- |
|||
|
|||
## SyntheticEvent |
|||
|
|||
Your event handlers will be passed instances of `SyntheticEvent`, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event, including `stopPropagation()` and `preventDefault()`, except the events work identically across all browsers. |
|||
|
|||
If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it. Every `SyntheticEvent` object has the following attributes: |
|||
|
|||
```javascript |
|||
boolean bubbles |
|||
boolean cancelable |
|||
DOMEventTarget currentTarget |
|||
boolean defaultPrevented |
|||
Number eventPhase |
|||
boolean isTrusted |
|||
DOMEvent nativeEvent |
|||
void preventDefault() |
|||
void stopPropagation() |
|||
DOMEventTarget target |
|||
Date timeStamp |
|||
String type |
|||
``` |
|||
|
|||
|
|||
## Supported Events |
|||
|
|||
React normalizes events so that they have consistent properties across |
|||
different browsers. |
|||
|
|||
|
|||
### Clipboard Events |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onCopy onCut onPaste |
|||
``` |
|||
|
|||
Properties: |
|||
|
|||
```javascript |
|||
DOMDataTransfer clipboardData |
|||
``` |
|||
|
|||
|
|||
### Keyboard Events |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onKeyDown onKeyPress onKeyUp |
|||
``` |
|||
|
|||
Properties: |
|||
|
|||
```javascript |
|||
boolean altKey |
|||
String char |
|||
boolean ctrlKey |
|||
String key |
|||
String locale |
|||
Number location |
|||
boolean metaKey |
|||
boolean repeat |
|||
boolean shiftKey |
|||
``` |
|||
|
|||
|
|||
### Focus Events |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onFocus onBlur |
|||
``` |
|||
|
|||
Properties: |
|||
|
|||
```javascript |
|||
DOMEventTarget relatedTarget |
|||
``` |
|||
|
|||
|
|||
### Form Events |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onChange onInput onSubmit |
|||
``` |
|||
|
|||
For more information about the onChange event, see [Forms](forms.html). |
|||
|
|||
|
|||
### Mouse Events |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onClick onDoubleClick onDrag onDragEnd onDragEnter onDragExit onDragLeave |
|||
onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave |
|||
onMouseMove onMouseUp |
|||
``` |
|||
|
|||
Properties: |
|||
|
|||
```javascript |
|||
boolean altKey |
|||
Number button |
|||
Number buttons |
|||
Number clientX |
|||
Number clientY |
|||
boolean ctrlKey |
|||
boolean metaKey |
|||
Number pageX |
|||
Number pageY |
|||
DOMEventTarget relatedTarget |
|||
Number screenX |
|||
Number screenY |
|||
boolean shiftKey |
|||
``` |
|||
|
|||
|
|||
### Mutation Events |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onDOMCharacterDataModified |
|||
``` |
|||
|
|||
Properties: |
|||
|
|||
```javascript |
|||
Number attrChange |
|||
String attrName |
|||
String newValue |
|||
String prevValue |
|||
Node relatedNode |
|||
``` |
|||
|
|||
|
|||
### Touch events |
|||
|
|||
To enable touch events, call `React.initializeTouchEvents(true)` before |
|||
rendering any component. |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onTouchCancel onTouchEnd onTouchMove onTouchStart |
|||
``` |
|||
|
|||
Properties: |
|||
|
|||
```javascript |
|||
boolean altKey |
|||
DOMTouchList changedTouches |
|||
boolean ctrlKey |
|||
boolean metaKey |
|||
boolean shiftKey |
|||
DOMTouchList targetTouches |
|||
DOMTouchList touches |
|||
``` |
|||
|
|||
|
|||
### UI Events |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onScroll |
|||
``` |
|||
|
|||
Properties: |
|||
|
|||
```javascript |
|||
Number detail |
|||
DOMAbstractView view |
|||
``` |
|||
|
|||
|
|||
### Wheel Events |
|||
|
|||
Event names: |
|||
|
|||
``` |
|||
onWheel |
|||
``` |
|||
|
|||
Properties: |
|||
|
|||
```javascript |
|||
Number deltaX |
|||
Number deltaMode |
|||
Number deltaY |
|||
Number deltaZ |
|||
``` |
|||
@ -0,0 +1,14 @@ |
|||
--- |
|||
id: dom-differences |
|||
title: DOM Differences |
|||
layout: docs |
|||
permalink: dom-differences.html |
|||
prev: events.html |
|||
--- |
|||
|
|||
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. |
|||
|
|||
* 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. |
|||
* The `style` attribute accepts a JavaScript object with camelCased properties rather than a CSS string. This is consistent with the DOM `style` JavaScript property, is more efficient, and prevents XSS security holes. |
|||
* All event objects conform to the W3C spec, and all events (including submit) bubble correctly per the W3C spec. See [Event System](events.html) for more details. |
|||
* The `onChange` event 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 `onChange` is a misnomer for its behavior and React relies on this event to react to user input in real time. See [Forms](forms.html) for more details. |
|||
Loading…
Reference in new issue