文档规范说明

不管有多少人共同参与同一项目，一定要确保每一行代码都像是同一个人编写的。

本文档参考了

如果发现错误敬请指正，如果有想法随时提出

命名规则

目录命名

有复数结构时采用复数命名法，如styles

JS文件命名

文件统一全部小写命名，且不应再包含上级文件夹或其他无用标识

以scripts/pha/in/v3/xxx.js为例
反例：pha.in.v3.disp.js、v3disp.js
正例：disp.js

CSS文件命名

同理JS，简短小写

CSP文件命名

文件统一放于csp目录下，全部小写，单词间通过点分隔，且文件名同JS目录下的全称

以scripts/pha/in/v3/xxx.js对应的CSP为例
反例：phainv3xxx.csp、dhcst.ingdrec.csp
正例：pha.in.v3.xxx.csp

JavaScript

简介

考虑当前系统主要依托HISUI以及旧版逻辑代码等，如下大部分暂并未遵循ES6相关新增内容，如const、let、class等，当后续开发涉及时会进行相关变更

变量命名

第一个字母必须是字母、下划线、美元符号，具体应遵循如下2、3。
参数、成员变量、局部变量都统一使用lowerCamelCase风格

反例：

var inicdesc=4; 
var INCIDesc=30;

正例：

var inciDesc=30;

全局变量、常量统一使用UpperCamelCase风格

反例：

var maxage=30; 
var max_age=30;

正例：

var MAX_AGE=30;

数组、对象等集合变量，应通过后缀标识

反例：

var inci = {
    inciDesc: '阿昔洛韦滴眼液',
    inciCode: 'HXY01001'
};
var inciData = ['阿昔洛韦滴眼液', '阿普唑仑片'];

正例：

var inciObj = {
    inciDesc: '阿昔洛韦滴眼液',
    inciCode: 'HXY01001'
};
var inciArr = ['阿昔洛韦滴眼液', '阿普唑仑片'];

一切声明的内容都应该有实际意义，变量、局部变量、全局变量等，且应使用英文描述，禁止出现无意义的、拼音、甚至中文
对象内避免无意义的前缀

反例：

var car = {
    carMake: 'Honda',
    carModel: 'Accord',
    carColor: 'Blue'
};

正例：

var car = {
    make: 'Honda',
    model: 'Accord',
    color: 'Blue'
};

静态字符串推荐使用单引号，不推荐双引号
jQuery获取到的对象使用美元符号标识

反例：

var body = $('body');

正例：

var $body = $('body');

变量声明，应统一提到函数顶部
关于部分无法确定大小写的变量

var userID;  // ID大写
var testURL; // URL大写

函数

函数采用动宾结构，描述函数的行为，且动词应采用对仗词，对仗词见附录

反例：

function notif(user) {
  // ...
}

正例：

function notifyUser(user) {
  // ...
}

避免使用大量参数，一般控制在2个，如果再多则需要考虑使用对象

反例：

function getUsers(fields, fromDate, toDate) {
  // ...
}

正例：

function getUsers({ fields, fromDate, toDate }) {
  // ...
}
getUsers({
  fields: ['name', 'surname', 'email'],
  fromDate: '2019-01-01',
  toDate: '2019-01-18'
});

函数应使用默认参数，而非if语句（ES6）

反例：

function createShape(type) {
    var shapeType = type || "cube";
    // ...
}

正例：

function createShape(type = "cube") {
    // ...
}

坚持单一原则，函数内仅做该函数应该做的，尽量避免通过传入标记控制不同行为
禁止直接在JS内置对象扩展，应单独建立公用函数统一处理

反例：

Array.prototype.myFunc = function myFunc() {
  // ...
};

正例：

待定，函数尚不考虑es6

条件语句避免负面条件，特指调用某一函数

反例：

function isUserNotBlocked(user) {
  // ...
}
if (!isUserNotBlocked(user)) {
  // ...
}

正例：

function isUserBlocked(user) {
  // ...
}
if (isUserBlocked(user)) {
  // ...
}

函数之间应空行区分

对象与数组

对象属性名不需要加引号
对象以缩进的形式书写，不要写在一行
数组、对象最后不要有逗号

反例：

var a = {
    'b': 1
};
var a = {b: 1};
var a = {
    b: 1,
    c: 2,
};

正例：

var a = {
    b: 1,
    c: 2
};

括号

如下关键字必须使用花括号，即使仅有一行代码

if, else,for, while, do, switch, try, catch, finally, with

反例：

if (condition)
    doSomething();

正例：

if (condition) {
    doSomething();
}

引号

最外层统一使用单引号

反例：

var x = "test";

正例：

var x = 'test';

代码风格

四空格缩进
使用分号作为结束
将左花括号放在第一行的结尾，且应空格，右花括号独立一行
单行长度建议控制与80个字符，但无具体标准

注释

单行注释：双斜线后应跟空格，且缩进与上下文的代码保持一致；或在行尾注释，在行尾依然需要左右空格

反例：

// 一些说明...
  var userID = 13;
  var userID = 13; //一些说明

正例：

  // 一些说明...
  var userID = 13;
  var userID = 13; // 一些说明

多行注释：一般用于注释难以理解的、可能存在错误的、逻辑强的代码，且缩进一致

/*
 * 针对下方代码的说明
 * 第一行太长写第二行
 */
var a = 1*2*3*4；

文件注释

/**
 * 名称:     住院移动药房-备药规则维护
 * 编写人:     yunhaibao
 * 编写日期: 2020-03-14
 */

函数注释：简单函数或可通过代码直观理解的函数可不做注释，但公共函数都应完整注释，详细课件附录
更多其他关键字参考http://yuri4ever.github.io/jsdoc/，

/**
 * 描述函数功能
 * @param {string} userID - 描述入参
 * @param {string} [userName] - userName是一个可选参数
 * @param {object} chkObj
 * @param {string} chkObj.userID - 参数chkObj对象中的userID说明
 * @param {object[]} g - 参数g为一个对象数组
 * @return
 */
function Test(userID, userName, chkObj, g) {
    ...
}

undefined

禁止直接使用undefined判断变量，应使用typeof

反例：

if (person === undefined) {
    ...
}

正例：

if (typeof person === 'undefined') {
    ...
}

语法

用’=’, ‘!’代替’==’, ‘!=’；

反例：

if (a == 1) {
    a++;
}

正例：

if (a === 1) {
    a++;
}

for-in里一定要有hasOwnProperty的判断
禁止在内置对象的原型上添加方法，如Array, Date
禁止在内层作用域的代码里声明了变量，之后却访问到了外层作用域的同名变量，即局部与全局同名的问题
禁止debugger、console出现在提交的代码里
禁止在循环内部再声明函数
禁止数组内出现空元素
禁止出现空函数

杂项

禁止代码缩进tab、空格混合使用

CSS

简介

说明基础CSS相关规范

Class命名

全部小写，单词间通过中横线间隔
涉及ID的，使用驼峰规则
尽可能简短，但避免过度简写，如button可简写为btn，但不能为bn、b、bt等
为避免冲突，所有本组的css应以pha开头

反例：

.header{
    ...
}

正例：

/* class */
.pha-header {
    ...
}
/* id */
#conUser {
    ...
}

语法

四空格缩进
每个属性末尾以分号结束
颜色应统一使用16进制
避免0值使用单位，如用 margin: 0; 代替 margin: 0px;
为选择器分组时，将单独的选择器单独放在一行
为了代码的易读性，在每个声明块的左花括号前添加一个空格，且右括号应另起一行（即使仅有一行样式）
每条声明语句的 : 后应该插入一个空格
为了获得更准确的错误报告，每条声明都应该独占一行
样式之间应空行间隔
属性之间应适当空行，以确保同类型的在一起，提高易读

反例：

.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}
span{
    color: #fff;
}

正例：

.selector,
.selector-secondary,
.selector[type="text"] {
    padding: 15px;
    margin-bottom: 15px;
    background-color: rgba(0,0,0,.5);
    box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}
span{
    color: #fff;
}

注释

以/ 注释内容 /格式注释，前后空格

/* 注释内容 */
.pha-element {
    width: 20px;
}

引号

最外层统一使用双引号
url的内容要用引号
属性选择器中的属性值需要引号

.pha-element:after {
    content: "";
    background-image: url("page.png");
}
li[name="second"] {
    ...
}

选择器

样式尽量使用class形式
对于频繁出现的样式，不应使用选择器筛选（如[class^="..."]），浏览器性能会受此影响，应建立直接的class引用，或使用更直接的选择
选择器要尽可能短，并且尽量限制组成选择器的元素个数，建议不要超过 4个

反例：

span {
    ...
}
.page-container #stream .stream-item .tweet .tweet-header .username {
    ...
}
.avatar {
    ...
}

正例：

.avatar {
    ...
}
.tweet-header .username {
    ...
}
.tweet .avatar {
    ...
}

属性声明顺序

相关属性声明应归为一组,并且按照如下顺序

Positioning：定位
Box model：盒模型
Typographic：排版，字体行号等
Visual：视觉样式，边框背景色等
Misc：其他各种

.pha-content {
    /* Positioning */
    position: absolute;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
    z-index: 100;
    /* Box-model */
    display: block;
    float: right;
    width: 100px;
    height: 100px;
    /* Typography */
    font: normal 13px "Helvetica Neue", sans-serif;
    line-height: 1.5;
    color: #333;
    text-align: center;
    /* Visual */
    background-color: #f5f5f5;
    border: 1px solid #e5e5e5;
    border-radius: 3px;
    /* Misc */
    opacity: 1;
}

前缀属性

因浏览器不同，部分语法存在差异，在使用特定厂商的带有前缀的属性时，通过缩进的方式，让每个属性的值在垂直方向对齐，这样便于多行编辑

反例：

.pha-ele {
    -moz-border-radius: 3px;
    border-radius: 3px;
    -webkit-border-radius: 3px;
}

正例：

.pha-ele {
    -webkit-border-radius: 3px;
       -moz-border-radius: 3px;
            border-radius: 3px;
}

@import

禁止使用，应使用link标签引入，@import指令较慢且容易导致不可预知问题

媒体查询

媒体查询放在尽可能相关规则的附近。不要将他们打包放在一个单一样式文件中或者放在文档底部。如果你把他们分开了，将来只会被大家遗忘。

@media (min-width: 480px) {
    .element {
        ...;
    }
    .element-avatar {
        ...;
    }
    .element-selected {
        ...;
    }
}

杂项

已发布CSS避免出现空规则
禁止在同个规则里出现重复的属性
禁止在同一个CSS文件出现两个相同规则

HTML与CSP

简介

CSP规范遵循HTML，但存在少许差别

标签命名

使用驼峰命名规则，首字母小写
作为查询条件的表单元素，不需要使用前缀标识（如combobox、textbox），按钮除外
作为查询条件的非表单元素的，需要前缀标识（如grid、tree等）,且为固定标识符
作为存储数据的元素（如药品信息维护的明细信息），不加con前缀

反例：

<!-- 查询条件 -->
<input id="inci">
<input id="highPriceFlag">
<!-- 表格 -->
<table id="GridSendLoc"></table>
<table id="tblSendLoc"></table>
<!-- 数据 -->
<input id="InciDesc">

正例：

<!-- 查询条件 -->
<input id="conInci">
<input id="conHighPriceFlag">
<!-- 表格 -->
<table id="gridSendLoc"></table>
<!-- 数据 -->
<input id="inciDesc">

语法

四空格缩进，嵌套节点缩进
属性使用双引号，不要使用单引号
属性名统一小写
不需要在自动闭合的标签上使用斜线（如 )
不要忽略可选的关闭标签，如（

<!DOCTYPE html>
<html>
    <head>
        <title>Page title</title>  
    </head>
    <body>
      <img src="images/company-logo.png" alt="Company">
      <h1 class="hello-world">Hello, world!</h1>
    </body>
</html>

HTML5 doctype

页面开头使用这DOCTYPE来启用标准模式，使其在每个浏览器中尽可能一致的展现

<!DOCTYPE html>
<html>
    ...
</html>

lang属性

根据HTML5规范，强烈建议html标签上加上lang属性。这会给语音工具和翻译工具帮助，告诉它们应当怎么去发音和翻译。因此固定为中文

<!DOCTYPE html>
<html lang="zh-cn">
    ...
</html>

字符编码

通过声明一个明确的字符编码，让浏览器轻松、快速的确定适合网页内容的渲染方式，通常指定为’UTF-8’，但通常在studio的格式为GBK，故此处暂不需要声明。

IE兼容模式

用 meta 标签可以指定页面应该用什么版本的IE来渲染，本组开发固定写法

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="X-UA-Compatible" content="IE=Edge">
    </head>
    ...
</html>

引入JS、CSS的规范链接

html5通常不需要指定type

<!-- 引入 CSS -->
<link rel="stylesheet" href="ui.css">
<!-- 页面内 CSS -->
<style>
    ...
</style>
<!-- 引入 JS -->
<script src="../scripts/pha/ip/v4/sendloc.js">
<!-- In-document JS -->
<script>
    ...
</script>

属性顺序

属性应按照固定顺序出现，以保证易读性

class
id
name
data-*
src, for, type, href, value , max-length, max, min, pattern
placeholder, title, alt
aria-*, role
required, readonly, disabled

减少标签数量

尽量减少多余无用的父节点

反例：

<span class="avatar">
    <img src="...">
</span>

正例：

<img class="avatar" src="...">

针对CSP

文档开头应统一增加验证登录代码
所有页面在加载时都应有遮罩，避免用户看到解析前的错乱布局
DOCTYPE后需紧跟文件说明，主csp与js，且路径应写全

<!DOCTYPE html>
<!--住院移动药房-送药科室维护
    csp:csp/pha.ip.v4.sendloc.csp
    js: scripts/pha/ip/v4/sendloc.js
-->
<html lang="zh-cn">
<!-- 验证session过期 -->
<csp:method name=OnPreHTTP arguments="" returntype=%Boolean>
    d ##Class(websys.SessionEvents).SessionExpired() q 1
</csp:method>
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge">
    <!-- iMedical版本标题 -->
    <title>
        <TRAK:TRANSLATE id=title>##(%session.Get("TITLE"))##</TRAK:TRANSLATE>
    </title>
    <TRAK:HEAD>
    </TRAK:HEAD>
</head>

编辑器设置

简介

仅做对VSCode的说明，其他编辑器亦有相关设置，请自行查阅相关资料

插件

使用格式化代码工具Prettier，可在VSCode应用商店下载
点击菜单【查看】-【命令面板】，输入setting，选择【打开设置】，注意不是【打开默认设置】，而后可将如下内容增加的设置的json文件中，重启VSCode测试无误即可

如下为一种设置方式，仅供参考，注意设置标注与最后的prettier

// 将设置放入此文件中以覆盖默认设置
{
    // 编辑器字体
    "editor.fontFamily": "consolas",
    // 文件默认编码
    "files.encoding": "gbk",
    // 编辑器字号
    "editor.fontSize": 15,
    "vsicons.dontShowNewVersionMessage": true,
    "git.ignoreMissingGitWarning": true,
    "workbench.statusBar.visible": true,
    // 将csp视为html
    "files.associations": {
        "*.csp": "html"
    },
    "explorer.confirmDelete": false,
    "editor.renderWhitespace": "none",
    "editor.renderControlCharacters": false,
    "breadcrumbs.enabled": true,
    "workbench.activityBar.visible": false,
    "workbench.settings.settingsSearchTocBehavior": "hide",
    // 主题
    "workbench.colorTheme": "Monokai",
    "editor.detectIndentation": false,
    // 如下几个为默认格式化的插件
    "[html]": {
        "editor.defaultFormatter": "vscode.html-language-features"
    },
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[css]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[csp]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[json]": {
        "editor.defaultFormatter": "vscode.json-language-features"
    },
    // 是否使用编辑器设置,否
    "prettier.useEditorConfig": false,
    "prettier.htmlWhitespaceSensitivity": "ignore",
    // 单行代码字符数
    "prettier.printWidth": 500,
    // Tab键转为4空格
    "prettier.tabWidth": 4,
    // 使用单引号
    "prettier.singleQuote": true
}

附录

JS常用动词

简写	说明
get\set	取值\给值
add\remove	增加\移除
show\hide	显示\隐藏
view	查看
browse	浏览
edit	修改
save	保存
delete	删除
find	查询
undo	撤销
redo	重做
clean	清除
index	索引
observe	观察
send\receive	发送\接收
refresh\synchronize	刷新\同步

JS变量缩写

数据类型	简写后缀
object	obj
array	arr
json	json
function	fn
message	msg

HTML标签缩写

组件	简写前缀	说明	举例
a	btn	作为按钮	btnFind
button	btn	按钮
datagrid	grid	数据表格	gridDisp
datagrid-toolbar	gridId+Bar	表格工具栏	gridDispBar
tree	tree	树
treegrid	treeGrid	树形表格
window	win	窗口
tab	tab	页签
dialog	dialog	模态框

前端代码规范