• 基于gulp的前端框架开发规范

    前端开发及相关规范 - 基于gulp的前端框架开发规范

    1.前端开发工具的安装和使用说明

    前端开发工具的目录结构

    htmlcodeBuilder - v0.9
    ├── statics
    ├── html //静态文件开发
    ├── js // 非require引入的js文件
    ├── Lib // 第三方JS包
    ├── ve_2_1 //
        ├── css // 样式目录
            ├── fonts // bootstrap的图标字体
            ├── img // 图片目录
            ├── less // less源码
            ├── sprite // 雪碧图按目录全称目录名的图片
                ├── dirName
            ├── vender // 第三方css包,比如bootstrap
        ├── js // JS目录
            ├── dist //生成文件的目录(与开发源码目模块对应)
                ├── cart.js  
                ├── common.js 
                ├── lib.js 
                ├── region.js 
                ├── sidebar.js 
                ├── tpl.js 
                ├── user.js 
                ├── web.js 
            ├── src // 开发源码的目录
                ├── cart // 购物车模块
                ├── common // 公共的函数模块
                ├── lib // 公共jq插件模块
                ├── region // 处理联动地址的模块
                ├── sidebar // 侧边栏模块
                ├── tpl //  前端mvc模板引擎的压缩源码
                ├── user // 用户中心模块
                ├── web // VE前端模块，包括首页、亲子、品牌专题、详情页等
            ├── tpl //
            ├── config.dev.js // requirejs 开发配置文件[自动生成]
            ├── config.js // requirejs开发配置文件[自动生成]
            ├── config.release.js //
            ├── config.test.js // requirejs 测试环境配置文件[自动生成]
            ├── js.map.json // 压缩后的文件位置映射[自动生成]
            ├── path.json // requirejs 的 config -> path 内容，第三包的路径缩写配置
            ├── shim.json // requirejs 的 config -> shim 内容，第三包的依赖申明
            ├── ver_config.json // 开发、测试、预生产到发布，方便部署静态资源，而创建的版本和环境变量
        ├── tpl //
            ├── toolbar
                ├── mian.html 
    ├── dot.gif // lazyloading的占位符
    ├── evc-VE.js // 在线客服的js
    ├── favicon.ico // 网站的缩略logo
    ├── README.md // 文档首页内容 markdown 语法
    ├── region.js // 地址

    statics/Lib // 第三方JS包 目录说明

    每个包单独一个文件夹，目的是：方便一个包多版本存放
    如：jQuery 的 1.x 跟 2.x ， 2.x 是针对移动版

    安装

    • 前往 http://nodejs.org/ 安装nodeJS
      • 注意系统是32位还是64位的，选择对应的版本
      • 如果是windows系统，需自行设置好环境变量，将nodejs的路径加入到系统的 path 环境变量中
    • 在终端执行 npm install -g cnpm --registry=http://r.cnpmjs.org
    • 在终端执行 npm install -g gulp ，安装 gulp 全局支持
    • 进入前端自动化开发和部署工具的目录，执行 npm install(使用国外镜像) 或 cnpm install(使用国内镜像)

    -- enjoy --

    升级自动化工具

    • 进入前端自动化开发和部署工具的目录，执行 npm install(使用国外镜像) 或 cnpm install(使用国内镜像)

    执行自动化工具

    以下操作，需进入 FeBuilder 的解压目录目录下执行

    • gulp
      • 监控 less 文件变化，自动生成 css
      • 监控 js/src 文件变化， 自动在 dist 目录生成对应的压缩 js
      • 监控 js/src 文件变化， 自动在 doc 目录，根据 jsdoc 格式，生成文档
      • 监控 css/sprite 目录，如果有新 sns 文件，自动生成雪碧图

    注：如果添加新目录，需重新执行该指令，否则新目录不会监控

    • gulp sprite 生成雪碧图
    • gulp script 压缩，合并，打包js
    • gulp less 编译less文件
    • gulp watch

    数据格式约定

    • 原则上，前端开发是完全可以脱离开发环境和生产环境来进行的，因为前端开发主要是开发一些静态的资源，比如 HTML 、 CSS和 JS 等。
    • 与后端的通讯，我们约定以 JSON 的格式进行数据交换，那么前端开发完全就可以本地模拟一个 .json 格式的文件来进行开发调试。
    • 基于 JSON 的本地模拟数据，在与后端的同事沟通约定后，只需要对方API返回的数据结构和本地模拟的一致即可。

    2.前端开发工具的相关约定

    文件和目录的命名约定

    • 必须是英文单词、名字拼音或者名字拼音首字母;
    • 多个单词用下划线(_)连接;
    • 只能出现英文字母、数字、连字符(_)，严禁以中文名来命名;
      > 注：此命名约定适用于 html, css, js, swf, php, xml, png, gif, jpg, ico 等前端维护的所有文件类型和相关目录

    开发文件的建立

    • css
      • 基于gulp的前端框架，前端开发是通过编写LESS，然后gulp会自动监听LESS来生成压缩的CSS，生成的文件与LESS同名
      • 在 css/less 目录下建立LESS文件
      • 不需要输出的CSS的，文件名要以下划线 _ 为前缀，通过 @import 包含的方式调用
      • 例如: @import "_ve_index";（注意，@import包含的less文件可将.less后缀省略掉）
      • 尽管LESS语法兼容CSS语法，但LESS源文件的编写请遵循LESS语法，以提高它的可读性和可维护性。 
        less.jpg
    • icon合成雪碧图 -css sprite
      • 在 css/sprite 目录下，按照功能模块的不同来建立文件夹，然后将零星的小图标放置在这个文件夹中；
      • 在gulp启动的状态下，它会自动监控文件夹中文件的变化，自动合成 css/img/dirName.png 雪碧图及 css/less/_sp_dirName.less。
      • 通过 @import 包含的方式调用 _sp_dirName.less即可
      • 请注意，如果一个项目没有icon，则不要建立一个空的文件夹，gulp会报错。
    什么是CSS Sprites？？

    CSS Sprites就是把网页中一些背景图片整合到一张图片文件中，再利用CSS的background-image，background-repeat，background-position的组合进行背景定位，background-position可以用数字精确的定位出背景图片的位置。利用CSS Sprites能很好地减少网页的http请求，从而大大的提高页面的性能，这也是CSS Sprites最大的优点。
    css_sprite.jpg

    • Javascript

      为了项目更容易管理和团队协作，js的开发需要以模块化的方式进行。
      在 ve_2_1/js/src 目录下建立按照功能模块的不同，来建立文件夹及js文件

      • js要按照AMD规范来命名和书写， 通过requireJS包管理器的方式来加载它依赖的其他js模块；
      • js编译好之后，会自动压缩到 ve_2_1/js/dist 目录，在页面中需要配合require.js（js依赖管理）和config.js（依赖的配置文件）来加载自动压缩后的js。
      • config.js有四个不同环境： config.dev.js、config.test.js、config.release.js和config.js 分别对应 开发环境、测试环境、预生产环境和生产环境。
      • 四个不同环境的js文件加载，在嵌套cms系统的前端模板时，只需要用 {php echo init_js();} (后端php同事要预先封装好init_js 函数)来动态输出即可。
        js.jpg
        *** 更多js模块化开发的参考文档:
      • RequireJS和AMD规范
      • Javascript模块化编程1
      • Javascript模块化编程2
      • Javascript模块化编程3

      *** 举例：

      ve双城首页的js，我们就建立在 js/src/web 目录下，并命名为index.js，它依赖于'jquery.slide', 'web/common', 'web/timer'和jquery，而'jquery.slide', 'web/common', 'web/timer'也依赖于jqeury，jquery已被全局化，那么index.js应该是这样的：

      • index.js:
      javascriptcodeBuilder - v0.9
          define('web/index', ['jquery.slide', 'web/common', 'web/timer'], function(slide, common) {
        var doc = document,
            win = window;
        //首页大图轮播
        var _fullSlide = function() {
            var $sliderBox = $('.slider_box');
            var $fullSlide = $('.fullSlide');
            var imgs = $fullSlide.find('.bd .preload');
            var now_img = $fullSlide.find('.bd img').eq(0);
            ...

      又如 common.js应该是这样的：

      • common.js:
      javascriptcodeBuilder - v0.9
          define('web/common', [], function() {
        var exports = {};
        var doc = document,
            win = window;

        //网页顶部的关注hover事件
        exports.hover_qr = function() {
            $('.QRcode').on('mouseover', function() {
                $('.QRcode-box').toggle();
                $('.QRcode i').toggleClass('selected');
            }).on('mouseout', function() {
                $('.QRcode-box').toggle();
                $('.QRcode i').toggleClass('selected');
            });
        };
        ...

      index.js 和common.js不需要在引用jquery.js,在它们内部中可以直接使用全局jquery中定义的 $符号。

      • 页面中加载index.js的方法
      htmlcodeBuilder - v0.9
          <script src="http://s1.ve.cn/statics/Lib/require/require.js?_v2.1">
    </script><script src="http://s1.ve.cn/statics/Lib/jquery/jquery.min.js?_v2.1"></script>
    <script src="http://s1.ve.cn/statics/ve_2_1/js/config.js?_1415852637"></script>
    <!-- requireJS -->
    文档的格式化 - tab制表符来控制缩进
    • 无论css、html还是js，开发的源文件都要适当地进行代码的格式化，一律以tab制表符来控制缩进；
    • 调整自己的编辑器，将 tab制表符 以 4个空格 来替代。
      > 小技巧：在绝大部分IDE开发工具中， tab是缩进，而shift+tab则是删除缩进。

    3.HTML静态模板规范

    约定

    • 所有页面元素的z-index属性值控制在1000以下，将1000-2000留给组件级调用，2000以上用于解决特殊情况下的适应问题；
    • 所有的标签及属性名采用小写，DOCTYPE除外；
    • 保证标签语义化；
    • 分离思想，所有的样式除特殊情况，css样式不能内联写在style属性中；
    • 如非必要，尽量不采用表格来布局页面。
    • 如非项目需要，不使用html5特有的标签，如canvas。

    页头声明

    必须加上以下3项，提高兼容性

    htmlcodeBuilder - v0.9
        <meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" />
    <meta name="renderer" content="webkit" />
    <meta name="viewport" content="width=device-width, initial-scale=1">

    前 2 项，是指定 360 等国产浏览器，用 webkit 内核渲染页面
    后 1 项，是在移动端上，指定页面的缩放比例

    HTML注释

    开始和结束均需要带有可识别的class或id，结束时则加斜杠 /(表示标签闭合了)。

    htmlcodeBuilder - v0.9
        <!-- 商品标题 -->
    <div class="breadcrumb">
        <a href="">唯一优品首页</a>&nbsp;&gt;&nbsp;<a href="">名品特卖</a>&nbsp;&gt;&nbsp;<a href="">新安怡夏季大促</a>&nbsp;&gt;&nbsp;<a href="" class="title">新安怡 婴儿保湿润肤乳液(200ml)</a>
    </div>
    <!-- 商品标题end -->

    css ， js 文件，在页面上的位置

    • 原则上， css 文件， 必须在 <head> 内
    • 原则上， js 文件， 必须在 </body> 结束前（尽可能的放底部），尽情避免在 <head> 内插入 js

    script 标签是阻塞式加载的。 如果一个 js 文件 比较大，或者 404 ，这将阻塞后面部分内容的加载

    标准前端html模板 -- 仅供参考

    htmlcodeBuilder - v0.9
        <!DOCTYPE html>
    <html lang="zh-CN">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" />
        <meta name="renderer" content="webkit" />
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{title}</title>
        <meta name="description" content="{description}" />
        <meta name="keywords" content="{keywords}" />
        <!-- 样式文件 -->
        <link rel="stylesheet" href="./../../ve_2_1/css/ve_wap.css" />
    </head>

    <body>

       <section class=''>
           <div class="container">
               <div class="row">
                 a
               </div>
           </div>
       </section>

       <!-- 尾部js -->
       <script src="./../../ve_2_1/js/vendor/require/require.js"></script>
       <script src="./../../ve_2_1/js/config.dev.js"></script>
       <!-- 替换结束 -->

       <!-- 自定义代码部分 -->
      <script>
       //js codes here.
       require(['wap/index'], function() {
           require(['wap/indexJs']);
       });
       </script>
    </body>
    </html>

    推荐使用的元素

    • 结构元素：blockquote, body, br, div, h1 - h6, head, hr, html, p
    • 头部元素：base, link, meta, script, style, title
    • 列表元素：ul, ol, li, dl, dt, dd
    • 文本格式元素：a, abbr, acronym, address, bdo, cite, code, del, dfn, em, ins, kbd, noscript, pre, q, samp, small, span, strong, sub, sup, var
    • 表单元素：button, fieldset, legend, form, input, label, optgroup, option, select, textarea
    • 多媒体元素：area, img, map, object, param
    • 表格元素：caption, col, colgroup, table, tbody, td, tfoot, th, thead, tr
    • 窗体元素：iframe

    不推荐使用的元素

    • 结构元素：无
    • 头部元素：无
    • 列表元素：dir, menu
    • 文本格式元素：b, basefont, big, blink, center, comment, font, i, marquee, nobr, plaintext, ruby, s, strike, u, wbr, xmp
    • 表单元素：isindex
    • 多媒体元素：applet, bgsound, embed, noembed
    • 表格元素：无
    • 窗体元素：frame, frameset, noframes

    转世重生的元素

    • i - 作为单个图标的展位符，表示icon
    • b - 预留，尚未想到合理的复活理由
    • s - 预留，尚未想到合理的复活理由

    4.CSS规范

    文件编码约定

    • 所有文件一律采用　utf-8编码

    id 和 class 命名约定

    • id 和 class 的命名总规则为： 内容优先,表现为辅. 首先根据内容来命名, 比如 main-nav. 如果根据内容找不到合适的命名, 可以再结合表现来定, 比如 amount-choose, product-intro, main_nav,logo_box 名称一律小写, 多个单词用下划线或者连字符连接, 比如 .time-countdown,size-choice,logo_box
    • class 名称中只能出现小写的 26 个英文字母、数字、下划线和连字符(-), 任何其它字符都严禁出现.
    • id的命名采用连接符命名法和下划线命名法,首字母小写，如：buy-ok,shop_btn
    • id 和 class 尽量用英文单词命名.确实找不到合适的单词时, 可以考虑使用产品的中文拼音。
    • 对于中国特色词汇可以使用拼音
    • 除了产品名称和特色词汇, 其它任何情况下都严禁使用拼音.
      *　在不影响语义的情况下, id 和 class 名称中可以适当采用英文单词缩写, 比如 col, nav, hd, bd, ft 等, 但切忌自造缩写.（常用缩写总结在css规范部分）
    • id 和 class 名称中的第一个词必须是单词全拼或语义非常清晰的单词缩写, 比如 goods, col.

    基本规范

    • 模块命名要注意带上模块名，下面尽可能的简写，页面级（app应用级）命名应该尽量简洁;
    • 尽可能地使用css-sprite
    • 尽量通过class属性定义样式,将id留给hook
    • 尽量不要在css中使用expression
    • 组件开发中，可以先不考虑性能，尽量使用选择符组以方便html调用，如.table-ctrl tbody tr td.selected{}；
    • font中的字体用英文或unicode代替,如黑体可写成SimHei：font: 12px/1.5 SimHei ,tahoma,arial,5b8b4f53,sans-serif;

    CSS引用

    • 统一以link形式引入
    • 不推荐内嵌形式引入css
    • 不推荐标签出现在body中，特定页面（比如404错误页）除外。
    • 不推荐内联CSS，请尽量放在head标签内

    常用CSS属性顺序建议

    • 显示属性(display, list-style, position, float, clear)
    • 盒模型(width, height, margin, padding, border, background)
    • 文本属性(color, font, text-decoration, text-align, vertical-align, white-space, other text, content)

    注释风格

    csscodeBuilder - v0.9
        /*头注释*/
    /*------------------------------------------------
    @Filename:  ve_goods
    @Description:  产品内页
    ------------------------------------------------*/

    //商品属性区块  

    //产品颜色选择

    /*爆款*/

    5.Javascript规范

    快速指引

    • 必须使用 Tab 键进行代码缩进，以节约代码大小和提高可读性。 (调整自己的编辑器tab制表符一律以4个空格来替代)

    • 命名风格
      || || 规则 || 列如 ||
      || 类 || 混合式 || fixToTopClass ||
      || 公有方法 || 混合式 || isDate() check_password ||
      || 公有变量 || 混合式 || 列如 ||
      || 常量 || 大写式 || 列如 ||

      *　其他建议风格　非必要
      　|| 结构 || 规则 || 列如 ||
      　|| 私有方法 || 混合式 || ||
      　|| 私有变量 || 混合式 || ||
      　|| 方法参数 || 混合式 || ||
      　|| 本地(local)变量 || 混合式 || ||

    • 所有语句结束后，必须使用;号结束

    命名规范

    基本原则：尽量避免潜在冲突；精简短小, 见名知意。

    • 局变量以$开头，如$user，相当于：window.$user
    • 常量全部大写，单词以下划线分隔，如STATIC_ROOT
    • 普通变量，采用驮峰式写法，首字母小写，如userIcon，UserRelation
    • 类名首字母大写，如Object = function(){}
    • 局部变量可缩写，命名空间，类名尽量不缩写
    • 方法和函数，名字同普通变量名;
    • 条件表达式、正则表式式，如果很复杂，给其命名
    • 枚举量, 同常量;
    • 私有变量, 属性和方法, 名字以下划线开头,如_init(),_param;
    • 保护变量, 属性和方法, 名字同普通变量名;

    注释规范

    因为基于gulp架构，jsDoc插件可以自动根据段落注释自动生成可读性很好的文档，因此前端开发必须按照jsDoc的规范来写了js注释。
  • 相关阅读:
    笔记：端子镀金厚度
    笔记：C 编译过程
    抽象类与接口类
    面向对象的三大特性之继承
    类命名空间与对象、实例的命名空间 面向对象的组合用法
    初识类和对象
    面向过程与面向对象
    初识面向对象
    hashlib模块configparser模块logging模块
    collections模块和os模块
  • 原文地址：https://www.cnblogs.com/yesw/p/4812598.html
Copyright © 2020-2023  润新知