Skip to content

开发须知

Jump to bottom
Cody Chan edited this page Jul 6, 2017 · 3 revisions

如果你需要参与 nek-ui 的开发，有必要完整地看下这个

此工程原先是从 Regular UI fork 过来的，由于 Regular UI 缺陷比较多又不能得到即时更新，于是 nek-ui 激进地选择重新写，当然大部分组件代码还是沿用 Regular UI 的

参与开发

组件的开发只需要 cd doc && npm install && cd .. && npm install 之后 npm run dev 即可，脚本已经封装了所有任务，会自动 watch src/ 下的改动，并且自动更新文档

协作流程

master 已经设为保护，不可以直接提交，一个正常的功能开发主要流程如下：

  • 在 issue 上发布详细开发介绍，说清楚做什么，为什么要做这个，以及达到的效果
  • 拉取最新 master 分支代码，以此为基础开一个新的分支
  • 开发 & 调试 & 文档完善 & 测试完善（建议按功能点分多次 commit，commit log 一定要有意义）
  • 觉得功能差不多的话，先别急着发 PR，需要先 git fetch origin && git merge origin/master
  • push 你的分支后，直接创建一个 PR 即可
  • 因为这个是基础库，牵一发动全身，所以一定要找人 Code Review ，最好两人
  • Review 完后会合并到 master

重构部分

完全按照组件化的思想组织结构

  • src/js/components 目录里是所有对外的 UI 组件，一级目录为类别，二级目录为组件名（暂且称作为组件目录），组件目录下一般有 index.js、index.mcss、index.md、index.html 等
  • 将样式代码分离，分离为四个部分：
    • 基础部分：位于 src/mcss/base，原则上是不做轻易改动的
    • 主题部分：位于 src/mcss/ ，主要是抽离出来的一些可配置的样式变量，目前只有颜色
    • 组件部分：分布于各个组件目录，原则上这里的样式只依赖公共部分和主题部分，组件间不应该有依赖关系
    • 公共部分：当然，组件间不可能一点关系没有，如果有一些组件间有依赖但是又不属于公共部分，那么可以放在 src/mcss/common 下
  • 文档参考 VueJS 的文档思路，采用 Hexo 构建，这样可以做到文档和代码之间尽可能解耦，文档对外友好的同时也可以提升开发效率

文档结构

因为文档是用 Hexo 构建的，所以还是比较建议看下 Hexo 的文档，当然因为脚本已经封装了和隐藏了很多操作，如果不看 Hexo 文档其实也不太影响

按照 Hexo 的组织，文档 Markdown 源文件是放在 doc 文件夹下的，但是由于从 markdown 转 html 之前我们的组件文档是需要添加一些额外的内容的（组件实例化脚本、API 文档等），所以需要做一些转化，于是就有了 组件文档 ---> Hexo 源文件 ---> Hexo 目标文件（纯静态站资源） 的构建链路

组件文档 ---> Hexo 源文件 的过程是通过 doc/doc.js 脚本（配合 gulp 使用）实现的，doc.js 主要干了以下几件事：

  • 增加头部信息，用于渲染左侧多级菜单
  • 把组件内的 jsdoc 注释转为 MD 追加到尾部，用于生成 API 文档
  • 把 DEMO 代码实例化为组件

注：除了组件目录下的文档被转换了，其实 doc/ 下的文档也被转换了（主要是组件实例化操作），但是在开发阶段为了避免产生额外的文件变动，只有在 CI 时才会做这个操作，总结就是，开发阶段如果往 doc/ 下文件里加 DEMO 代码，是看不到实例化的效果的

文档书写

格式规范

  • 尽量保证只出现 2/3/4 级标题
  • 以尽可能覆盖测试点为目的

文档参数头

Hexo 文档构建只关心 doc/ 下的 Markdown 文件，URL 的 path 跟目录名是一致的，每个目录下可视为一组文档，通常会被组织在侧边菜单，因此需要指明 order 参数用于排序，然后还会有标题 title，文档的开头一般都会有个参数头（如果整个目录只有一个文件，则可以不写参数头），形式如下：

---
title: <标题>
type: <跟目录名一致即可>
order: <序号>
---

src/js/components/ 组件目录里的文档则不用写 order 和 type，因为 doc.js 统一处理了，不过要注意，order 参数值是自动加的，所以不能保证菜单顺序。组件文档除了 title 参数需要写外还有两个参数可以根据需要添加：is_new: true 如果是新组件，is_beta: true 如果组件还在开发中，这两个参数会在菜单栏左侧生成响应徽标，比较友好

组件实例

文档里大部分是组件的 DEMO 实例，为了减少重复工作，文档里我们只需要写代码即可，doc.js 脚本会把代码区域提取出来，正确拼接后放到 <script> 里然后追加到文档尾部，这样我们就可以在每个文档里看到对应代码实例化的组件了，为了让 doc.js 正确识别出是否需要实例化组件（因为也有些时候我们恰恰只需要看代码或者根本无法实例化代码对应的组件）需要把 DEMO 代码区域标记出来，一个典型例子如下： selection_627

通过 <!-- demo_start --> 和 <!-- demo_end --> 标识开始和结束，必须有 <div class="m-example"></div> 用于 inject 组件，rgl 模板用 xml 格式，javascript 用 javascript 格式。注意这里的 javascript 一般是可选的，如果不写表示默认为var component = new NEKUI.Component({template: template});

API 规范

组件的 API 是由 doc.js 从组件目录下的 index.js 抽离出来的，因此注释必须符合 标准 JSDoc 规范，就目前组件来说，一般只用到三种：

  • 组件类
/**
 * @class Input
 * @extend Component
 * @param {object}      [options.data]                = 绑定属性
 * @param {string}      [options.data.text=文本]      <=> 内容
 * @param {string}      [options.data.size]           => 大小
 * @param {boolean}     [options.data.isBold=false]   => 是否加粗
 * @param {string}      [options.data.align]          => 左右对齐方式
 * @param {string}      [options.data.vertical]       => 上下对齐方式
 * @param {string}      [options.data.type=default]   => 文本样式
 */
  • 对外方法
/**
 * @method check(checked) 改变选中状态
 * @public
 * @param  {boolean} checked 选中状态。则在true/false之间切换。
 * @return {void}
 */
  • 事件
/**
 * @event check 改变选中状态时触发
 * @property {object} sender 事件发送对象
 * @property {boolean} checked 选中状态
 */
Clone this wiki locally