更新时间:2022-05-07 GMT+08:00
分享

Widget开发规范

本章节介绍前端页面的设计原则和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需要支持响应式设计,页面需要在多屏下进行充分测试验证。

浏览器兼容性

组件开发需要考虑浏览器兼容性,对多浏览进行适配验证。需要支持IE10+,Chrome,Safari和Firefox,移动端需要考虑支持UC、QQ浏览器,Android Chrome和iOS Safari等。

桥接器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引用,保证样式只作用在当前组件。
分享:

    相关文档

    相关产品

close