buijs 命令行工具

描述修改日期
新增update命令,修复update平台时,会覆盖index.html,index.js问题2018-2-1
新增NPM开发模式,修改了目录规范,修复无网络无法创建问题2018-3-25
新增buijs update -d 更新工程gulpfile.js package.json app.json2018-4-12
修复buijs create 不能在同个工程下创建子工程2018-5-30
新增对相同模板目录的检测,避免重复覆盖2018-8-01
修复输入版本号前必须输入工程名2018-10-31
新增多工程共享 node_modules目录2018-12-07
新增创建新模块命令 buijs create -m 模块名2019-01-22
新增更改数据源命令, 默认是 github. buijs create -f gitee2019-03-20
完善创建新模块命令,需要结合最新的 buijs 及 bui-template 使用2019-08-26
新增对工程的node不同版本的区分2020-04-01
更新默认的源为 gitee 国内会快很多2020-04-13

一、简介

buijsBUI Webapp交互框架 的cli命令工具, 用于快速生成指定平台与模板最新的工程文件.

通过命令行构建,有以下好处:

  1. 自动获取最新的BUI模板工程;
  2. 可以指定bui对应的平台版本;
  3. 可以指定bui的单页模板. BUI模板图片预览 ;
  4. 拥有服务器并支持接口跨域调试;
  5. 自动编译压缩混淆文件,便于打包部署的安全;
  6. 支持ES6编译;
  7. 支持sass编译;
  8. 支持less编译;
  9. 减少对工具的依赖

重要更新 1.4.8 包含之前的版本是基于540设计稿规范, 新版1.5.0是基于750设计稿规范, 所以两个版本的使用方式及表现都是不同的, 旧工程不建议升级. 默认未指定版本, 都是基于1.5.0创建的750规范. 模板也是750. 如果旧项目想使用模板名, 需要先重新安装buijs, 在创建前加上 1.4.8 最新540规范版本.

旧项目使用指定版本模板示例:

  1. $ buijs create 1.4.8 -t page-login

二、安装buijs命令行工具

需要先安装 node环境 才能使用npm命令. 如果下载缓慢,建议先安装淘宝的npm镜像, 把以下命令的npm换成cnpm;

windows: 需要右键使用管理员打开终端或者安装 powershell.

  1. npm install -g buijs

mac: 打开终端, 需要权限,加上sudo,还要输入密码回车确认

  1. $ sudo npm install -g buijs

三、初始化工程目录:

buijs 创建工程预览

3.1 创建默认Webapp工程, 新版的buijs会针对不同的node版本,创建不同的工程,但是默认不会主动创建sass的编译支持.

  1. # * 创建webapp工程 (demo 为工程名称, 如果没有,则在当前目录)
  2. $ buijs create demo
  3. # * 进入工程目录
  4. $ cd demo
  5. # * 安装依赖
  6. $ npm install
  7. # * 自动打开浏览器并监听js,scss,html等文件的修改
  8. $ npm run dev
  9. # 非必须命令,编译工程,生成dist目录,压缩脚本,样式,图片,用于发布打包的安全, 会清空之前目录,重新根据`src`目录生成. 另外, es6 的模块化 import ,Objece.assign 等方法不要使用, 会导致编译后在部分手机无法运行
  10. $ npm run build

3.1.1 如果需要工程对sass或者less支持

在刚刚创建的demo工程里面再次执行以下命令

  1. $ buijs create -p sass
  2. $ buijs create -p less

注意: npm run dev使用这个命令, 样式的修改都需要在 src/scss/style.scss 文件. 如果直接修改src/css/style.css,需要删除src/scss目录,避免style.css被覆盖.

安装时, 如果报 sass 错误, 请先执行 npm remove node-sass 然后再安装依赖.

如 github 下载缓慢, 可以使用新的命令 buijs create -f gitee 使用码云的下载源. buijs 需要更新到 0.6.6 以上才有.

3.2 自动打开默认浏览器, 修改src 目录的相同文件,就会生成对应的dist文件,用于预览.

http://localhost:port

port端口自动生成, 一个端口对应一个工程, 如需更改同样是在app.json 配置.

3.3 工程模板预览

默认模板预览 更多模板点击这里 BUI模板图片预览

buijs cli工具 - 图2

四、接口跨域及配置

接口跨域

打开根目录下的 app.json ,里面有个 proxy 的对象, key值为接口的目录名, target 为域名的host.

假设请求的接口地址为: http://www.easybui.com/api/getDetail/id/123

需要这样配置 proxy :

  1. {
  2. ...
  3. "proxy": {
  4. "/api": {
  5. "target": "http://www.easybui.com",
  6. "changeOrigin":true
  7. }
  8. }
  9. ...
  10. }

js: 脚本请求使用相对路径, 为了后面更改为正式地址, 建议可以把url部分作为配置项.

  1. var apiUrl = "";
  2. bui.ajax({
  3. url: apiUrl+ "api/getDetail/id/123"
  4. }).then(function(res){
  5. })

服务器的配置说明

打开根目录下的 `app.json ,里面有个 devServer 的对象.

  1. {
  2. "distServer": {
  3. "root": "dist", // 编译的目录
  4. "livereload": true, // 修改自动刷新
  5. "port": 2149 // 端口号,默认第一次随机自动生成
  6. }
  7. }

五、命令列表

注意: 中括号为可选,如果没有采用默认

buijs 命令列表

命令行描述
buijs -v查看当前工具的版本
buijs -h命令帮助信息
buijs create在当前目录创建bui webapp默认工程
buijs create [projectName] [version] [-t templateName] [-p platformName] [-m moduleName] [-f from]创建工程,支持指定版本,指定模板,指定平台,相同目录下会覆盖
buijs update在当前项目更新 bui为最新webapp版本,只修改bui.css,bui.js不覆盖项目其它内容
buijs update [projectName] [version] [-p platformName] [-d dev] [-f from]更新bui为某个版本,某个平台, -d 更新为最新的工程模式(dev)
buijs list显示可用的版本
buijs list-template显示可用的模板列表 BUI模板图片预览
buijs list-platform显示可用的平台列表
buijs clear清除下载的模板缓存
buijs create -m 模块名 创建新的模块 m = module
buijs create -f 数据源 创建工程来自 gitee 或者 github , 默认是 github f = from

NPM 命令列表

命令行描述
npm run build编译成可以打包的文件,默认服务器根路径是”dist”,所以需要先编译
npm run dev启动服务并打开默认浏览器,支持接口跨域, 并且会自动监听脚本,scss文件,html文件的修改编译
npm run server启动默认8000端口的服务,并且默认支持了接口跨域,需要在app.json配置对应的接口地址

六、命令示例

创建某个模板工程 ( main-tab 为模板名称)

可以先查看有什么模板 buijs list-template, BUI模板图片预览

  1. # 查看有什么模板
  2. $ buijs list-template
  3. # 进入当前工程 demo
  4. $ cd demo
  5. # 替换main模板
  6. $ buijs create -t main-tab
  7. # 新增login模板
  8. $ buijs create -t page-login
  9. # 新增一个新模块 apps
  10. $ buijs create -m apps
  11. # 新增一个新子模块 apps/meeting
  12. $ buijs create -m apps/meeting

效果预览
buijs cli工具 - 图3

注意:

  1. 同一个工程可以多次创建模板; 模板名以 main-开头 会覆盖 main 模块, 例如: 模板名 main-tab 预览地址 index.html 模板名以 page-开头 会新增页面, 例如: 模板名 page-login 预览地址 index.html#pages/login/login;
  2. main-开头的模板会覆盖main页面, page-开头的模板是新增页面;
  3. 同一个工程只能创建一个平台, 多次创建会相互覆盖;

创建指定平台工程 ( dcloud 为平台名称 )

可以先查看有什么平台选择 buijs list-platform

注意:

  1. 目前已经支持以下打包平台 cordova,bingotouch,dcloud,apicloud,appcan,微信 等;
  2. 不同平台对应的文件会有些许不同, 绑定原生后退的方法也不同, 不指定平台时, 默认是webapp平台, 可以在微信及webkit浏览器内核预览.

以下内容都是以进入 demo 工程示例.

  1. # 创建Dcloud平台的应用
  2. $ buijs create -p dcloud

创建dcloud平台下的某个模板工程

  1. $ buijs create -t sidebar -p dcloud

创建sass编译工程

  1. $ buijs create -p sass

创建less编译工程

  1. $ buijs create -p less

创建指定版本工程

可以先查看有什么版本 buijs list

  1. buijs create v1.0

更新工程为最新bui版本

  1. buijs update

更新工程为最新bui版本及平台

  1. buijs update -p bingotouch

创建多页工程

  1. buijs update -p mpa

更新工程为最新npm开发模式 node10以上使用以下方式更新

  1. buijs update -d

也可以指定更新对应的node版本

  1. buijs update -d node8
  2. buijs update -d node8-sass
  3. buijs update -d node10
  4. buijs update -d node10-sass

创建新模块

模块的访问路径: 默认: index.html#pages/article/index

  1. buijs create -m article

七、目录说明:

单页应用包文件夹说明:

路径描述
gulpfile.js入口文件
package.jsonnpm依赖配置文件
app.json入口文件
dist/编译打包最终要部署的目录
src/index.html入口文件
src/index.js入口的脚本
src/css/bui.cssBUI库的样式文件
src/css/style.css当前应用的样式文件
src/font/字体图标目录
src/images/应用图片目录
src/scss/样式源文件,样式最好放这里可以分模块管理
src/js/zepto.jsbui的依赖库
src/js/plugins/fastclick.js移动端快速点击的插件
src/js/bui.jsBUI交互控件库
src/pages/模块目录
src/pages/main默认 main 模块
src/pages/main/main.html默认 main 模块模板
src/pages/main/main.js默认 main 模块定义脚本

八、多个bui工程共享node_modules模块目录

现在每次创建一个工程以后, 每次都需要执行 npm install 特别的繁琐, 通过以下步骤, 可以创建一个bui的相关工程共享 node_modules

  1. 升级buijs 0.5.3
  2. 创建bui工程目录, 作为所有工程目录 buijs create bui-projects, 删除 src目录,app.json ,只保留 package.json, gulpfile.js
  3. cd bui-projects 进入目录
  4. npm install 安装依赖模块
  5. buijs create project1 创建带工程名的工程
  6. npm run dev-project1 运行服务预览 或者 npm run build-project1 编译打包
  1. # 创建 bui-projects 文件夹作为公共的bui应用目录
  2. buijs create bui-projects
  3. # 进入这个目录
  4. cd bui-projects/
  5. # 安装依赖
  6. npm install
  7. # 创建 project1 工程
  8. buijs create project1
  9. # 运行预览
  10. npm run dev-project1
  11. # 编译打包
  12. npm run build-project1

project1/gulpfile.js, project1/package.json 这两个文件则不需要了

九、更改数据源

国内部分地区创建工程时,个别反应,创建的过程过于缓慢. 现在我们新增一个命令用于指定数据源, 默认是在 github, 你可以通过 -f 命令,更改到 gitee

  1. # 从 gitee 的最新版本创建默认工程.
  2. buijs create -f gitee
  3. buijs create -f github
  4. # 创建一次以后,在没有新版本的时候, 创建其它模板, 无需再加入这个 `-f` from命令.
  5. buijs create -t main-tab

十、创建完整案例参考

  1. # 创建163案例
  2. buijs create -t case-163

十一、创建皮肤

  1. 创建主色皮肤

npm run dev 主色皮肤运行以后就会覆盖掉 原本的色系

  1. # 先让你的文件支持sass
  2. buijs create -p sass
  3. # 创建一个红色皮肤, 在__variables.scss 文件里面通过 $main-color 修改为其它主色调, 会把头部等样式替换
  4. buijs create -p skin
  1. 创建深夜模式皮肤

深色皮肤跟主色皮肤的区别在于很多配色是相反的, 一般不需要修改, 运行以后,会在 css/bui-skindeep.css 生成样式文件,需要在 index.html 主动引入或者通过脚本控制切换.

  1. # 先让你的文件支持sass
  2. buijs create -p sass
  3. # 创建一个深色皮肤
  4. buijs create -p skindeep

十二、疑难问题

  1. 保存代码不会自动更新?

答:工程有使用 npm run dev 以后,会默认支持热更新, 工程只能在英文名路径下.

  1. 找不到全局变量?

答: 在node10以上创建的新工程, 默认对es6编译更加友好, 但当执行了 npm run build命令以后, 这个编译把脚本变成了闭包, 工程原本的全局变量, 变成了局部变量, 公共脚本用var声明的全局变量都无法找到. 有4种解决办法,

  1. 最简单的方法是使用 window.xxx 来替代公共方法的 var 声明.
  2. 一开始就使用 loader.define 定义这个模块, 然后在每个模块需要用的时候引入, 这样就不会有这个问题了.
  3. 把文件命名为 xxx.min.js 就会跳过编译. 但这样就要求里面不能有es6的写法, 因为打包以后对es6支持不好.
  4. 1.6.2 新增了一个新的定义方式, 比较推荐.

4.1. common.js 使用这个方法构建全局方法

  1. ```js
  2. loader.global(function(global){
  3. // global: 为上次执行的依赖
  4. return {
  5. test: function(){
  6. console.log("test");
  7. },
  8. test2: function(){
  9. console.log("test2");
  10. }
  11. }
  12. })
  13. ```

4.2. 推荐: 局部调用

  1. ```js
  2. loader.define(function(require,export,module,global){
  3. // 调用test方法
  4. global.test();
  5. })
  6. ```

4.3 全局调用: loader.globals.test();