buijs 命令行工具

一、简介

buijs 是BUI 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规范版本.

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

$ buijs create 1.4.8 -t page-login

二、安装buijs命令行工具

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

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

npm install -g buijs

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

$ sudo npm install -g buijs

三、初始化工程目录:

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

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

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

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

$ buijs create -p sass
$ 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模板图片预览

四、接口跨域及配置

接口跨域

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

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

需要这样配置 proxy :

{
...
"proxy": {
    "/api": {
      "target": "http://www.easybui.com",  
      "changeOrigin":true  
    }
  }
...
}

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

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

服务器的配置说明

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

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

五、命令列表

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

buijs 命令列表

NPM 命令列表

六、命令示例

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

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

# 查看有什么模板
$ buijs list-template
# 进入当前工程 demo
$ cd demo
# 替换main模板
$ buijs create -t main-tab
# 新增login模板
$ buijs create -t page-login
# 新增一个新模块 apps 
$ buijs create -m apps
# 新增一个新子模块 apps/meeting 
$ buijs create -m apps/meeting

效果预览

注意:

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 工程示例.

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

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

$ buijs create -t sidebar -p dcloud

创建sass编译工程

$ buijs create -p sass

创建less编译工程

$ buijs create -p less

创建指定版本工程

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

buijs create v1.0

更新工程为最新bui版本

buijs update

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

buijs update -p bingotouch

创建多页工程

buijs update -p mpa

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

buijs update -d

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

buijs update -d node8
buijs update -d node8-sass
buijs update -d node10
buijs update -d node10-sass

创建新模块

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

buijs create -m article

七、目录说明:

单页应用包文件夹说明:

八、多个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 编译打包

# 创建 bui-projects 文件夹作为公共的bui应用目录
buijs create bui-projects
# 进入这个目录
cd bui-projects/
# 安装依赖
npm install
# 创建 project1 工程
buijs create project1
# 运行预览
npm run dev-project1
# 编译打包
npm run build-project1

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

九、更改数据源

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

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

十、创建完整案例参考

# 创建163案例
buijs create -t case-163

十一、创建皮肤

1. 创建主色皮肤

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

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

1. 创建深夜模式皮肤

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

# 先让你的文件支持sass
buijs create -p sass
# 创建一个深色皮肤
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 使用这个方法构建全局方法

```js
loader.global(function(global){
    // global: 为上次执行的依赖
    return {
        test: function(){
            console.log("test");
        },
        test2: function(){
            console.log("test2");
        }
    }
})
```

4.2. 推荐: 局部调用

```js
loader.define(function(require,export,module,global){
    // 调用test方法
    global.test();
})
```

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