ReactJS入门（三）—— 顶层API
本文基本跟着官方文档把API都走一遍，但会有实例来解释应该怎么用，木有比我更详细的API文档咯。
React.createClass
参数：CONFIG（object）
创建一个ReactClass（组件类），参数是一个对象且必须带有 render 属性方法，该方法必须返回一个封闭的容器（容器内可以有其它不限结构的容器）或 null/false（表示啥都不渲染）：
var Component = React.createClass({ render: function() { return this.props.a==1 ? <div><h1>标题</h1><p>123</p></div> : null } }); React.render( <Component a="1" />, document.body );
注意！在该方法里面，所有的 this 都会在最终调用时自动地晚绑定到当前组件的构造器上（在本文最后有个有趣的小例子说明）。
React.createElement
参数：TYPE（string/ReactClass），[PROPS（object）]，[CHILDREN（ReactElement）]
创建一个指定类型的React元素，注意第三个参数CHILDREN可以是任意个React元素：
var Component = React.createClass({ render: function() { return this.props.a==1 ? <p>123</p> : null } }); React.render( React.createElement('div', null, React.createElement( 'p', null, React.createElement('span', null, 'Hello,'), React.createElement('span', null, 'world,'), React.createElement( Component, {a : 1}) ) ), document.body );
其实 React.createElement 是一个语法糖：
var reactElement = React.createElement(type, props, children); //等价于下面两行： var div = React.createFactory('div'); var reactDivElement = div(props, children);
React.cloneElement
参数：TYPE（ReactElement），[PROPS（object）]，[CHILDREN（ReactElement）]
克隆并返回一个新的 ReactElement （内部子元素也会跟着克隆），新返回的元素会保留有旧元素的 props、ref、key，也会集成新的 props（只要在第二个参数中有定义）。
var Hello = React.createClass({ render: function() { var span = <span a="1">VaJoy</span>; var newSpan = React.cloneElement(span, {b:'2'}, <em>CNBlog</em>); console.log(newSpan.props); return <div>Hello {span},{newSpan}</div>; //Hello VaJoy,CNBlog } }); React.render(<Hello />, document.body);
要注意的是，createElement 的第一个参数必须是字符串或 ReactClass，而在 cloneElement 里第一个参数应该是 ReactElement：
var Li = React.createClass({ render: function() { return <li>{this.props.i}</li> } }); var Ul = React.createClass({ deal : function(child, index){ //注意下面这行换成 createElement 会报错！因为child是ReactElement而不是ReactClass或字符串 return React.cloneElement(child, {i:index}); }, render: function() { return <ul>{this.props.children.map(this.deal)}</ul>; } }); React.render(( <Ul> <Li i="9" /> <Li i="8" /> <Li i="7" /> </Ul> ), document.body);
React.createFactory
参数：TYPE（string/ReactElement）
返回一个某种类型的ReactElement工厂函数，可以利用返回的函数来创建一个ReactElement（配置 props 和 children）：
var Component = React.createClass({ render: function() { return this.props.a==1 ? <p>123</p> : null } }); var p = React.createFactory(Component), ReactElementP = p({a:1}), div = React.createFactory('div'), ReactElementDiv = div(null, ReactElementP); React.render( ReactElementDiv, document.body );
React.render
参数：REACTELEMENT（ReactElement），CONTAINER（DOMElement），[CALLBACK（function）]
渲染一个 ReactElement 到 container 指定的 DOM 中，并返回一个到该组件的引用。如果提供了可选的回调函数，则该函数将会在组件渲染或者更新之后调用:
var Component = React.createClass({ render: function() { return this.props.a==1 ? <p>123</p> : null } }); var p = React.render( <Component a="1" />, document.body, function(){ console.log('OK') } ); setTimeout(function(){ console.log(p.props.a); //打印出“1” }, 2000)
因此如果我们希望在组件外部获取到组件内部（能通过 this 访问）的东西，可以将 React.render 的返回值赋予一个变量，在后续调用该变量即可。
React.unmountComponentAtNode
参数：CONTAINER（DOMElement）
从 container 指定的 DOM 中移除已经挂载的 React 组件，清除相应的事件处理器和 state。如果在 container 内没有组件挂载，这个函数将什么都不做。如果组件成功移除，则返回 true；如果没有组件被移除，则返回 false：
var Component = React.createClass({ render: function() { return this.props.a==1 ? <p>123</p> : null } }); React.render( <Component a="1" />, document.body ); setTimeout(function(){ var isUnmount = React.unmountComponentAtNode(document.body); console.log(isUnmount); //打印出true }, 2000)
React.renderToString
参数：REACTELEMENT（ReactElement）
React为服务端提供的一个方法，可以直接输出 ReactElement 为 HTML 字符串，将这些标记发送（比如 res.write(HTMLString)）给客户端，可以获得更快的页面加载速度，并且有利于搜索引擎抓取页面，方便做 SEO（主要是百度不争气，谷歌早可以从内存中去抓最终生成的HTML内容了）：
var Component = React.createClass({ render: function() { return this.props.a==1 ? <p>123</p> : null } }); var com = <Component a="1" />, comHTML = React.renderToString(com); console.log(comHTML); //输出“<p data-reactid=".0" data-react-checksum="-2122315716">123</p>”
React.renderToStaticMarkup
参数：REACTELEMENT（ReactElement）
类似 React.renderToString ，但只生成纯粹的HTML标记字符串，不会包含类似 data-reactid 之类的React属性，从而节省字节数：
var Component = React.createClass({ render: function() { return this.props.a==1 ? <p>123</p> : null } }); var com = <Component a="1" />, comHTML = React.renderToStaticMarkup(com); console.log(comHTML); //输出“<p>123</p>”
React.isValidElement
参数：SOMETHING
判断参数是否一个合法的 ReactElement，并返回 Boolean 值：
var Component = React.createClass({ render: function() { return this.props.a==1 ? <p>123</p> : null } }); var com = <Component/>, com2 = '<Component/>'; console.log(React.isValidElement(com)); //true console.log(React.isValidElement(com2)); //false
React.DOM.tag
参数：ATTRIBUTE（object/null），CHILDREN（string/ReactElement）
常规是用于在非 JSX 下来创建 ReactElement，tag 表示相应的DOM类型（比如“div”、“p”）。另外首个参数可以定制相关的 DOM 属性（比如“name”），第二个参数表示 DOM 内的内容：
var div = React.DOM.div({name : 'div1'}, 'HELLO ', React.DOM.span(null, <em>WORLD</em>)); React.render( div, document.body )
生成结果：
<div name="div1" data-reactid=".0"> <span data-reactid=".0.0">HELLO</span> <span data-reactid=".0.1"> <em data-reactid=".0.1.0">WORLD</em> </span> </div>
React.PropTypes
用于组件内部验证传入 Props 的类型，如果传入的类型不匹配，React 会打印出警告：
var Component = React.createClass({ propTypes : { a : React.PropTypes.number.isRequired, //必须传入一个名为“a”、类型为number的props callback : React.PropTypes.func //如果传入了名为“callback”的props，其类型必须是函数 }, render : function() { return this.props.a==1 ? <p onClick={this.props.callback}>123</p> : null } }); var cb = function(){ alert('click!') }; React.render( <Component a="1" callback={cb} />, document.body )
上方代码中，我们虽然给组件传入了名为“a”的 props，但其类型为字符串，不是我们期望的 number 类型，故 React 会报警告：
更多的 Props 期望类型可见官方例子：
React.createClass({
propTypes: {
// 可以声明 prop 为指定的 JS 基本类型。默认
// 情况下，这些 prop 都是可传可不传的。
optionalArray: React.PropTypes.array,
optionalBool: React.PropTypes.bool,
optionalFunc: React.PropTypes.func,
optionalNumber: React.PropTypes.number,
optionalObject: React.PropTypes.object,
optionalString: React.PropTypes.string,
// 所有可以被渲染的对象：数字，
// 字符串，DOM 元素或包含这些类型的数组。
optionalNode: React.PropTypes.node,
// React 元素
optionalElement: React.PropTypes.element,
// 用 JS 的 instanceof 操作符声明 prop 为类的实例。
optionalMessage: React.PropTypes.instanceOf(Message),
// 用 enum 来限制 prop 只接受指定的值。
optionalEnum: React.PropTypes.oneOf(['News', 'Photos']),
// 指定的多个对象类型中的一个
optionalUnion: React.PropTypes.oneOfType([
React.PropTypes.string,
React.PropTypes.number,
React.PropTypes.instanceOf(Message)
]),
// 指定类型组成的数组
optionalArrayOf: React.PropTypes.arrayOf(React.PropTypes.number),
// 指定类型的属性构成的对象
optionalObjectOf: React.PropTypes.objectOf(React.PropTypes.number),
// 指定Object对象内各属性的类型
optionalObjectWithShape: React.PropTypes.shape({
color: React.PropTypes.string,
fontSize: React.PropTypes.number
}),
// 加上 `isRequired` 来要求该 prop 不可为空
requiredFunc: React.PropTypes.func.isRequired,
// 不可为空的任意类型
requiredAny: React.PropTypes.any.isRequired,
// 自定义验证器。如果验证失败需要返回一个 Error 对象。不要直接
// 使用 `console.warn` 或抛异常，因为这样 `oneOfType` 会失效。
customProp: function(props, propName, componentName) {
if (!/matchme/.test(props[propName])) {
return new Error('Validation failed!');
}
}
},
/* ... */
});
React.initializeTouchEvents
参数：SholdUserTouch（boolean）
开启或关闭 React 的触摸事件机制，传入参数 true 使 React 能处理移动设备的触摸（ touch ）事件：
React.initializeTouchEvents(true); var Component = React.createClass({ render : function() { return <p onTouchStart={this.props.callback}>123</p> } }); var cb = function(){ alert('touch!') }; React.render( <Component callback={cb} />, document.body )
React.Children
为处理 this.props.children 这个封闭的数据结构提供了有用的工具。它有如下几个方法：
1. React.Children.map(object children, function fn [, object context])
遍历子元素，映射为一个新的子元素集合（跟 ES5 的 Array.map 差不多）：
var Component = React.createClass({ deal : function(child, index){ console.log(child, index); return !!index && child; //第一个li会被过滤掉，因为其索引为0 }, render : function() { return ( <ul> {React.Children.map(this.props.children, this.deal)} </ul>) } }); React.render( ( <Component> <li>0</li> <li>1</li> <li>2</li> </Component> ), document.body )
2. React.Children.forEach(object children, function fn [, object context])
遍历子元素，对每一个子元素执行回调，但不像上述的 map 那样最终返回一个新的集合（跟 ES5 的 Array.forEach 差不多）：
var Hello = React.createClass({ render: function() { React.Children.forEach(this.props.children, function(child){ console.log(child.props, child.key) }); return <div>Hello {this.props.name}</div>; } }); React.render(<Hello name="World"> <li myProp="test"/> <li key="blah2" myProp="test2"/> <li key="blah3"/> </Hello>, document.body);
3. React.Children.count(object children)
返回子元素的总数：
var Component = React.createClass({ render : function() { var nums = React.Children.count(this.props.children); return (<ul> <li>一共有{nums}个子元素</li> //3 {this.props.children} </ul>) } }); React.render( ( <Component> <li>0</li> <li>1</li> <li>2</li> </Component> ), document.body )
4. React.Children.only(object children)
返回仅有的一个子元素，否则（没有子元素或超过一个子元素）报错且不渲染任何东西：
var Hello = React.createClass({ render: function() { return <div>Hello {React.Children.only(this.props.children)}</div>; } }); React.render(<Hello name="World"> <span>World</span> <span>!</span> //会报错“onlyChild must be passed a children with exactly one child.” </Hello>, document.body);
话说这块其实我有些疑虑，明明可以直接使用数组的原生方法，比如 this.props.children.map/forEach ，也可以直接用 this.props.children.length 来获取总数，React 封装自己的遍历方法难道是为了polyfill IE8？
在最后说个有趣的小例子。我们知道 React.Children.map 和 React.Children.forEach 是有第三个参数（可选，用于修改上下文this）的，但我们试着执行下方的例子发现它并没按照我们的预期生效：
var obj = { num : 3 }; var Component = React.createClass({ deal : function(){ console.log(this); //it`s NOT obj }, render : function() { React.Children.forEach(this.props.children, this.deal, obj); return (<ul> {this.props.children} </ul>) } }); React.render( ( <Component> <li>0</li> <li>1</li> <li>2</li> </Component> ), document.body );
打印出来的是 Component 的构造器。ok，软的不行玩硬的，我们试着加俩个 bind(obj)，总不至于不行了吧：
var obj = { num : 3 }; var Component = React.createClass({ deal : function(){ console.log(this); //it`s NOT obj }, render : function() { React.Children.forEach.bind(obj)(this.props.children, this.deal.bind(obj)); return (<ul> {this.props.children} </ul>) } }); React.render( ( <Component> <li>0</li> <li>1</li> <li>2</li> </Component> ), document.body );
结果真的是不行，改为 call 和 apply 也都扑街~ 卧槽我读书少别欺负我啊。
后来去提 issue 询问下才知道 React.creactClass 会在后续调用自身方法时将 this 自动绑定到当前组件上，自然我们获取到的 this 总会是组件的构造器了。
因此 React.Children.map 和 React.Children.forEach 的第三个参数只要不用于 React.creactClass 的内部属性方法，都会跑的好好滴：
var Component = React.createClass({ render : function() { React.Children.forEach(this.props.children, function(){ //独立的回调 console.log(this); //obj无误！ }, obj); return (<ul> {this.props.children} </ul>) } });
顶层API先总结到这边，下篇文章总结下同样很重要的组件API，共勉~
