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/>源生属性和方法。参见：https://github.com/palmg/react-scroll-over-img#readme

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 | 从对象中安全获取属性。 isElement | 判断当前内容是一个React的类还是一个元素(实例)。 案例：

//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)
})