背景

目前社区没有较为优秀的 weui+react 框架，而我们使用的是 React0.13 的老版本，新版 React 框架并不兼容，weui 虽然提供了标准的视觉规范组件，但并没有封装成运用于项目的UI交互组件。

所以我们决定自己维护开发一套基于 weui+React 的组件库，以便在项目开发中使用搭积木的方式快速高质量的实现业务需求。

概述

mt-weui-react v1.0 版本包含基础类、交互反馈类、数据展示类、数据录入类、导航类等多，已有 37 个基础组件，未来还会添加更多基础组件和业务组件以增强数据交互和展示。

  • 组件开发参考了优秀的移动端组件库 Vux2.5版本 ，Vux在不断的应用实践中跌代完善，是值得借鉴学习的样本库，让我们的组件开发少走很多弯路，也更加具有易用性、稳定性和扩展性。
  • 提供了详细的 使用文档，每个组件各个功能点都有详细的说明和示例代码，如果需要应用到项目，直接复制文档上的代码即可。
  • 支持按需引用，使用Bable插件 babel-plugin-import 简单配置，可以优化代码体积，按需加载组件，搞高前端性能。
  • 使用 weui 样式库，统一标准的视觉规范。

预览

在线Demo

进度与计划

1.x 版本

该版本主要以基础组件开发为主，为以后的业务开发提供基础组件服务

2.x 版本

该版本会扩展部分基础组件，但会以业务组件开发为主，为业务需求提供定制更多标准组件，以便以后相似业务的快速实现

使用

组件库提供了完善的中文文档及代码示例，以便快速查阅应用。

在线文档

安装

组件库已发布到 NPM 仓库，直接使用npm安装到项目

  1. npm install mt-weui-react --save

引用

  1. import React from 'react'
  2. import { Button, Flex } from 'mt-weui-react'
  3. const FlexItem = Flex.FlexItem
  5. let App = React.createClass({
  6.   render() {
  7.       return (
  8.         <Flex>
  9.           <FlexItem><Button>hello wechat</Button></FlexItem>
  10.           <FlexItem><Button>hello wechat</Button></FlexItem>
  11.         </Flex>
  12.       );
  13.   }
  14. })
  16. ReactDOM.render((
  17.     <App/>
  18. ), document.getElementById('container'));

按需引用

在非SPA应用中使用，最好使用按需要引用的方式加载需要用到的组件，以节省加载资源，按需引用有两中方式引用

直接引用

  1. import Button from 'mt-weui-react/lib/components/button'

使用Babel插件，编译成上面的方式

安装 babel-plugin-component babel插件

  1. npm i babel-plugin-component --save-dev

在文件 .babelrc 文件中添加配置

  1. "plugins": [
  2.  ["component", {"libraryName": "mt-weui-react", "libDir":"lib/components", "style": false }]
  3. ]

然后在项目中正常引入相关组件，最后会被编译成按需引入的方式

  1. import { Button } from 'mt-weui-react'
  3. // 经过插件转译为：
  4. import Button from 'mt-weui-react/lib/components/button'

版本管理

  • BUG修复、UI调整及组件增强发布小版本 0.1.x, package.json 中使用前缀 ～ 安装时更新
  • 删除组件或对组件API做调整时发布子版本 0.x.1, package.json 中使用前缀 ^ 安装时更新
  • 稳定版本发布大版本 x.1.1, package.json 中手动更新版本号

版本更新必须记录日志，构建文档，随项目一起发布到Github

关于版本号的小知识:

  • alpha版：内部测试版。α是希腊字母的第一个，表示最早的版本，一般用户不要下载这个版本，这个版本包含很多BUG，功能也不全，主要是给开发人员和 测试人员测试和找BUG用的。

  • beta版：公开测试版。β是希腊字母的第二个，顾名思义，这个版本比alpha版发布得晚一些，主要是给“部落”用户和忠实用户测试用的，该版本任然存 在很多BUG，但是相对alpha版要稳定一些。这个阶段版本的软件还会不断增加新功能。如果你是发烧友，可以下载这个版本。

  • rc版：全写：Release Candidate（候选版本），该版本又较beta版更进一步了，该版本功能不再增加，和最终发布版功能一样。这个版本有点像最终发行版之前的一个类似 预览版，这个的发布就标明离最终发行版不远了。作为普通用户，如果你很急着用这个软件的话，也可以下载这个版本。

  • stable版：稳定版。在开源软件中，都有stable版，这个就是开源软件的最终发行版，用户可以放心大胆的用了。

本地开发

到 mt-weui-react 的 github仓库 中fork项目

将项目克隆到本地

添加组件

在项目目录 src/components 下添加组件

组件目录文件

  1. index.js   // 组件主文件
  2. index.less // 样式
  3. metas.yml  // 组件描述

metas.yml 用于描述组件，最后会生成该组件的说明文档

metas.yml 结构说明: 

  1. # 属性说明
  2. props:
  3.   list:
  4.     type: Array
  5.     default: []
  6.     desc: 图片列表
  7.   options:
  8.     type: Object
  9.     default: {}
  10.     desc: '`photoswipe` 的设置'
  11. # 事件说明
  12. events:
  13.   onClose:
  14.     desc: 关闭的回调
  15. # 方法说明
  16. methods:
  17.   show:
  18.     params: '(index)'
  19.     desc: 图片的索引
  20.   close:
  21.     params: '(index)'
  22.     desc: 图片的索引
  23. # 组件更新说明
  24. changes:
  25.   v0.1.15:
  26.     - '[new] 新组件 图片查看器，点击放大查看图片'

changes 中 的 [new] 用于标识组件变动类型，内置有以下几中类型:

  • feature 添加新的功能
  • fix 修复了bug
  • new 为新增组件
  • change 更新功能，如更改了样式
  • enhance 增强功能，如添加了新的api
  • deprecated 去掉某功能

在文件 src/index.js 中导出组件

编写示例

  • 到目录 example/pages 添加组件示例页面
  • 到 example/index.js 中导出页面模块
  • 到 example/app.js 文件下添加路由
  • 到 example/pages/home/index.js 首页文件下添加组件链接

示例页面

  1. import React from 'react'
  2. import { Group, Cell, Switch } from '../../../src'
  3. import Page from '../../component/page'
  5. var Demo = React.createClass({
  6.     changeEv(checked){
  7.       console.log(checked);
  8.     },
  9.     render: function() {
  10.       const cusLabel = <span><i className="weui-icon-download"></i><span>开启下载</span></span>;
  11.         return (
  12.           <Page title="Switch">
  13.             <Group title="一般使用">
  14.               <Switch label="飞行模式" checked={ false }  onChange={ this.changeEv }/>
  15.               <Switch label="蓝牙"  checked onChange={ this.changeEv }/>
  16.               <Switch label="禁用缓存" checked={ true }  onChange={ this.changeEv }/>
  17.             </Group>
  19.             <Group title="禁用">
  20.               <Switch label="蓝牙"  checked disabled onChange={ this.changeEv }/>
  21.               <Switch label="禁用缓存" checked={ false } disabled onChange={ this.changeEv }/>
  22.             </Group>
  24.             <Group title="自定义label">
  25.               <Switch label={ cusLabel }  checked onChange={ this.changeEv }/>
  26.             </Group>
  27.           </Page>
  28.         );
  29.     },
  30. });
  32. export default Demo

预览构建

  • 启动项目 npm run start，默认访问地址 http://localhost:8081

  • 更改版本，在文件 package.json 与 src/version.js 更改版本编号

  • 构建组件，执行命令 npm run build 构建组件为 ES5 版本

  • 构建示例，执行命令 npm run build:example 构建组件Demo 示例项目

  • 构建文档 执行命令 npm run build:docs 构建组件的说明文档

提交合并

将项目推送至你的 github 仓库后，提交 PR

更新版本

项目中使用 npm update mt-weui-react 或 yarn upgrade mt-weui-react 升级版本

总结

接下来要做的事情还有很多:

  • 增加一些基础扩展组件及业务组件
  • 在组件的易用性、稳定性上不断提升和改良
  • 会和UI组使用，在细节上让组件更加规范、漂亮
  • 更新项目中旧的组件为组件库中的标准组件
  • 根跟实际应用，对组件库的API进一步优化升级
文档更新时间: 2017-10-20 10:45