node package manager
Loosely couple your services. Use Orgs to version and reuse your code. Create a free org »

spon

安装cnpm和spon

尚妆前端开发的套件名称是spon,目前已发布在npm模块库中,由于npm的源在海外,因此安装相关插件的速度比较慢,所以,针对spon,非常建议你使用淘宝的第三方镜像源,cnpm。 安装cnpm之后,执行sudo cnpm i -g spon,等待2min,spon就安装到系统上了。 # spon初始化 spon安装完成之后,可以执行命令spon查看相关的命令说明。在使用具体功能之前,先初始化spon的执行环境,它会检测当前系统有没有安装yeoman和gulp命令,以及copy相关的npm组件。这一切,通过spon init运行。

mobi的使用

spon初始化完成之后,我们就可以使用针对移动端开发的spon的插件-mobi了。执行spon mobi,可以看到相关的子命令,这些命令与尚妆前端的开发流程以及规范密不可分,在下文中会着重讲解。 ### 神马是mobi工程 mobi工程是mobi管理的工程,在mobi工程的当前路径下,我们可以看到一些配置文件,这些文件根据mobi工程的类型不同而不同。那么,mobi工程有哪些类型呢:

  1. page工程
  2. component工程
  3. ReactNative工程

以上。 page工程就是页面工程,对应着一个java工程。一个page工程中可以有多个页面,每个页面根据名称区分; component工程就是一个组件,它复用可充用的逻辑,我们可以在page工程的js文件中引用它; ReactNative工程就是一个ReactNative组件,目前并没有对其进行开发,暂且不表。

以上三种类型的mobi工程,都是一个git本地仓库。也就是说,我们的mobi工程必然是被git托管的,因此,在gitlab上必须对应一个远程仓库,我们根据项目的需要,在group:showjoy-assets,ggl-assets,fecomponent中进行创建项目,命名规则同时也需要遵循规范:

"针对尚妆的页面工程,根据是否是移动端或者pc端,在工程名后面加后缀"-m" or "-p",如对于交易工程,我们在组 showjoy-assets中创建trade-m的移动端工程,trade-p的pc端工程"
"针对够给力的页面工程,同理"
"针对组件工程,在gitlab的fecomponent组中进行创建工程,工程名为组件名称,并且在创建仓库时,需要确保该工程是可见的,即为public权限"

再次强调,针对component工程,必须在创建gitlab仓库时确保工程可见,即public权限,否则在构建过程中肯定会报错!!

初始化工程

该命令的作用是初始化一个工程为mobi项目(mobi管控的工程)。 1,spon mb init (初始化page工程) 2,spon mb init -c (初始化component工程) 3,spon mb init -r (初始化RN工程) 执行该命令,会出现一系列的交互,需要用户填入“对应gitlab的组”,“开发者”,“相关依赖”等,据实填写,如果有不明白的地方,请联系欲休。 ## spon mb add add命令仅仅针对page工程而言,在实际的page工程中,肯定会有多个页面的情况,因此添加第二个页面或者更多页面的情况下,需要执行spon mb add命令,输入需要添加的页面的名称即可。 #### add命令只针对page工程。 ## 调试模式 dev命令则在本地开启服务器,默认实现了livereload功能,在开发page工程的时候可以在本地进行调试。 dev命令可以手动指定tcp端口号和livereload端口号,如 spon mb dev -p 8080 -r 29909 #### dev命令只针对page工程 ## 本地构建和测试 针对移动端项目开发,采用commonJS规范,编写的格式完全按照npm模块的方式书写,这样不管在以后node模块复用还是进行后端(node端)模板渲染的情况下,更方便的迁移。但是commonJS规范是针对服务端的规范,而前端的代码都是通过网络加载,因此如果仅仅在浏览器端采用原始的commonJS肯定会出现“undefined”错误,所以,有了这步的build。当然,build并不仅仅是引入依赖,还有完成代码的相关检查,如js的书写规范,less的编译等。 本地build的作用就是将js中引用的其他模块合并到当前js的数组中,依次加载所有的依赖数组中的项即可完成依赖的加载。 命令很简单,就是执行spon mb build即可。需要注意的是,在调试情况下,每次修改源码之后,都需要进行build,build之后再开启本地服务器进行浏览器端的测试。这样做的原因很简单,就是源码一旦改变,必须重新构建出新的代码进行测试,否则并没有更新。 #### build命令只针对page工程,对于component而言,没有必要进行构建,因为我们会在page工程中的js文件引用component,这样在page工程中构建就完全将component工程的代码引入并压缩了。 ## 测试 编写的代码不仅仅逻辑上需要打通,更需要高可靠性。所谓的单元测试往往针对后端的代码,如java的jUnit测试框架,保证接口的可靠性,以及高覆盖率。而针对前端的代码,我们也需要进行单元测试,前端的测试可以通过通过自己debug完成,但是更为规范的仍是采用测试框架来完成。目前已着手开始开发前端代码测试模块,未来可以通过spon mb test的命令完成某个模块的测试。 ## 发布 构建并测试完毕之后发布:
1,spon mb publish (发布当前mb工程之测试环境,地址为 assets.showjoy.net/${groups}/${project}/${path})
2,spon mb publish -o (发布之线上环境) #### 执行publish操作,会默认先执行build操作,build完成之后,会需要开发者输入相关的信息和发布的标签号,在这里信息需要输入有实际意义的信息,而标签号则须遵循规范,如果发布至线上环境,格式为publish/x.x.x;发布至测试环境,格式为dev/x.x.x。一旦格式正确,则会进入服务端的发布流程,完成最终的发布。 ## 升级 在page工程的根目录,可以看到一个mobi.json文件,该文件作用就是记录了在初始化(spon mb init)该page工程时的所有的线上模块版本号,该文件保存在服务端。一旦有新的模块发布或者原有的模块发生改动,服务端的文件会更新,而我们当前的page工程的mobi.json并不会更新,意味着在该工程下,我们无法require新的模块。解决这种情况的方式有两种:

  1. 手动修改添加变动的模块及依赖
  2. 通过spon mb upgrade更新mobi.json 这样,完成了模块的版本控制,也实现了在原有的工程使用更新的模块。

FAQ

1. 命令行spon的调用,必须在工程的根目录。

ex: gitlab上创建一个新的仓库abc,在客户端执行git clone git@git.showjoy.net:showjoy-assets/abc-m.git,会出现一个空的abc-m目录, 然后cd abc-m,在这里,就是所谓的工程的根目录。所有的命令行必须在根目录执行,否则会出现file not found等错误。 ### 2. 组件的引用方式require('fecomponent/mobi-${name}') 有不少同学和我提到了为什么在引用组件时,非得在组件名称前加上mobi-这个前缀,原因就是为了以后的兼容性。目前仅仅针对移动端的工程做迁移,因此fecomponent组中的组件自然都是移动端的组件,而在未来pc的工程肯定也会进行拆分,这样我们在js文件中仅仅require ### 3. component的修改 ex:我刚刚接到一个需求,即"针对fecomponent组的jswebview组件做一次升级:原来的jswebview中require了两个模块,即zepto-callbacks和zepto-deferred。但是由于去全局化的需要,针对mobile段的global.js做拆分,将UA判断的逻辑拿出来放在了一个新的模块下,即detect-ua组件。而jswebview组件也依赖detect-ua组件,因此我们再在代码中require(fecomponent/detect-ua),认为这样就大功告成了。这样是错误的,在构建引入jswebview组件的page工程中会出现错误,原因是找不到'fecomponent/detect-ua'组件。" #### 解决方案:这是由于服务端的mobi.json并没有更新jswebview组件的依赖。在初始化jswebview组件的时候,我们输入了该组件的依赖,即zepto-callbacks和zepto-deferred。服务端的mobi.json记录了这两个依赖,而当我们手动添加了另一个依赖fecomponent/detect-ua的情况下,jswebview根目录的package.json的dependencies属性并没有改变,因此服务端的mobi.json也就没有更新。所以我们仅需在根目录的package.json中添加正确格式和版本的detect-ua,在执行publish操作,就完成了服务端配置文件的更新! ### 4. .DS_Store文件夹(文件)造成的spon mb build失败 同学们在使用spon mb build进行本地构建的过程中,有可能会出现错误,错误信息中提到了由于src/pages/.DS_Store的存在,导致无法解析该目录的文件。.DS_Store文件时Mac os中用于记录文件夹现实属性的隐藏文件,对于我们的spon而言,这个隐藏目录的存在是不必要的,因此执行 rm -rf .DS_Store命令即可。   ### 5. less共用组件的修改 mobile工程的有些页面的less中可能会引入除mixins.less之外的less模块,建议在src/mixins/${name}/${name}.less引用。注意,less模块的路径引用不要出错。 ### 6. 引用带有版本号的组件(确保spon的版本号为0.1.3) ex: 仍以fecomponent/mobi-jswebview组件为例,当前最新的版本为0.0.5,暴露了$.JSBridge的相关接口;而我们的项目却依赖0.0.1版本的jswebview组件,该版本组件并没有$.JSBridge,而是$.Operate接口,此时该如何做呢? #### 解决方案:由于服务端的mobi.json中记录的jswebview的版本号为最新的0.0.5,因此在业务逻辑的js中以require('fecomponent/mobi-jswebview')方式引入会默认引入最新版本,可以通过附加版本号的方式-require('fecomponent/mobi-jswebview/0.0.1')引入制定版本号的模块,引入的格式一定要规范! ### 7. spon版本升级到0.1.2后build之前创建的工程出错 ##### 方案:是由于版本升级后,对根目录下spon.json做了些扩展。为了保证build旧工程成功,请在根目录下重新执行spon mb init,更新spon.json配置文件即可。 ### 8. fecomponent模块进阶(确保spon的版本号为0.1.3) #### 回顾:之前针对组件的开发,主要逻辑都在index.js文件中,而且针对有css(less)引用的组件无能为力。为了保证软件工程中的“单一功能”作用,我们可以将单一的功能拆分成诸多功能模块,放在某个文件夹下,如lib,而在index.js中以相对路径方式引用,这样在组件内部解耦,容易分工开发组件。具体的复杂组件编写模式,可以查看线上实例:fecomponent/mobi-withcss #### 要点:关于在组件中以引用css(less)和模块,必须以相对路径方式引用,即“./sth.less”的方式。 ### 9. 异步渲染模板的功能 #### 针对移动端,目前h5页面并为采用模版异步渲染的机制,这对于开发长列表展示页的性能很不友好。现在在page工程中,集成了模板功能,模板的书写语法就是大家在用的art-template简单语法,这样每次build之后我们就可以在页面上看到引用的模板。

在spon中,规定模板的后缀为.tmpl,也就是说spon会对src目录下的所有.tmpl文件进行解析,并生成对应的js文件。建议每个目录下只有一个tmpl文件,这样做到模板的模块化。

在js中,可以这样引用模板:

showjoy模板:

<h1>{{title}}</h1>
<p>{{titleDesc}}</p>
var tmpl = require('./showjoy');
$('main').html(tmpl({
  title: 'this is the art-template example',
  titleDesc: 'nothing to say!'
}));

10. spon集成showjoy-assets/portal的发布功能

简介: spon在0.1.6版本提供了portal的发布功能,命令如下:

spon pc publish (-o) 对应 发布至测试(线上)

11. 本地营销页面spon工程

营销页面目前没有统一的远程仓库地址,在本地执行spon mb init命令创建工程时会出现错误。正确方式是先去自己的gitlab创建一个仓库,再讲仓库clone下来。本地进入这个仓库就可执行spon mb init命令创建工程。

12. rem布局规范

0.1.10版本的spon添加了rem插件,该插件作用可以让rem的大小自适应。rem插件必须与flexible.js文件匹配(http://cdn1.showjoy.com/assets/f2e/joyf2e/vendor/0.0.6/flexible/flexible-min.js),目前公司使用的flexible是将设计稿插件针对的750px的设计稿,因此,在设计稿上一个banner的宽度是750px,可以在less中这样定义:

.banner{ width: 750px; font-size: 16px; } 这样,使用spon mb rem之后,会计算成 .banner{ width: 10rem; font-size: 16px; } 当然,现实情况中不回有这么简单的情况,举个例子: 设计师往往给我们视觉稿中有1px的边框要求,如果还是简单的采用rem放缩,那么肯定最终在终端的呈现效果很有可能不是1px。那么,如何避免呢?有些同学可能有了解决方案,如高分屏下设置0.5px,或者使用tramsform进行scale缩小,但这都是基于px为前提的。因此我们需要针对某些属性放弃使用rem变换,当然也有可能需要我们手动添加某些属性使用rem变换,这取决于项目的具体需求。 目前,spon工具默认针对以下css属性做rem判断:

'font','font-size','line-height', 'letter-spacing','text-indent','word-spacing','width','height','max-height','max-width','min-height','min-width','left','top','right','bottom','margin','margin-left','margin-top','margin-right','margin-bottom','padding','padding-left','padding-top','padding-right','padding-bottom','background','background-position', 'vertical-align'

如果想针对某个属性放弃使用rem变换,spon已实现黑名单机制,我们可以使用spon mb rem -b 'height border font-size line-height'命令,“height,border,font-size,line-height”几个属性就不会进行rem变换; 同理,如果有些css属性需要进行rem变换,但是spon默认并未针对该属性做rem变换,需要我们手动将这些属性加入白名单中,如spon mb rem -w "margin padding-top"; #### 另外,spon工程可能会有多个页面,而每个页面可能由于历史遗留问题并未采用rem布局,为了避免不可预知的变换问题,因此十分建议在page工程中,只针对单一工程进行rem变换,正如下面命令: spon mb rem -n 'abc',只针对abc页面的相关less做变换,安全有效。 最后,对于如下的css样式:

.abc { width: 750px; font-size: 16px; line-height: 16px; height: 50px; border: 1px solid red; margin: 10px 5px 5px 10px; padding-top: 20px; }

使用spon mb rem -n art-tmpl -w "margin padding-top" -b 'height border font-size line-height',就可以按照自定义设置完成转换,转换后的结果如下:

.abc { width: 10rem; font-size: 16px; line-height: 16px; height: 50px; border: 1px solid red; margin: 0.1333rem 0.0667rem 0.0667rem 0.1333rem; padding-top: 0.2667rem; }

最后的最后哦,在使用rem插件时,每当我们执行spon mb rem后会有交互,在此确认可能的后果,以免造成不必要的损失!!!!

13. pc端工具链打通

命令一览:

spon pc init (-c);

spon pc add;

spon pc build

spon pc dev -p 8888 -l 12334;

spon pc publish (-o);

spon pc upgrade;

CHANGELOG

  • v0.1.3 添加了版本号引用组件;

  • v0.1.4 增加模版渲染引擎,针对src/pages下的所有.tmpl文件进行预编译 可创建ui组件,并相对路径引用模块

  • v0.1.5 针对src下的less文件进行watcher,方便开发时调试样式

  • v0.1.6 针对尚未重构的showjoy-assets/portal 工程添加发布功能

  • v0.1.7 针对pages工程,添加了src/components中的模块引用线上组件的功能 内部实现了线上组件缓存功能

  • v0.1.8 针对fecomponent组件中的less,可以循环引用,即less中可通过@import递归加载

  • v0.1.9 完成部分重构,集成rem插件(待修改,做过渡使用,建议不要采用该版本的rem插件)

  • v0.1.10 丰富了rem插件,集成许多复杂功能

  • v0.1.11 修改了rem插件的小问题,并完美适配当前前端切图规范(在使用rem插件时,必须修改引用的flexibal.js,使用新的布局脚本)

  • v0.1.12(不要使用该版本,作为过渡) bug修复,task顺序重新调整

  • v0.1.13 bug修复

  • v0.1.14 pc端工具链打通,针对pc端的操作和mobile端对应

  • v0.2.0 spon彻底重构,添加插件选项,并且配置别名服务,另外,该版本下的发布publish操作默认取消了build选项,这意味着每次发布之前需要手动进行构建page工程,不要疏忽! 另外,spon插件规范及别名使用!!!

  • v0.2.1 添加相关依赖

  • v0.2.2 解决模块解析遗留问题(注释删除)

  • v0.2.3 解决js解析时的AST构建问题(注释模块)

  • v0.2.4 增加维护者“南洋”

  • v0.2.5 增加对指定页面进行build工程

  • v0.2.6 针对rem插件做了diff对比,目前仍在测试阶段,欢迎找bug 修改重构后的遗留问题,spon主目录创建问题

  • v0.2.7 1、添加js,less文件代码规范检查 2、更新新添加page时的初始html文件

  • v0.2.8 修改 eslint.json 配置文件,放宽规则限制

  • v0.2.9 添加 eslint的依赖

  • v0.2.10 lint规则放宽 sourceMap链接错误解决 spon commit(cmt)集成,规范化提交内容 spon性能优化,采用懒加载 tty输出信息优化