HTML静态页面原型交付工具“魔卡”简介

“魔卡”这个项目虽然挂在我的github账号下,但是,在阅文内部已经跑了很多项目,作家线,腾讯视频阅读,部分内部系统等都是借助“魔卡”完成项目开发的,从17年到现在,已经迭代了很多,目前算是比较成熟的状态,因此是时候亮出来给大家看看了。

“魔卡”项目地址:https://github.com/zhangxinxu/mockup

二、“魔卡”诞生的背景

理想:大前端,工程化,前后端分离,模块化开发;
现实:大兄弟,你这是啥啊?我们只要HTML静态页面就好了,你这搞了一堆什么跟什么!

目前还有很多团队还是传统后端开发套页面方式。即使前端工程化开发成熟大厂也会有类似需求,例如,陈年老旧公司内部系统的开发,又例如,跨部门或者和异地团队协作时候,对方希望前端重构交付的就是高质量的HTML原型页面,此时什么自动化工具,前端模板等高科技都不需要,因为对接的开发这些玩不转,也懒得玩。

此时又要回到了痛苦的过去,例如:

  • 传统静态HTML页面头尾无法公用,20多个页面,如果公用头部变化了,一改该好多地方,累!
  • 类似Sass里面变量这么好用的东西就不支持了,万一所有的圆角从2px变成4px,替换都替换不了。
  • 有些交互效果需要有真实的Ajax请求。传统静态HTML默认只能使用file协议预览,Ajax请求就无法还原,需要安装和配置Apache或IIS模拟服务环境,这个很烦的,好不容易自己电脑装好了,结果使用会议电脑演示的时候又嗝屁了。产品和开发解压你的压缩包体验时候,异步加载全军覆没,页面效果凄凄惨惨。你说,大大,要装个环境。好吧,我装,大大结果一看安装教程,足足十几步,步步不能错,想当年结婚流程都没这么长,整个人就不好了,友尽。
  • 开发那边居然没有资源合并功能,前端只能把JS和CSS全部手动合在一起写,以后维护要看花眼咯。

矛盾就出现了:交接方希望得到的是干净的HTML原型,不是和前端工程化耦合在一起的HTML页面;而前端同学希望开发时候可以借助前端工程化,以快速便捷开发同时易于维护。

那有没有什么办法同时兼顾呢,处理好这种矛盾呢?

这样的痛点促使了“魔卡”的出现。免安装,直击静态页面开发痛点,提高开发效率降低维护成本。

二、“魔卡”简介

“魔卡”是个Node.js小工具,开启一些动态特性,帮助前端人员以超高质量超高效率完成高保真静态原型页面,纯原生,无任何安装包依赖,很轻量。

通常后端开发都是windows机器多,因此,还准备了run.bat文件,直接双击就可以跑。产品同学也可以玩,开发同学也可以玩。

相比工程化那套东西要简单很多,也没有乱七八糟npm package安装问题。

“魔卡”主要功能:

  • HTML import功能,头部和尾部可以公用啦

    头部尾部公用
  • 基于文件夹的CSS和JS资源合并策略

  • 支持CSS变量以及@import模块引入

    变量示意

    @import url(../_variable.css);

  • 本地http环境一键开启,post/get请求轻松模拟

Demo演示,基于“魔卡”生成的原型页面:index.html

三、如何使用?

  1. 下载项目zip包(含默认脚手架):master.zip

  2. 安装node.js

  3. 命令行node run。windows系统可以双击run.bat。

    魔卡项目运行示意

此时“魔卡”就开启了本地服务,http://127.0.0.1:2019/views/html/*.html 访问(127.0.0.1也可以替换成localhost)。这里2019是可变的,是基于当前年份设置的。

同时,全面监控HTML,CSS和JS资源。

模板目录结构:

./src -> HTML, JS, CSS资源开发目录
|--static
| |--css
| | |--common
| | | |--reset.css
| | | |--color.css
| | | |--layout.css
| | | |--animate.css
| | |--details
| | | |--home.css
| | | |--page1.css
| | | |--page2.css
| |--js
| | |--common
| | | |--lib
| | | | |--jquery.js
| | | |--header.js
| | |--home
| | | |--home.js
| | |--pages
| | | |--page1.js
| | | |--page2.js
|--views
| |--html
| | |--include
| | | |--meta.html
| | | |--header.html
| | | |--footer.html
| | |--index.html
| | |--page1.html
| | |--page2.html
./dist -> 预览和最终资源交付目录
|--static
| |--css
| | |--common.css
| | |--details.css
| |--js
| | |--lib
| | | |--jquery.js
| | |--common.js
| | |--home.js
| | |--pages.js
| |--images
| |--fonts
|--views
| |--html
| | |--index.html
| | |--page1.html
| | |--page2.html
| |--cgi
| | |--succ.json
| |--map.html -> 地图和项目进度页面

其中:

  • ./src 为开发目录,可以看到资源按照模块或者页面分得比较细

  • ./dist 为生成目录,原型预览,和静态资源交付都在这个文件夹下。相比./src目录,多了static/imagesstatic/fonts以及views/cgi文件夹,分别放置图片资源、字体资源和ajax请求页面。因为这些资源不参与node任务,因此,直接安排在./dist目录下,省去拷贝的成本。

  • ./dist/views/map.html 是项目页面地图以及项目进度完成视觉化页面,可以让Leader和项目组一看看出目前进度,访问地址(假设端口号是2019)是 http://localhost:2019/views/map.html 。效果图示意:

    页面地图交付截图

一些说明:

  • 上面文件目录结构中,./src中的css, js, html等目录名称和层级是不能调整的,否则会跑不起来。如果进行了修改,需要同步修改run.js相关路径。
  • css, js及其以下子目录,目前仅支持1级文件夹结构,名称可以任意,例如page1.js, page2.js都是示意用,您可以删除或者改成你需要的名称。

四、“魔卡”深入介绍

1. 关于CSS编译

支持简单的模块引入和CSS变量编译,具体如下:

@import功能

下面两种引入方法都是支持的:

@import '../_variable.css';
@import url('../_variable.css');

仅支持一层关系import,多层关系不支持,例如a import b, b import c,则a文件编译时候,c是不会嵌套进来的。

毕竟写静态页面原型,不需要太复杂的结构。

CSS变量

CSS变量采用原生的CSS语法,也就是--varname: value声明变量,然后var(--varname)使用变量,具体可参见“了解CSS/CSS3原生变量var”这篇文章。

但是,细节上有差异,包括:

  • 只支持:root{}html{}body{}中的CSS变量声明;
  • 不支持CSS变量嵌套声明;

另外,为了避免和原生需要的CSS变量冲突,建议在语句块中加上!;进行区分,本工具在编译时候会过滤这段声明。例如:

body {!;
    --borderRadius: 2px;
}

其他

文件名以_下划线开头的CSS文件不会参与编译与合并,只能被@import导入。

2. 关于合并

合并仅在CSS和JS文件中存在,“魔卡”采用基于文件夹的合并策略。

具体表现为:

  • ./src/static/js下所有1级文件夹中的JS会合并为和文件夹同命名的独立文件。例如,.src/static/js/pages文件夹下有page1.jspage2.js,当“魔卡”运行后,就会在./dist/static/js目录下合并成一个pages.js。但是,直接暴露在./src/static/js下的js文件是不参与合并,直接复制到./dist/static/js目录下。
    其中,有一个例外,那就是lib文件夹下的JS是不参与合并的,通常用来放置JS框架,例如jquery, zepto之类。
  • ./src/static/css下所有1级文件夹中的CSS会合并为和文件夹同命名的独立文件。例如,.src/static/js/details文件夹下有home.csspage1.csspage2.css,结果“魔卡”运行后通通合并成了details.css,在./dist/static/css目录下。同样的,直接直接暴露在./src/static/css下的css文件是不参与合并的。

合并不支持多级目录,个人经验,很少项目会用到超过2级的CSS, JS资源。于是就简单点,工具层面约束项目复杂度,使结构更加扁平。

3. 关于HTML编译

html文件支持模块导入,采用html5 import语法,例如:


“魔卡”会将"./include/header.html"这个文件内容直接引入进来,类似php中的include功能。

HTML编译支持简易查询

“魔卡”的HTML编译支持通过URL查询字符串向引入的模块传递参数,不过功能比较单一,就是替换,例如:


这里的nav2=active就会替换header.html中的$nav2$为字符'active'

header.html原始HTML为:

首页

页面1

页面2

HTML模块引入后就是:

首页

页面1

页面2

于是,当我们点击导航切换到“页面1”的时候会发现导航按钮一起跟着高亮了,就是上面nav2=active的作用,如下图:

导航与选中

替换细则如下:

替换所有前后都是$的字符单元,如果有匹配的查询关键字(如nav2),则替换为对应的值(如active);否则替换为空字符串''

因此,虽然概率较小,但依然有会将引入模块中正常的$$包含内容替换的风险。如果遇到该问题,可以修改run.js中的$字符为更为生僻字符,例如[图片上传失败...(image-c7e065-1563862386138)]

之类。

HTML编译的局限

目前“魔卡”仅支持直接暴露在./src/views/html目录下的.html文件的编译,子目录.html直接忽略。95%+项目无压力,如果项目真的很复杂,上百个原型页面,不能不文件夹分组,请参照run.js中的示意,自己动手,对这些文件夹调用complie()方法。

4. 关于本地服务

本地服务是一个用node.js写的简易服务,支持get/post等ajax请求模拟,和常规资源的加载和显示。

对于一些特殊格式资源,例如.conf,“魔卡”并未支持,需要自己在run.js中的mimetype对象中添加。

“魔卡”本地服务端口采用的是本地年份:

let port = new Date().getFullYear();

因此,访问地址以 http://localhost:2019 开始,这就有一个问题,因为年份是固定的,所以,“魔卡”默认是不支持同时开多个本地服务的,如果想要同时开多个服务,需要你修改run.js中的port端口值。

五、结束语

“魔卡”项目中默认有很多演示和测试用的静态资源,包括HTML页面和一些CSS脚手架和JS文件,实际开发的时候,这些资源大都没什么用,大家可以直接删掉或者按照项目内容重命名。

“魔卡”是一个写HTML静态页面非常实用的小工具,不过如果你的页面就是运营活动这种就1~2个页面的场景,则不太适合使用“魔卡”。直接简单粗暴一个完整HTML即可。

总之,如果你的主要工作内容就是重构HTML页面,则“魔卡”工具会很适合你。

你可能感兴趣的:(HTML静态页面原型交付工具“魔卡”简介)