Widget开发规范

设计原则

高级页面开发模式下，页面是由N个widget构成（N>=1）。Widget可以理解为页面中的小组件，组件的拆分可根据具体的业务和组件的复用情况进行。如果某个页面不可拆分或无复用场景，则可以只有一个Widget构成。

组件存在的最主要的意义是“可在不同页面中被复用”。理论上拆分越细，可被复用的概率就越大。但是带来的副作用是页面开发的复杂度上升，所以拆分的力度需要进行综合的考虑。

Widget命名

Widget命名采用三段式命名：命名空间_业务名称_widget（固定字段），业务名称采用大驼峰命名。

函数/方法注释

函数/方法注释采用典型的JSDoc的注释方式。

• 函数注释入参说明：@param + 1个空格+ {参数类型} + 1个空格 + 参数名+ 1个空格 + 参数说明。
• 函数注释出参说明：@return + 1个空格 + {参数类型} + 1个空格 + 出参说明（如果没有出参，则出参说明可不写）。

有关键逻辑或者重大变更时，增加改动者及改动描述。

        /** 
         * 在地图上创建标志 
         * 
         * @param {String} latLng 经纬度信息 
         * @param {Object} mapInfo 地图描点信息 
         * @return {Boolean} 在地图上创建点选标志的结果
         * @version 20180310  modify by xxx shangsan 修改地图上描点的样式
         * @version 20180314  modify by xxx wangwu 在地图上描点增加事件发送，供外部订阅
         */ 
        var placeMarkerAndPanTo=function(latLng, mapInfo) {                      
                //返回创建点选标志的结果 
             return true; 
          }

方法内注释

方法内使用单行注释，以“//”开头。对代码的注释，应放在其上方或右方（对单条语句的注释）相邻位置。

var placeMarkerAndPanTo=function(latLng, mapInfo) 
{
   //返回创建点选标志的结果
   return true; 
}

FTL注释

• 在一些主要节点标签结束后，加上注释。

  <div class="success-operate">
       <a href="javascript:;" class="btn-md-red"
           @click="trackOrder">Track Order</a> <!-- btn-md-red end 跳转到订单详情页查看订单-->
       <a href="javascript:;" class="btn-md-primary"
           @click="continueShopping">Continue Shopping</a> <!-- btn-md- primary end 跳转到商城首页继续购物--> 
  </div>

• 在一些循环结束后，加上注释。

  <li class="li-tab" v-for="(item,index) in g_viewOrderData.tabsParam">
       <div class="item-wrap">
          <div class="img-wrap">
                 <img :src="item.url"></img>
          </div>
        <div class="wid-tab-text">{{item.value}}</div>
    </div> 
  </li><!--loop end 遍历订单上的状态页签，获取名称和链接-->

样式文件

• 样式文件中，图片及字体文件的引用，需使用相对路径。
• 字体文件需要放置在与样式文件同级的目录中，目录名称为font、fonts（两个任选其一即可），可设置子层目录，子层目录命名无要求。
• 目录及图片、文件的命名仅支持数字、字母（大小写均可）、下划线和中划线。
• 支持的图片格式，包含png、jpg、jpeg、gif、bmp和webp。
• 支持的字体文件格式，包含tiff、woff、ttf、otf、eot和svg。
• 多个Widget样式可以抽取为单独库文件，独立库文件可以方便进行整体样式主题的切换。缺点是Widget的运行，需要对这个库文件产生依赖。

  如果Widget比较独立，也可以将样式文件定义到Widget作用域的css中。

响应式设计

Widget需要支持响应式设计，页面需要在多屏下，进行充分测试验证。

浏览器兼容性

组件开发需要考虑浏览器的兼容性，对多浏览进行适配验证。

桥接器Bridge

• Widget数据访问需要封装到Bridge中，不允许在Widget中，直接通过ajax访问业务数据服务。

  通过Bridge的封装，可以保持Widget的稳定性。未来数据源的切换不需要升级Widget，只需要切换Bridge即可。

• 对于数据消费类的Bridge，mock目录不允许为空。

  Mock数据会在编辑状态加载，如果直接调用API，可能会因为API的不稳定而引起UI渲染异常。

• 一个查询API一个Bridge，更新API当前可以共用同一个Bridge。
• 前端对象需要在Bridge中，进行明确定义，字段清晰。

开放性

• Widget自身是开放的，直接引用业界优秀的开源组件可以提高开发效率。

  例如，使用MVVM框架Vue（Vue相比AngularJS更轻量，性能更优）以及使用基于Vue的前端控件库Quasar，Element-UI。

• 不允许引入JQuery，因为框架已默认提供，引入后会引起运行冲突异常。
• 非特殊场景，组件的尺寸大小不建议写成固定值，可以指定最大/最小值。
• 非特殊场景，不允许直接对DOM元素添加CSS。DOM元素的样式通过显式的class引用，保证样式只作用在当前组件。