kaola-fed / nek-ui Goto Github PK

目前 URL 导出文件的两种方式都不太友好：

• window.open() // 浏览器会拦截
• location.href = // 页面会被覆盖

因此，为 ui.button 增加 export 属性，内部实现是增加一个隐藏的 <a href={xxx} download style="display:none">download</a> 链接，导出时设置 href 并且模拟点击

1. 实现循环向外寻找validation组件；
   2.表单组件init方法方法中的push control部分逻辑，统一放在一起；暂定继承；

弹窗内容过多时样式会错乱，增加 maxHeight 参数并且设置 overflow: auto

主要用于 request 时传递

https://www.npmjs.com/package/validator校验的值必须是string；
This library validates and sanitizes strings only.

If you're not sure if your input is a string, coerce it using input + ''. Passing anything other than a string is an error.

DOMSubtreeModified事件firefox浏览器会造成死循环, 本来这里加事件的原因是为了处理:pop.confirm中验证之后,高度变化造成对不齐的情况 ;

增加 disabled 参数，disabled 时点击不生效

代码错误

form.item越多调用的次数越多

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

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

参与开发

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

协作流程

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

• 在 issue 上发布详细开发介绍（仅仅针对功能扩展和缺陷修复，文档和测试可以不用开 issue），说清楚做什么，为什么要做这个，以及达到的效果
• 拉取最新 master 分支代码，以此为基础开一个新的分支
• 开发 & 调试 & 文档完善 & 测试完善（建议按功能点分多次 commit，commit log 一定要有意义）
• 觉得功能差不多的话，先别急着发 PR，需要先 git fetch origin && git rebase origin/master，之所以这里不用 merge 是为了保持自己分支的干净
• 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 代码区域标记出来，一个典型例子如下：

通过 <!-- 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 选中状态
 */

测试部分

测试方案

组件的测试采用UI自动化测试方案。采用的框架是PhantomFlow, 他结合了PhantomJS, CasperJS 和 PhantomCSS, 通过Casper打开测试页面，模拟用户操作，PhantomCSS截图或者Casper检查DOM，来实现自动化测试。

测试文件目录

在项目根目录下有个test文件夹，来放置测试相关代码。

• test/test.js是运行测试的入口文件。
• test/index.html是测试页面，所有组件的测试共用这一个页面，通过inject不同的组件demo来测试不同的组件。
• test/components文件夹下是组件测试文件，目录结构保持跟src/js/components一致。
• 组件测试文件命名统一以.test.js结尾，程序只会运行以.test.js结尾的文件。这里推荐统一命名index.test.js。

测试运行流程

• npm run build 生成dist文件夹，执行这一步是因为index.html中需要引入dist下的nek-ui.js和nek-ui.default.min.css
• npm run test 运行测试。第一次运行的时候，测试会在test目录自动创建visuals文件夹，存放PhantomCSS截图，并以这次的截图作为baseline。当然index.test.js中有断言的地方也会在控制台显示结果。
• npm run test 再次运行。会将此次运行的截图和baseline比较，不同的就标记为失败。

其他命令：

• npm run test report 查看运行报告。如图：

• npm run test debug　　　　使用debug模式，输出更多的信息，运行会更慢，只会以单进程运行。
• npm run test threads=xx　　设置测试运行的进程数，默认不设置的情况下进程数是8
• npm run earlyexit　　　　　有报错的情况下立即退出
• npm run tests=xxx　　　　 设置运行的文件夹，默认运行test目录下的所有.test.js结尾的文件，如只希望运行ui.select，可使用npm run test tests=test/components/form/ui.input

测试文件书写介绍

Phantom基于决策树来模拟用户操作。包含这几个方法：

实际使用示例：

在report的体现类型(不对应上图的那个case)：

Phantomflow只是来组织操作流，具体的操作还要用过Casper来实现。

常用的casper API有：
casper.thenOpen， casper.echo， casper.waitForSelector，casper.wait，casper.click，casper.mouseEvent，casper.test等。

casper module

tester module

phantomCSS只使用其截图功能，phantomCSS.screenshot(selector) 即可。

目前的想法：

1. ui.button里面加个监听器， 外部在request通用的地方，可以在request之前dispatch一个loading的event， request返回后， 再dispatch一个去除loading的event；

2. ui.button和request通过请求的url实现匹配；

统一tip的显示位置；国际化组件增加组合方法；

249f311

180c197

目前是text-align：center； vertical-align：middle的形式； 缩小浏览器宽度小于modal宽时， modal就掉到页面最下面去了；

替换方案：
用position：fixed， left, top， transform的方式实现居中

希望增加一个确定按钮和取消按钮

避免国际化麻烦

pop.confirm中的textarea中超过一行， 出现滚动条后， 如果有hideWhenScroll， 再输入pop.confirm就消失了

umd" - Export to AMD, CommonJS2 or as property in root

如果不加commonjs2， 打包出来后， regularjs为undefined
if(typeof exports === 'object' && typeof module === 'object') module.exports = factory(require(undefined));

radio.goup目前没有value的值绑定

日期控件-时间选择显示错位，疑似display:block导致：

目前对外暴露的有 selected 和 value，在多选的时候，其中 selected 是选择对象的数组，value 是选择对象 id 列表用 , 拼接的字符串。然而场景如果仅仅需要 id 的列表就需要每次手动处理下 selected 或者 value，效率略低，增加 valueList 仅仅用于提供 value split 后的列表

以下例子，如果 list 是动态变化的话 sourceKey 会无效，需要 watch controls 长度变化后请求可修正

  <ui.form service={@(service)}>
    {#list list as item}
      <form.item title="区域" sourceKey="source">
        <ui.select />
      </form.item>
    {/list}
</ui.form>

当然，特殊情况下（数量不变，仅仅是内容变化）这个 bug 依旧会出现

树形选择增加多选，包括增加了以下参数：key/nameKey/childKey/value/...

null作为空字符串处理

如果inline，则form.item按照inline-block排列；

check.group组件内没有watch到value的改变

比如，minDate = 2016-01-05，选择时会显示区间是 [ 2016-01-03 , ) 为 Disable 状态，但是 2016-01-04 选的时候并不会触发 select 事件

1. 最多选几个， 最少选几个；
2. 有一些是必选；

bec15dc

因为代码里用到了一个 == 比较了 0 和 ''，出现了错误赋值，两边都强制转为字符串判断即可

原因：有时候只想用获取接口，不想要套form；
多个ui.form嵌套也不合适；

JIRA 42636

目测 Regular 的 list by index 问题，暂时去掉

包含：ui.input, ui.select, date.picker

37af6ee

日期控件，调整时间，报如下错误：

如果 canSearch 设置为 true 则点击的时候下拉会闪烁

某些场景需要在点击确定的时候仅仅是把 ok 事件 emit 出来，而不关闭弹窗

目前使用的是不规范的 jsdoc 注释法，并且是自己写的 parser 方法，不具有通用性

建议使用规范语法，然后直接采用 jsdoc2md 转成 Markdown 文档

需要watch value

formitem_tt 指定栅格后，formitem_ct 的也要指定栅格

1. form.item下多个input表单元素， 验证message只会显示最后一个
2. ui.form内的form.item销毁时， 引用没有去除