BUI 规范文档

修订者 描述 修改日期
王伟深 整理规范 2018-01-02

目录

目录规范

BUI 单页示例目录说明

以上图片是路由示例的目录,创建的开发工程目录是纯净的, 在 demo/pages/下,只有入口 main 模块.
点击这里下载单页开发示例工程?

目录说明:

目录名 描述 是否必须
index.html 应用首页入口文件
index.js 路由的初始化脚本及全局事件
css/ 应用样式及bui.css样式
font/ bui.css用到的字体图标
images/ 应用图片目录
js/ 应用脚本
js/zepto.js bui.js默认依赖于zepto.js 或 jquery
js/bui.js BUI交互控件库
js/plugins/ 应用插件目录
js/plugins/fastclick.js 移动端快速点击插件
pages/ 应用的模块
pages/main/ 默认路由初始化以后会先载入这个main模块
pages/main/main.html main模块的模板
pages/main/main.js main模块的业务脚本

制作规范

步骤一览

  1. 按源稿大小切图
  2. 把设计稿转换成540px的宽度
  3. 量取大小除以100,转换单位为rem, 比如: 量取页面的元素的大小,宽100px,高360px ,得到的值除以100, 那么写成 width:1rem;height:3.6rem;

步骤分解

1. 按源稿大小切图

1.1 打开PSD源稿
1.2 选中图片,导出为PNG格式, ( 这里用到一个 cutterman PS插件;
1.3 把图片放到BUI开发包的 images 目录下;

images目录里面可以自行规划,例如:icons,banner等;

演示:
切图

2. 把设计稿转换成540px的宽度

BUI独创的基于REM适配手机,保持跟原生DPI一致的缩放效果, 需要把设计稿转换为540的设计稿,这样量取到的值,直接除以100,便是rem值.

把设计稿更改为540px宽度,高度等比缩放的设计稿

修改设计稿为540宽度

3. 量取设计稿内容的大小/100, 转成rem单位

转换尺寸为rem单位

说明:
如果希望slide的高度随着移动设备的不同比例缩放,需要转换成rem单位, 比方,你量取到的宽度是540px,高度是270px的焦点图, 那么写成 2.7rem = 270px/100 ; 这样页面的slide,就会根据手机的分辨率不同,自动更改为等比的焦点图.

.slide { width:100%;height:2.7rem; } 

开发规范

1. 页面结构规范

一个标准的结构包含, .bui-page 子集分别是 header, main, footer 等标签, main 标签必须有, 因为页面初始化的时候会自动撑开main的高度. 快速书写 ui-page Tab

<div class="bui-page">
    <header class="bui-bar">
        <div class="bui-bar-left">
            <!-- 左边有图标示例 -->
            <div class="bui-btn"><i class="icon-back"></i></div>
        </div>
        <div class="bui-bar-main">BUI开发工程模板</div>
        <div class="bui-bar-right">
            <!-- 右边有图标示例 -->
            <div class="bui-btn"><i class="icon-search"></i></div>
        </div>
    </header>
    <main>
        <!-- 中间内容 -->
    </main>
    <footer>
        <!-- 底部内容 -->
    </footer>
</div>

2. 命名与结构规范

  • bui-box, bui-fluid, bui-btn, span1 - span12, icon-, 是全局定义的关键字,不要使用上面的名称开头,可能导致你的样式多了很多东西
  • 业务中新增的样式无需以bui开头命名
  • 结构使用 控件名+中横杆+位置 命名 head main foot left right cell wrap

上下结构 示例 : 滑动控件
快速书写: ui-slide Tab

  <div class="bui-slide">
      <div class="bui-slide-head">
      </div>
      <div class="bui-slide-main">
      </div>
  </div>

上中下结构 示例 : 滚动加载控件
快速书写: ui-scroll Tab

  <div class="bui-scroll">
    <div class="bui-scroll-head"></div>
    <div class="bui-scroll-main"></div>
    <div class="bui-scroll-foot"></div>
  </div>

左中右结构 示例 : bar
快速书写: ui-bar Tab
  <div class="bui-bar">
      <div class="bui-bar-left">
      </div>
      <div class="bui-bar-main"></div>
      <div class="bui-bar-right">
      </div>
  </div>

控件的重复子元素使用 -cell 示例 : 步骤条
快速书写: ui-rating Tab
  <div class="bui-rating">
    <div class="bui-rating-cell"></div>
  </div>

控件名父层在控件名后面加上 -wrap 示例 : 侧边栏
快速书写: ui-sidebar Tab
  <div class="bui-sidebar-wrap">
    <div id="sidebar" class="bui-sidebar">
      侧滑菜单
    </div>
    <div class="bui-page">
      页面正文
    </div>
  </div>

3. 样式规范

3.1 样式书写注意事项

  • active 是控件的公共样式,请通过父层的方式定义 .bui-nav .active{} ,不要直接 .active {} ;
  • BUI的样式单位都需要以 rem 为单位, 也就是量到的px除以100 就能转换成rem, 除了1px 不做转换;
    注意: .bui-nav .active{} 也会修改到使用bui-nav的其它控件, 所以如果跟业务相关,请直接加上自己的业务样式进行修改;

3.2 BUI常用样式

3.2.1 布局

布局 子元素 描述
bui-box span1 - span12 弹性布局
bui-box-space span1 - span12 留白弹性布局
bui-box-vertical span1 - span12 垂直方向
bui-box-reverse span1 - span12 反序排列
bui-fluid span1 - span12 流式布局
bui-box-space span1 - span12 留白流式布局
bui-left 左浮动
bui-right 右浮动
bui-clear 清除浮动

3.2.2 布局对齐方式

布局 子元素 描述
bui-box-center div 块元素水平垂直居中
bui-box-align-center div 水平居中
bui-box-align-left div 居左对齐
bui-box-align-right div 居右对齐
bui-box-align-middle div 垂直居中对齐
bui-box-align-top div 顶部对齐
bui-box-align-bottom div 底部对齐
bui-box-align-justify div 两端对齐
bui-box-align-stretch div 高度拉伸对齐

3.2.3 全局样式-常用类

样式名 描述
container-x 左右间隙
container-y 上下间隙
container-xy 上下左右间隙
active 按钮高亮颜色
clearactive 清除按钮高亮
inline 内联元素
round 圆角
noround 没有圆角
ring
large 加大高度
xlarge 超大高度
bui-reset 按钮样式重置
bui-show 显示块元素
bui-hide 隐藏块元素

3.2.4 全局样式-颜色类

样式名 描述
default 默认颜色
primary 页面主颜色
success 一般是绿色
warning 一般是橘红色
danger 列表的分组标题

3.2.5 全局样式-标题类

样式名 描述
page-title 页面标题
title 文章标题
subtitle 文章子标题
section-title 章节标题,常用于页面的模块划分
bui-btn-title 列表的分组标题
item-title 列表的多行标题
item-text 列表的多行内容

3.2.6 全局样式-文本类

样式名 描述
bui-align-left 文本左对齐
bui-align-right 文本右对齐
bui-align-center 文本居中对齐
bui-text-show 文本显示
bui-text-hide 文本超出点点点
bui-box-text-hide 文本多行点点点
bui-text-clip 文本超出截断

3.2.7 全局样式-箭头类

样式名 描述
bui-arrow-left 左边箭头
bui-arrow-right 右边箭头
bui-arrow-up 顶部箭头
bui-arrow-down 底部箭头

4. 控件初始化

如何安装使用BUI Fast插件快速书写?

4.1 书写控件的结构
已安装BUI Fast 插件的SublimeText用户,在html里面直接输入 ui-accordion, 按Tab键 则可以生成以下结构.

<!--控件结构html-->
<dl class="bui-accordion">
  <dt class="bui-btn">菜单</dt>
  <dd>内容</dd>
</dl>

4.2 书写控件的初始化实例
已安装BUI Fast 插件的SublimeText用户, 输入 bui- + 控件名,按Tab键可以生成以下结构
BUI Fast 书写示例: bui-accordion ;

// 初始化JS
var uiAccordion = bui.accordion({
      id:"#accordion"
    });

4.3 调用控件实例的方法
已安装BUI Fast 插件的SublimeText用户, 输入 bui- + 控件名 + -方法名,按Tab键可以生成以下结构
BUI Fast 书写示例: bui-accordion-show ;

// 显示折叠菜单
uiAccordion.show(0)

4.4 控件初始化的完整demo ( 1.3.1 新增 )
已安装BUI Fast 插件的SublimeText用户, 输入 bui- + 控件名 + -demo,按Tab键可以生成以下结构
BUI Fast 书写示例: bui-list-demo ;

// 列表控件 js 初始化: 

var uiList = bui.list({
  id: "#uiList",
  url: "",
  data: {},             // 数据请求带过去的参数,分页在field配置
  template: listTemplate,
  field: {
      page: "page",     // 分页参数名
      size: "pageSize", // 分页大小参数名
      data: ""          // 数据字段名
  }
});
// 列表模板
function listTemplate (data) {
  var html = "";
  $.each(data,function(index, el) {
      html += '<li class="bui-btn" href="index.html"><i class="icon-facefill"></i>'+el.name+'</li>';
  });

  return html;
}

// 列表控件 html 对应的结构: 

<div id="uiList" class="bui-scroll">
  <div class="bui-scroll-head"></div>
  <div class="bui-scroll-main">
      <ul class="bui-list">
      </ul>
  </div>
  <div class="bui-scroll-foot"></div>
</div>

5. 模块化规范

5.1 一个js 文件里面只能有一个 loader.define 的匿名模块;
5.2 业务逻辑需要在 loader.define 里面,防止加载其它模块的时候冲突;
5.3 避免循环依赖 A ->依赖 B 模块, 而 B模块 -> A模块, 这就造成循环依赖,一般需要避免这种设计,如果一定要用, 不使用依赖前置的方式;
5.4 避免循环嵌套, 在loader.define 里面 又 require 加载当前模块, 这个时候还没实例化,就会造成死循环;
5.5 每个页面的ID不能相同;

6. 事件规范

事件分为全局事件,及控件事件,

全局事件: 指页面加载的时候,就会触发的事件;
控件事件: 在控件初始化以后才会存在;

6.1 全局事件

页面初始化加载事件

  • pagebefore (dom 初始化完毕, BUI 及 原生方法未初始化)
  • pageinit (dom 及 BUI 初始化完毕, 原生方法未初始化 )
  • pageready (dom 及 BUI 及原生方法 初始化完毕 )
  • onload (dom 及 BUI 及原生方法 及 图片js资源 都初始化完毕 )

UI控件初始化可以在以下:

// dom及bui控件初始化完毕 
bui.on("pageinit",function(){
  // dom ready , bui ready
})

多页开发控件及原生方法都必须在bui.ready 里面

// dom及bui及原生方法都初始化完毕, 多页开发用到 
bui.ready(function(){
  // dom ready , bui ready, native ready 
})

在PC的加载顺序是 pagebefore -> pageinit -> pageready -> onload , 在手机的加载顺序是 pagebefore -> pageinit -> onload -> pageready 所以为了方法及dom能正确初始化, 我们的事件监听一般在 pageready .

6.2 监听控件事件

已安装BUI Fast 插件的SublimeText用户, 输入 bui- + 控件名 + -on,按Tab键可以生成以下结构
BUI Fast 书写示例: bui-accordion-on ;

// 监听事件
uiAccordion.on("show",function(){
  // 显示的时候做什么事情
})


控件的更多事件,请查看API文档

注意: 控件的事件监听要在控件初始化之后.

调试

Chrome调试

  • 部署工程(任何部署工程的方式)

    下载服务器编译软件 prepros, 打开prepros软件, 把刚刚新建的工程包,拖进里面, 然后找到 index.html, 右键预览.
    如果开启了跨域的谷歌,可以直接打开 index.html

prepros 预览图

  • 模拟手机效果

    打开chrome 开发者工具, 开启模拟手机效果, 这样才能模拟手机的滑动拖拽事件.

chrome 预览图

DebugTool调试

不同平台会有不同的调试工具.
Debugtool 是品高公司推出的一个移动端调试工具,结合bingotouch一起调试原生API.
多页开发,需要设置 bui.isWebapp = false;

  • 打开手机已经安装的 debugtool 工具 ;
  • 输入部署的地址

微信调试

安卓的微信缓存比较严重,记得在js引用后面加 .js?t=2016073101

<script src="bui.js?t=2016073101"></script>

如果是单页开发调试, bui.router 路由初始化的时候,可以把 cache 参数设置为 false;

buijs命令创建工程

我们从NODE命令行开始构建,这个也是我们推荐的一种构建方式, 每次会从github上面获取最新的模板构建.

进入桌面目录,创建一个demo工程, 默认就是单页模板工程了. 如何使用buijs命令行工具?

在我的桌面创建一个 demo 工程

cd /Users/用户名/Desktop/

buijs create demo

buijs 创建工程预览

你也可以点击这里 下载单页开发包? (单页的工程包需要部署起来才能预览)

打开 demo 目录 工程生成以后的路径: /Users/用户名/Desktop/demo

常用命令

命令行 描述
buijs -v 查看当前工具的版本
buijs -h 命令帮助信息
buijs list 显示可用的版本
buijs list-template 显示可用的模板
buijs create <projectName> [version] 创建bui默认工程
buijs create <projectName> [version] -t link 创建bui示例工程,可以指定模版版本

使用示例

初始化工程目录

webapp: webapp开发工程包 (默认单页开发结构)

buijs create demo

微信: 仿weui演示工程 (默认单页开发结构)

buijs create demo -t weixin 

Bingotouch: Bingotouch打包工程 (默认单页开发结构)
buijs create demo -t bingotouch

Link: Link开发工程包

buijs create demo -t link

BUI Fast 快速书写插件

BUI Fast 是BUI提供的Sublime扩展插件,在Sublime中集成BUI控件及方法的代码提示,为快速开发助力. 里面封装了控件的常用参数及常用方法的语法补全, 版本对应 BUI的版本, 1.3.1版本新增 控件名加”-demo” 快速生成控件初始化及结构,只要把结构复制到body对应的位置就行.

下载 BUI Fast 插件包 (可以让开发更快,查看安装使用说明)

使用BUI Fast来书写控件,有几个好处,
1. 快;
2. 简单好记;
3. 统一推荐的结构,可以减少拼错的概率;

规则1: ui- 开头生成html结构
规则2: bui- 开头生成js结构
规则3: bui-控件名-demo 生成控件完整示例

按键: Tab: 生成控件
按键: Esc: 如果需要重新第2个控件,需要先按一下Esc

// 生成包含js引用的一个html页面
ui-html
  // 生成一个标准的BUI结构,并且包含头部布局
  ui-page

注意: 页面需要先存成.html结尾,以下命令才会生效

ui-html 演示:

ui-html

ui-page 演示:

ui-page

bui-slide-demo 演示:

bui-slide-demo