本文基本跟着官方文档把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,共勉~