pwfe-dom

pwfe-dom

palmg基础前端react组件基础工程。

---

pwfe—palmg web front end。

---

安装

npm install pwfe-dom

sass-node安装异常

当nodejs版本较低时，安装node-sass会出现异常，请使用cnpm执行：

$ npm rm node-sass
$ cnpm install node-sass

详情请查看：https://github.com/sass/node-sass/issues/468

规范

pwfe中的所有前后端组件统一使用标准的routes列表作为路由配置：

[{
    id: 'comp1', //页面id，在列表中唯一
    url: '/', //页面对应的URL
    name: '演示文稿', //页面名称，会渲染到title媒体属性中
    component: (call)=> { //加载组件的回调
        require.ensure([], require => {
            call(require('./sub/comp1'))
        }, 'comp1')
    }
}]

参数说明：

接口	说明
id	表示该页面的唯一标识，在内部用于匹配和实现前后端同步渲染。
url	页面对应的url。可以为/path/name或/path/name/:params的形式
name	页面显示在浏览器title的名称。
component	获取组件的回调方式。一般是(cb)=>{cb(Component)}的方式，无论通过什么方式获取React组件，最后使用cb(component)来返回。例如上面使用了require.ensure规范。

组件说明

bundle

页面分片高阶组件。该组件配合routes用于实现页面分片。

import bundle from 'pwfe-dom/bundle'
<div>bundle(initComp, getComp)</div>

参数说明

接口	类型	说明
initComp	Element	优先初始化的组件。当传入该参数时，表示不必使用第二个参数的get回调去获取参数。而直接使用这个组件。
getComp	function	异步获取参数的回调方法。该方法会在组件开始渲染时被调用。传入另外一个回调方法，实现异步加载。例如(cb)=>{cb(require('./page'))}，在获取组件后调用cb返回。

App

App是用于前后端同构的入口，app中会调用bundle进行分片渲染。如果在业务工程中有特别需要，可以以app组件以模板进行二次开发。

import React from 'react'
import {render} from 'react-dom';
import App from 'pwfe-dom/app'
render(
    (<App className={className} init={{comp:comp, id: initID}} routes={routes}>
        <Children />
    </App>),
    document.getElementById('root')
)

参数说明

接口	类型	说明
init	object	系统初始化渲染参数。对象中包含2个参数：comp和id。 comp：初始化渲染的页面组件，一般用于前后端同构渲染。这个组件会在第一次渲染之前就传入，放置前后端首屏异构。 id：初始渲染组件对应的路由表id。
routes	arrya	路由列表。结构请看规范中的routes说明。
className	string	app组件样式。所有App中的子元素都会被一个div标签包裹，传入className可以设定这个div对应的样式。
children	react Element	App的子元素。会在路由内容之前显示该内容。
header	react Element	App头部元素。例如可以设定Link元素。
header	react Element	App页脚元素。用于全站统一显示页脚信息。

entry

entry是提供前端入口的全局组件。与后端的serverApp组件对应。用于实现前端同构渲染功能。entry中使用默认的App和bundle实现了页面渲染和分片加载。如果有特殊的业务需求，可以使用自定义的App

import entry from 'pwfe-dom/entry'

entry({
    reducer: reducer,
    routes: routes,
    children: (<div>
        <Link to="/">comp1</Link>
        <Link to="/comp2">comp2</Link>
    </div>),
    className: cn('demo'),
    renderCb: ()=> {
        console.log('render success!')
    }
})

参数说明

接口	类型	说明
reducer	object	redux对应使用的reducer。结构为{key:function(){}}
routes	array	routes列表，详见前文的routes说明
app	Element	用于前后端同构渲染的组件。该App会被传入init参数和routes参数。不设置默认使用pwfe-dom/app组件
header	Element	在app中显示的头部元素，如果传入了自定义的app，则会传入到props.header中，组件会在children之前显示。
children	Element	在app中显示的子元素，如果使用了自定义App组件，则会传入到props.children中。
footer	Element	在app中显示的头部元素，如果传入了自定义的app，则会传入到props.footer中，组件会在routes之后显示。
className	string	app组件显示的样式，如果使用自定义的App组件，则会传入到props.className中。
renderCb	function	渲染成功的回调方法

tag

tag组件包含一系列对源生HTML标签进行扩展的组件：Img、Icon、DynaIcon、A。此外还提供了针对动态图片的设置功能——setIcon。

Img

Img用于替换源生的html<img/>标签。目前还未实现Img的特性。计划实现的特性包括：

1. 实现图片滚当到可视区域加载。
2. 实现图片低清图和高清图分步加载。
3. 实现图片质量控制，配合后台文件服务器控制图片的大小、分辨质量等。

import Tag from 'pwfe-dom/tag'
<Tag.Img src="myPic" className="myStyle"/>

接口	说明
all	Img组件支持所有<img/>源生属性和方法。

Icon

Icon用于展示所有站内图标，它的作用是将资源文件和代码部分隔离开，然后异步加载，不影响业务执行。

1. 标签组件需要绑定资源路径使用，每增加一个图片，都需要增加一个资源引用。资源文件通过Tab.Icon设置（后文有介绍）
2. src参数传递的是资源标记，例如资源项 img={logo:"base64:adf"},此时传入的src="logo"。

import Tag from 'pwfe-dom/tag'
<Tag.Icon src="myPicName" className="myStyle"/>

接口	说明
all	Icon组件支持所有<img/>源生属性和方法。
src	与标准<img/>不同是，这里的src传入的是一个资源文件名称。详见Tag.setIcon部分说明。

DynaIcon

支持激活特性的Icon组件。使用方式和Icon组件一样。

import Tag from 'pwfe-dom/tag'
<Tag.DynaIcon src="myPicName" actSrc="myActPicName" act/>

接口	类型	说明
all	object	组件支持所有<img/>源生属性和方法。
src	string	未激活时要显示的图标，src传入的是一个资源文件名称。详见Tag.setIcon部分说明。
actSrc	string	激活后要显示的图标，actSrc传入的是一个资源文件名称。详见Tag.setIcon部分说明。
act	boolean	是否激活标记true标识激活,需要动态传入。默认为false

A

类同于HTML源生的<a>标签。提供控制浏览器端跳转和服务端跳转的特性。

import Tag from 'pwfe-dom/tag'
<Tag.A href="/path/name" server/>

接口	类型	说明
href	string	要跳转的路径。
server	boolean	标记是否通过服务器跳转，默认为false。

setIcon

用于设置系统图标。该工具方法用于设置Icon的数据。当图标未初始化时，Icon组件所有的实例都只显示默认的空白图片，当调用setIcon方法设置图标后，所有的图片都会更新为Icon组件src名称对应的图标。

setIcon设定的图标数据为扁平化对象结构：

{
    myPicName:Base64Data=
    myAvatarName:Base64Data=
}

在代码的任意位置都可以使用setIcon方法来设置图标，以实现分片、异步等加载方法，例如下面的代码实现了分片在家独立的img模块：

import Tag from 'pwfe-dom/tag'
require.ensure([], require => {
    Tag.setIcon(require("./res/img"))
}, 'res')

而在**"./res/img"**模块中，可以这样设定图片：

/**
* 通过import或require引入图片，会将图标转换为base64。
*/
import logo from './icon/logo.png' 
const img = {
    logo
}
module.exports = img

注意，上面的代码需要设定webpack的图片loader。例如：

{
    test: /\.(png|jpg|svg)$/,
    use:['url-loader?limit=25000']
}

接口	类型	说明
img	object	设定img的资源对象。
defImg	string	设定默认图片。

flux

flux提供了redux相关的支持功能。提供的接口包括buildStore、getStore。

buildStore

buildStore提供构建store实例的功能。

import {buildStore} from 'pwfe-dom/flux'
const store = buildStore(reducer, window.REDUX_STATE)

接口	类型	说明
reducer	object	设定redux的reducer。其结构为`{reducerName:function()}。
loaderStore	object	设定已有的store对象，一般用于前后端同构渲染。

getStore

获取store实例。需要先运行buildStore创建才能获取，否则返回'undefined'

import {getStore} from 'pwfe-dom/flux'
const store = getStore()

除了直接使用import {getStore} from './flux'方式引入，还可以引入全局flux对象：

import flux from 'pwfe-dom/flux'
const store = buildStore(reducer, window.REDUX_STATE)
const store = getStore()

dispatch

执行action更新store的数据，使用前必须先使用buildStore构建store。

import {dispatch} from 'pwfe-dom/flux'
const store = buildStore(reducer, window.REDUX_STATE)
const store = dispatch(action(data))

subscribe

用于监听store的变化，使用前必须先使用buildStore构建store。

import {subscribe, getStore} from 'pwfe-dom/flux'
const store = buildStore(reducer, window.REDUX_STATE)
const store = subscribe(()=>{
    console.log('current store' , getStore().getState())
})

设置日志输出等级

可以通过webpack的DefinePlugin设定redux的日志输出等级。通过以下方式设置：

 new webpack.DefinePlugin({
    __FluxLogLevel:"'None'" //JSON.stringify('None')
 }）

设置变量说明

值	说明
'None'	什么日志也不输出
'Detail'	输出Redux变更的详细日志，包括：变更之前的数据状态，变更之后的数据状态，以及变更的值。

net

提供前后端异步请求的功能。前端请求用ajax实现、后台请求使用nodejs提供的http包实现。net模块中提供net、get和post方法。所有的请求返回一个serverNetwork实例或一个browserNetwork实例。通过函数式的方式来获取数据，回调提供3个方法suc、err，headers，例如：

import {net,get,post} from 'pwfe-dom/net'
net({
    method: 'GET',
    url: '/myPath/value'
}).suc((data)=>{})
  .err((err,msg)=>{})
  .headers((header)=>{})

get('/myPath/value')
  .suc((data)=>{})
  .err((err,msg)=>{})
  .headers((header)=>{})

post('/myPath/value',{key:'kye',value:'value'})
  .suc((data)=>{})
  .err((err,msg)=>{})
  .headers((header)=>{})

net方法

net传递的是一个options对象——net(options)。下面是options的参数：

接口	类型	说明
method	string	请求的方法GET或POST。
url	string	请求地址。
data	object或string	要传递的数据。可以是一段字符串，或者是一个JSON结构的对象。
header	object	请求的头部，格式为：{"Accept":"application/json"}。
query	object	请求的查询字段，类似的get请求的？参数。
withCredentials	boolean	标记是否跨域传递cookie。为了便于在测试环境中全局使用，可以在webpack中全局配置__WithCredentials=true

get方法

GET请求。

接口	类型	说明
url	string	请求地址。
query	object	请求的查询字段，类似的get请求的？参数。

post方法

POST请求。

接口	类型	说明
url	string	请求地址。
query	object	请求的查询字段，类似的get请求的？参数。

router

router 提供路由、链接、跳转、重定向等功能。模块包含的组件有：Route, Router, reRoute, Link, Redirect, StaticRouter。 其中Route, Router, Link, Redirect, StaticRouter 基于react-route实现。请参看对应的说明。

1. Route：https://reacttraining.com/react-router/web/api/Route
2. Router：https://reacttraining.com/react-router/web/api/Router
3. Link：https://reacttraining.com/react-router/web/api/Link
4. Redirect： https://reacttraining.com/react-router/web/api/Redirect
5. StaticRouter：仅用于后台渲染。https://reacttraining.com/react-router/web/api/StaticRouter。

reRoute是一个提供路由控制功能的高阶组件。采用react高阶组件的方式使用：

const MyComponent = reRoute()(props=>{
    const browser = props.browser; //获取browser对象来操作路由
    return(<div>组件</div>)
})

browser提供了多个路由方法和属性值：

接口	说明
local	通过服务器跳转。跳转石会访问服务器，浏览器重新刷新页面。原有的内存数据会丢失。 调用方法：browser.local('/myPath')
forward	浏览器向前跳转，使用该方法时不会发生服务器请求，只会发生react组件替换。 若不传入url参数，则浏览器会发生前进一页的行为。 若传入url参数，浏览器会自行跳转到对应url。 调用方法：browser.forward('/myPath')
back	浏览器回滚，不会发生服务器请求。 调用方法：`browser.back()
path	获取当前页面的访问的相对地址。如http://domain(:port)/myPath/myParam 调用browser.path()会返回'/myPath/myParam'。如果在routes中将路径配置为/myPath/:pamram,则获取到的数据为/myPath/:pamram
url	获取当前页面的访问的相对路径。如http://domain(:port)/myPath/myParam 调用browser.path()会返回'/myPath/myParam'。如果在routes中将路径配置为/myPath/:pamram,则获取到的数据为/myPath/myParam

设置history的类型

可以通过webpack的DefinePlugin设定react-route的history类型。通过以下方式设置：

 new webpack.DefinePlugin({
    __History:"'Browser'" //JSON.stringify('Browser')
 }）

设置变量说明

值	说明
'Hash'	类似于http://domain(:port)/#/path这样格式的URL。可参看关于hash的说明:https://reacttraining.com/react-router/core/api/history
'Browser'	标准的浏览器格式：http(s)://domain(:port)/path

util

util提供了最基础的工具。包括getComponentName、isServerEvn、asyncLoader和safeGetValue。

方法	说明
getComponentName	获取react组件的名称。
isServerEvn	获取当前的运行环境是服务器端还是浏览器端。
asyncLoader	异步加载类。用于等待某一项任务完成，然后通知所有的处理器。
safeGetValue	从对象中安全获取属性。
案例：

//import util from 'pwfe-dom/util' 全局引用
import {getComponentName} from 'pwfe-dom/util'
console.log(getComponentName(component))

asyncLoader使用方法:

//import util from 'pwfe-dom/util' 全局引用
import {asyncLoader} from 'pwfe-dom/util'
/**
* 新建一个asyncLoader实例。
* 新建时传入回调方法，表示需要加载的内容。
* call由asyncLoader传入，加载的内容成功后，需要调用call方法
*/
const loader = new asyncLoader({
    loader: (call)=> {
        require.ensure([], require => {
            call(require('superagent'))
        }, 'request')
    }
})
//注册一个处理器，
//当第一个处理器被调用时，上面传入的loader方法会被触发。
//laoder方法执行回调之后
//
loader.register((result)=>{
    console.log(resule)
})