slush-alloyteam-simple

Alloyteam Simple Web Apps generator base on slush & glup

Alloyteam web 前端项目工程化模板

特性

1. 基于 gulp 进行构建，方便快捷，易于定制和插件支持
2. 最小化需配置项 (project.js)，基于约定优于配置理念
3. 所有资源使用增量发布策略，文件名全部 md5 版本化，让产品轻松支持多版本并存
4. [css] 使用 compass 编写模块化、可维护 css
5. [css] 使用 compass 自动 sprite 生成精灵图，自动生成版本化图片 (无需修改时间戳)
6. [js] 支持多种模块化策略，使用 webpack 进行 cmd/amd 模块化打包
7. [js] 内置 handlebar 模板引擎支持，发布前编译
8. [html] 自动替换 html 内部资源引用路径，替换为 cdn/md5 版本化路径
9. [html] 轻松支持 js/css 资源内嵌到页面
10. [工程化集成] 生成资源（ak离线包、web资源），对接内部发布系统 jb.oa.com
11. [工程化集成] 通过 task 调用 jb.oa.com 提供 rest api 接口，轻松实现命令行部署测试环境、正式环境、离线包发布等

依赖

1. ruby & compass
2. nodejs
3. gulp & slush

安装

• 安装 ruby，参考 https://www.ruby-lang.org/en/installation/
• 建议安装 compass preview 版本

gem install compass -v 1.0.1

• 安装 nodejs，参考 http://nodejs.org/
• 安装 gulp slush slush-alloyteam-simple

npm install -g gulp slush slush-alloyteam-simple

• 创建项目目录

mkdir alloyteam-webapp
cd alloyteam-webapp

• 初始化项目

slush alloyteam-simple

• 按照提示填写项目初始化信息

项目名称，如：alloyteam-webapp
项目html路径，如：http://find.qq.com/qqun/search/
项目cdn路径，如：http://s.url.cn/qqun/qqfind/search/
子项目(可留空)，如：qiqi_1111

• [可选] 确定 jb.oa.com 是否有对应部署映射，多个子项目的映射可以公用，如各种运营活动，activity/qiqi_1111

项目路径 与 jb 映射对应关系
http://find.qq.com/qqun/search/  <=> /data/sites/find.qq.com/qqun/search/ 
http://s.url.cn/qqun/qqfind/search/  <=> /data/sites/cdn.qplus.com/qqun/search/

• 安装构建依赖

npm install

• 启动开发任务

gulp

• 启动正常发布编译任务

gulp dist

目录约定

• 根目录

./alloyteam-simple-app/
├── README.md
├── config.rb  -- sass 配置文件，不需修改
├── dist  -- 开发编译目录，开发时将资源替换到这里
├── gulpfile.js  -- gulp 构建文件，不需修改，版本升级，只需下载最新覆盖
├── livefile.js  -- liveproxy 配置文件，用于本地开发代理
├── node_modules
├── package.json
├── project.js -- 全局配置
├── src   -- 源代码目录
└── userdef.js  -- jb.oa.com 发布系统集成配置文件

• 源代码目录

./src
├── css  -- sass 样式目录，不需要编译生成 .css 文件的子模块，请使用 _ 开头
│   ├── common   -- 公共样式
│   │   ├── _level.scss  -- 自动 sprite 合并图片示范
│   │   ├── _reset.scss  -- reset css 公共模块
│   │   └── _ricons.scss  -- retina 高清 sprite 合并图片示范
│   ├── index  -- index 页面样式子模块，可以将 index 所需样式进行子模块划分，便于管理
│   │   └── _submodule.scss  -- 子模块，以下划线开头
│   │   └── index.scss  -- 合并所有 index 页面样式子模块，公共模块，合图...
├── favicon.ico
├── img  -- 图片目录
│   ├── common  -- 不需合图的图片，文件会自动在文件名加上md5，filename-md5.png
│   │   ├── banner.png  -- 自动生成 banner-be70f3b1.png
│   ├── sprite  -- 需要合图的图片，安装生成 sprite 图片名进行目录划分，可以自己新建子目录
│   │   ├── icons  -- 普清图，最终合并生成 icons-sbb41937c32.png
│   │   ├── icons@2x -- 2x高清图，生成 [email protected]
│   │   └── level -- 普清图，生成 level-s99b1a493c7.png
│   └── static  -- 不需合图的图片，不需自动md5重命名的图片
│       ├── static-img-url.png
├── index.html  -- 首页
├── js  -- js 目录，使用 cmd require 规范进行模块之间应用
│   ├── common -- 公共模块
│   │   ├── config.js
│   │   └── global.js
│   ├── index  -- 首页 js 模块
│   │   └── index.js
│   └── libs  -- 第三方 js 库，会被复制到 dist 目录，js/css 文件名 md5 化
│       └── jquery
├── libs  -- 第三方库，libs 所有文件会被复制到 dist 目录，js/css 文件名 md5 化
│   └── bootstrap
│       ├── bootstrap.css
│       └── bootstrap.js
└── tpl  -- handlebar 模板文件
    ├── common  -- 公共模板页面片
    │   ├── footer.hbs
    │   └── header.hbs
    └── index  -- 首页模板
        └── list.hbs

如何新建一个页面，如下：mypage 为需要创建的页面名称

slush alloyteam-simple:page mypage

将会生成如下目录和文件

./src
├── mypage.html 
├── css
│   ├── mypage
│   │   └── _index.scss
│   └── mypage.scss
├── js
│   ├── mypage
│   │   └── index.js
├── tpl
│   ├── mypage
│   │   └── index.hbs

修改 project.js 中的 webpack entry 项目，添加对应的 js 编译项

entry: {
    index: './src/js/index/index.js',
    mypage: './src/js/mypage/index.js'
},

如何新建一个 sprite 自动合图，如下：mysprite 为需要创建的 sprite 名称

# 生成精灵图，方式一：自动生成合图样式，参考下面【关于 css】说明
slush alloyteam-simple:autosprite mysprite
# 生成精灵图，方式二：使用 include 引用合图样式
slush alloyteam-simple:sprite mysprite
# 生成高清精灵图
slush alloyteam-simple:retina mysprite

将会生成如下目录和文件

./src
├── css
│   ├── common
│   │   └── _mysprite.scss
├── img
│   ├── mysprite

project.js 配置说明

待续

livefile.js 配置说明

待续

userdef.js 配置说明

待续

如何开始编码

启动开发命令

gulp dev

关于 css

• 使用 sass 进行 css 编写，有利于模块化，可复用
• 利用 compass 提供了便捷的自动合图，只支持 png

如何进行自动合图，方式一：自动生成合图样式

• 在 src/img/sprite 下新建目录，名称为 sprite 名称，如QQ等级，level
• 将需要合图的图片放到 img/sprite/level 下，如 search.png 和 webqq.png
• 在 src/css/common 下新建文件，_level.scss (ps: 将文件内容中 level 替换为自己的 sprite 名称)

$level-layout:smart;
@import"sprite/level/*.png";
@include all-level-sprites;

上面的代码将自动生成如下代码

.level-search, .level-sprite, .level-webqq {
    background-image: url(../img/sprite/level-s99b1a493c7.png);
    background-repeat: no-repeat
}
.level-search {
    background-position: 0 0
}
.level-webqq {
    background-position: 0 -24px
}

• 将对应的 css 样式规则加在 html 页面或 hbs 模板中

<span class='level-search'></span>

如何进行自动合图，方式二：使用 include 引用合图样式

• 在 src/img/sprite 下新建目录，名称为 sprite 名称，如QQ等级，level
• 将需要合图的图片放到 img/sprite/level 下，如 search.png 和 webqq.png
• 在 src/css/common 下新建文件，_level.scss (ps: 将文件内容中 level 替换为自己的 sprite 名称)

$level-layout:smart;
@import"sprite/level/*.png";

• 在需要引用小图标的地方，使用 @include {合图名称}-sprite("图标名称") 的方式引用

@import"common/level";
.hello {
    &:before {
        @include level-sprite("search");
    }
}

上面的代码将自动生成如下代码

.hello:before {
    background-image: url(../img/sprite/level-s99b1a493c7.png);
    background-repeat: no-repeat
}
.hello:before {
    background-position: 0 0
}

如何让合图支持 retina 高清屏

• 大致过程参考上文 【如何进行自动合图，方式二】
• 在 src/img/sprite 下新建目录，名称为 sprite 名称，如QQ等级，level
• 分别在 src/img/sprite/level，src/img/sprite/level@2x 下面放普通图标和2x高清图
• 在 src/css/common 下新建文件，_level.scss (ps: 将文件内容中 level 替换为自己的 sprite 名称)

$level:sprite-map("sprite/level/*.png", $layout:smart);
$level-2x:sprite-map("sprite/level@2x/*.png", $layout:smart);
@mixin level-sprite-retina($sprite) {
    background-image: sprite-url($level);
    background-position: sprite-position($level, $sprite);
    background-repeat: no-repeat;
    overflow: hidden;
    display: block;
    height: image-height(sprite-file($level, $sprite));
    width: image-width(sprite-file($level, $sprite));
    @media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
        background-image: sprite-url($level-2x);
        background-size: (image-width(sprite-path($level-2x)) / 2) (image-height(sprite-path($level-2x)) / 2);
        background-position: round(nth(sprite-position($level-2x, $sprite), 1) / 2) round(nth(sprite-position($level-2x, $sprite), 2) / 2);
        height: image-height(sprite-file($level-2x, $sprite)) / 2;
        width: image-width(sprite-file($level-2x, $sprite)) / 2;
    }
}

• 在需要引用小图标的地方，使用 @include {合图名称}-retina-sprite("图标名称") 的方式引用

@import"common/level";
.hello {
    &:before {
        @include level-sprite-retina("search");
    }
}

如何将图片资源内嵌到 css 中，使用 inline-image 方法

.hello {
    background-image: inline-image("banner");
}

关于 js

• 在 html 中添加 js 引用

# 先在 project.js 中 webpack.entry 里面添加 js 引用入口
webpack: {
    // 页面所引用 js 配置
    entry: {
        // 格式=> [js名字]: '入口路径'
        index: './src/js/index/index.js'
    }
}
# 在 html 中引用 <script src='js/[js名字].js'></script>
<script src="js/index.js"></script>

• 利用 webpack 进行 cmd 模块打包
• 在 js 中直接使用 require 即可，全部使用相对路径

// ./src/js/index/index.js
require('../common/global.js');
require('../common/config.js');
console.log('index is loaded');

• 在 js 中引用 handlebar 模板文件

// ./src/js/index/index.js
var listTpl = require('../../tpl/index/list.hbs');
var data = {
    body: 'this is body',
    title: 'hi title'
};
var dom = listTpl(data);

• 在 js 中引用 src/img/common 下图片

var banner = require('../../img/common/banner.png');
// will change to: "http://s.url.cn/qqun/img/common/banner-be70f3b1.png"

• 在 js 中引用 src/img/static 下图片

var staticImg = require('../../img/static/static-img-url.png');
// will change to: "http://s.url.cn/qqun/img/static/static-img-url.png"

• 在 js 中引用第三方库，如 jQuery 修改 project.js 配置，在 webpack 配置中添加 jQuery: "jQuery" (window.jQuery 可访问，其他库类似)

externals: {
    jQuery: "jQuery"
}

在 js 中直接添加引用

var jQuery = require('jQuery');

在 html 中添加 jquery 引用

<script src="js/libs/jquery/jquery.js"></script>

• 独立打包公共库，共享代码，避免不同页面 js 重复打包 修改 project.js 配置，添加公共库入口 common

entry: {
    commons: './src/js/common/index.js',
    index: './src/js/index/index.js',
    mypage: './src/js/mypage/index.js'
},

在 common/index.js 中暴露一个全局变量 window.commons

// src/js/common/index.js
window.commons = {
    sub1: require('./sub1.js'),
    sub2: require('./sub2.js')
};

按照第三方类库的方式，引入 commons

externals: {
    commons: "commons"
}

在 js 中直接添加引用

var commons = require('commons');

在 html 中添加 commons 引用

<script src="js/commons.js"></script>
<script src="js/mypage.js"></script>

• 异步远程加载 js

// aync loading files
require(['./submod1.js', './submod2.js'], function(submod1, submod2) {
    console.log('submod loaded');
});

关于 handlebar 模板文件

• 语法参考: http://handlebarsjs.com/
• https://github.com/altano/handlebars-loader

关于 html 文件

使用 gulp-htmlrefs 对 html 进行路径替换和内嵌

• 引用 css 文件

<link rel="stylesheet" href="css/index.css">

将被替换为 cdn+md5 文件格式，如

<link rel="stylesheet" href="http://s.url.cn/qqfind/css/index-2e3a4b5c.css">

• 引用 js 文件

<script src="js/index.js"></script>

将被替换为 cdn+md5 文件格式，如

<script src="http://s.url.cn/qqfind/js/index-2e3a4b5c.js"></script>

• gulp-htmlrefs 默认会自动扫描 link/scirpt/img 三种标签并自动替换
• 需要额外替换 video/source/data-main/meta/a/input 等标签，需要插入额外标签

<!-- build:htmlrefs -->
<meta ....>
<!-- endbuild -->

• 将 js/css 内嵌到 html 中

<script src="js/index.js?__inline"></script>

关于 liveproxy 开发代理

启动开发任务后，将自动启动一个开发代理，支持如下特性：

• 本地替换
• cgi 模拟
• 脚本注入
• host 配置
• 正向透明代理远程资源（本地不存在的文件）
• 自动刷新页面 livereload
• 远程调试控制台 jsconsole 详细参考：https://github.com/rehorn/liveproxy

使用 liveproxy 进行本地替换开发

• 将浏览器代理或者系统代理配置为 127.0.0.1:8090 (端口可在 livefile.js 修改)
• 将 localhost;127.0.0.1 配置不使用代理
• 在浏览器中打开业务页面，如 http://find.qq.com/index.html
• 编辑 src 下代码，直接浏览器查看最新页面
• 编辑 livefile.js 里面 mocker 配置，进行cgi本地模拟

使用 liveproxy 进行移动端远程调试

• 将手机网络代理设置为 127.0.0.1:8090
• 在 pc 浏览器中打开调试控制台页面 http://localhost:8091 (端口可在 livefile.js 修改)
• 在手机浏览器或者webview中打开页面
• 手机页面日志将自动输出 pc 端控制台中

腾讯内部发布平台 jb.oa.com 整合

• 配置单号

# project.js
distId: 'R000012'

• 部署到测试环境

gulp test

提交一个ars发布单

gulp ars

提交一个离线包发布

gulp ak