SiteServer及前端开发指南

# 前言

编程规范使得我们的项目在一定程度上是可维护的。本文定义了代码规范，旨在提高代码质量和协作效率

# SiteServer

官方文档

# 项目目录规范

┌─css                     # 存放页面样式文件    
│  ├── reset.css          # 存放初始化浏览器样式
│  ├── common.css         # 存放公共模块的样式
│  ├── xxx-index.css      # 存放页面css
├─js                      # 存放页面 JS 脚本，`xxx.service.js` 为调用 API 的脚本
│  ├── api.js             # 存放api地址
│  ├── constant.js        # 存放js的常量
│  ├── xxxIndex.js        # 存放页面js
├─img                     # 存放页面图片素材，按网页分文件夹存放
├─library                 # 第三方库，如vue.js、axios.js、elementui
├─component               # 存放自己编写的 UI 组件
├─include                 # 包含文件             
├─Template                # 栏目模板页             
│  ├─Content              # 内容模板页
├─upload                  # siteserver上传的文件，包括文档、图片、视频等
├─channels                # siteserver生成的栏目页，站点导出时不用包含该目录   
├─contents                # siteserver生成的内容页，站点导出时不用包含该目录
├─single-pages            # siteserver生成的单页模板页，站点导出时不用包含该目录
└─T_系统首页模板           # 首页模板页面

# HTML

  • HTML只关注内容，HTML只显示展示内容信息，不要引入一些特定的 HTML 结构来解决一些视觉设计问题
  • 不将img元素当做专门用来做视觉设计的元素 样式上的问题应该使用css解决

# HTML标签

  • 标签必须合法且闭合、嵌套正确，标签名需小写
  • 标签语法无错误，需要符合语义化
  • 标签的自定义属性以data-开头，如：
  • 除非有特定的功能、组件要求等，禁止随意使用id来定义元素样式

# 链接

  • 给 <a> 标签加上title属性，<a>标签的href属性必须写上链接地址，暂无链接的加上javascript:alert('敬请期待！')
  • 非本专题的页面间跳转，采用打开新窗口模式：target="_blank"

# 静态资源

  • 静态资源文件名必须小写，禁止使用除 “-” 以外的特殊字符及中文
  • 单词使用 “-”，如：btn-start.png
  • 文件名应体现资源内容，例如：

bg.jpg 背景图片
mod-bg.jpg 模块背景
sprites.png 精灵图
btn-start.png 开始按钮
ico-play.png 修饰性图片

# https协议自适应

去掉协议http:、https:部分。采用自适应的写法。具体方法如下：

<style>
.bg{background: url(//www.choicelink.cn/img/logo.png) no-repeat;}
</style>

<a href="//z.choicelink.cn/cdc/">疾控平台</a>

<img src="//z.choicelink.cn/CDC/img/banner_01.png">

<script src="//www.choicelink.cn/plugins/element-ui-2.9.1/index.js"></script>

# CSS

  • 颜色：统一使用十六进制，大小写约定统一（建议统一小写），可缩写就缩写例如 #fff 代替 #ffffff
  • 除去某些极特殊的情况，尽量不要使用 !important
  • class、id 全部小写，单词使用短横线分隔
  • 命名使用英文，禁止使用特殊字符
  • 样式名不能包含ad、guanggao、ads、gg是广告含义的关键词，避免元素被网页拓展、插件屏蔽
  • 名称间隔使用-符号
  • 涉及数据、交互等需要联调的部分，禁止通过id选择器定义样式，以免开发过程中id名变化，引起页局错乱
  • 类名命名需要语义化，参考下面的示例：

建议：
.wrap{}                 // 外层容器
.mod-box{}              // 模块容器
.btn-start{}            // 开始
.btn-news-more{}        // 更多新闻
.btn-play{}             // 播放视频
.side-nav{}             // 侧栏导航
.btn-more{}             // 更多

不使用行内样式（<style>.no-good {}</style>）
不在元素上使用 style 属性（<hr style="border-top: 5px solid black">）
不使用行内脚本（<script>alert('no good')</script>）
不使用表象元素（i.e. <b>, <u>, <center>, <font>, <b>）
不使用表象 class 名（i.e. red, left, center）

::: 提示 命名词穷了怎么办？试下这个工具 codelf :::

# 样式重置

HTML中绝大部分标签元素在网页显示中都有一个默认属性值，通常为了避免重复定义元素样式，需要进行重置默认样式（CSS Reset）

点击查看样式代码 
html,body,div,span,applet,object,iframe,caption,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,h1,h2,h3,h4,h5,h6,blockquote,pre,a,abbr,acronym,address,big,cite,code,dl,dt,dd,ol,ul,li,fieldset,form,label,legend{vertical-align:baseline;font-weight:inherit;font-style:inherit;outline:0;padding:0;margin:0;font-family:"Helvetica Neue",Helvetica,"PingFang SC","Hiragino Sans GB","Microsoft YaHei","微软雅黑",Arial,sans-serif}
:focus{outline:0}
body{background:white;color:black}
ol,ul,li{list-style:none;font-size:14px}
blockquote:before,blockquote:after,q:before,q:after{content:""}
blockquote,q{quotes:"" ""}
a{text-decoration:none}
.clearfix:after,.clearfix:before{content:"";display:table}
.clearfix:after{clear:both;overflow:hidden}
.clearfix{zoom:1}
.clear{clear:both;display:block;font-size:0;height:0;line-height:0;overflow:hidden}
.hide{display:none}
.block{display:block}
.fl,.fr{display:inline}
.fl{float:left}
.fr{float:right}
body{min-width:1200px}

# Javascript

文字教程：https://www.liaoxuefeng.com/wiki/1022910821149312

# 函数

函数使用驼峰标识法，以动宾结构命名，函数名应体现函数作用。

动词 含义 返回值
can 判断是否可执行某个动作 ( 权限 ) 函数返回一个布尔值。true：可执行；false：不可执行
has 判断是否含有某个值 函数返回一个布尔值。true：含有此值；false：不含有此值
is 判断是否为某个值 函数返回一个布尔值。true：为某个值；false：不为某个值
get 获取某个值 函数返回一个非布尔值
set 设置某个值 无返回值、返回是否设置成功或者返回链式对象
... ... ...
function canRead(){ // 是否可阅读
    return true;
}

function getName(){ // 获取姓名
    return this.name
}

let loadData = function () {}
let loadData = () => {}

# 变量命名

严格控制变量作用域，

# 常量

使用 const 声明，常量名全部大写，使用下划线分割单词。如：

const SITE_ID = 9323;
const SECRET_KEY = 'dc28fbeb-0a0d-4934-bc79-522c6382c187';

# 局部变量

使用 let 声明，常量名使用驼峰标识法

let userName = 'lytine';

# Vue

  • 不要在 HTML 中引入复杂的代码逻辑（例如一个巨长表达式），复杂的逻辑应提取到 JS
  • 使用 v-for 渲染列表元素时请加上 key 属性，以便维护内部组件及其子树的状态（如果没加会在浏览器报warning）
  • 避免 v-if 和 v-for 用在一起，因为当 Vue 处理指令时，v-for 比 v-if 具有更高的优先级

# service

  • 为提高代码复用性，页面渲染脚本中一般不直接发送 API 请求，而是集中在 service 目录，并分模块编写
  • service 负责发送 API 请求，并作初步数据处理
  • API 的 URL 声明为全局常量，声明在 js/api.js 中
  • API 函数在 service 中编写
  • 声明 API 函数需写文档注释，说明每个参数的作用。
  • 有多个参数时，尽量不要为了方便只声明一个 JSON 对象，请尽可能把接口参数描述清楚，以提高代码可读性
  • 如有需要，可设置参数默认值
  • 当同一个接口可能会被多个地方调用，请尽可能地提高接口函数的兼容性，以适应不同场景的接口调用
  • 如果需要使用自定义的 axios 实例，可在函数列表中传递，例如：
/**
 * 保存采购清单
 * @param {*} userId 用户 ID
 * @param {*} purchaseNumbers 商品编号数组
 * @param {*} axiosInstance 自定义的 axios 实例（可选）
 */
async function savePurchaseList(userId, purchaseNumbers, selectedPurchaseNumbers, axiosInstance) {
    const _axios = axiosInstance || axios;
    let purchaseNumbersStr = purchaseNumbers.join(',');
    let selectedPurchaseNumbersStr = selectedPurchaseNumbers.join(',');
    let res = await _axios({
        url: ADD_PURCHASE_LIST,
        method: 'post',
        data: {
            purchaserProduct: {
                userId,
                productNumbers: purchaseNumbersStr,
                productUsedNumbers: selectedPurchaseNumbersStr
            }
        }
    });
    return res.data;
}

# 组件抽取

  • 建议对常用组件进行抽取 ，如：文件上传组件、倒计时组件，以便在不同页面中引用。参考： vue 组件
  • 在SiteServer开发中，若要配合STL标签完成的功能，不建议封装成组件，而应以包含文件的形式完成该功能，如：页脚，导航菜单等

# Git

视频教程：https://www.bilibili.com/video/BV1KD4y1S7FL
文字教程：https://www.liaoxuefeng.com/wiki/896043488029600

# 格式化commit的好处

  1. 提供更多的历史信息，方便快速浏览
  2. 可以过滤某些文档，方便快速查找
  3. 可以直接从commit生成change log
  • feat:新功能
  • fix：修补
  • docs:文档
  • style:格式
  • refactor:重构（既不是新增，也不是代码变动）
  • test：增加测试
  • chore：构建过程中或辅助工具的变动
例如：
fix:  修复了倒计时时差问题
feat: 首页增加通知公告弹窗

← 任务 →