快速入门春松客服 v7 版本开发，Pugjs 介绍及使用注意事项 | Chatopera

春松客服：快速获得好用的开源智能客服系统

https://www.cskefu.com/

春松客服使用 Pugjs

春松客服 v7 版本自2021年2月10日发布至今，短短一个月，已经完成 2,000+ 次 Docker 镜像部署。 春松客服 v7 版引入 Pugjs 替换 Freemarker，用意是提升前端开发速度：使用 Freemarker 的前端代码，因为标签太多导致维护效率低。

v7 版本最终发布时，已经达到了完全替换的目的，Pugjs 的一些优点：

• 简化代码：前端代码量减少 60%
• 支持格式化: 在开发环境中，更容易自动排查错误和提示
• 跟容易维护，增强可读性

以上三点为主要的优点，现在春松客服前端开发效率提升了至少 3 倍！

以下内容将围绕如何使用 Pugjs 为主，帮助春松客服开源社区用户可以快速入门新版本开发，定制智能客服系统。

Pugjs 例子

在正式介绍之前，先看一个例子：

//- template.pug
p #{name}的 Pug 代码！

例子来源：https://pugjs.org/zh-cn/api/getting-started.html

这就是一个 Pugjs 代码，Pugjs 是后端 HTML 渲染引擎，不同编程语言有兼容 Pugjs 的工具包，将 Pugjs 代码编译为 HTML 字符串。

春松客服 v7 使用的 Pugjs 渲染引擎实现是 pug4j，https://github.com/neuland/pug4j。

pug4j’s intention is to be able to process pug templates in Java without the need of a JavaScript environment, while being fully compatible with the original pug syntax.

春松客服 contact-center root POM:

Pugjs 语法

参考中文站点文档：
https://pugjs.org/zh-cn/language/attributes.html

该站点对 Pugjs 的基础知识介绍的非常详细。需要强调的是，重点要理解 unbuffered和buffered 的区别。

使用注意事项

接下来，假设你已经运行了一些 Pugjs 的小例子及看了 Pugjs 的语法文档。那么在春松客服中如何使用呢？
春松客服 Pugjs 的模板源码位置：
contact-center\app\src\main\resources\templates

以 .pug 结尾的文件都是 Pugjs 代码文件。

以下各点，有的是代码书写约定，有的是春松客服的设计，都属于注意事项。

判断模块

春松客服中，使用模块化加载，比如企业聊天， CRM，Facebook Messenger 渠道 都是独立的模块，在前端检查一个模块是否安装：

models?seq_contains("contacts") -> models.contains("contacts")

判断权限

春松客服中，每个登录用户，都依据角色权限显示或控制读写，在 Pugjs 模板中检查权限：

user?? && (user.roleAuthMap["A02"]??  || user.admin) -> user && (user.roleAuthMap["A02"] || user.admin)

使用 for 而不是 each

for 和 each 都可以进行遍历，为了更好的可读性，只使用 for。

语法: https://pugjs.org/zh-cn/language/code.html

使用 unbuffered comment

Pugjs 中，注释应统一用 //- 这种，提升性能和减少不必要的信息。

根据条件赋予不同Class

Pugjs 中使用如下语法：

在行内，最前或最后如果有空格，不去掉

因为 Pugjs 处理空格有约定，在 Pug buffer 中，空格需要特别处理。

如果在一行的最前或最后，有空格，空格不去掉。比如

标签(空格1)(空格2)text(空格3) 

那么，这里空格1是规范，必须有，但是空格2和空格3，如果有，则不要去掉，这是故意留的。

尤其是用格式化工具，不要被格式化规则去掉。

语法：https://pugjs.org/language/plain-text.html#whitespace-control

尽量使用 if !

在 pug 中，unless 等同于 if !，但是从习惯上，if ! 更方便阅读，并且占用的代码更少，所以，还是多用 if !.

阅读 pug4j 使用的动态语言

de.neuland.pug4j 中，可以直接写 JavaScript，但实际上，该语言和 JavaScript 有着一些区别，比如常用的 length 函数，在 pug4j 中对应的是 size，pug4j 使用的真正语言是 jexl：

https://commons.apache.org/proper/commons-j/reference/syntax.html

标签属性，应尽量加入 , 分隔，, 可消除歧义, 规避错误

比如：

div(class='div-class' (click)='play()')

应写为：

div(class='div-class', (click)='play()')

语法：https://pugjs.org/language/attributes.html#quoted-attributes

IDEA 中开发 Pug 脚本

在 IDEA 中，打开任意 pug 文件，IDEA 提示安装插件，按照提示进行安装。

安装后，重启 IDEA。

格式化代码，快捷方式：

option + command + L

HTML 自动转化为 Pug 的工具

html2pug 转化工具
https://github.com/izolate/html2pug

转化后，检查，使用两列显示

使用 4 个空格作为缩进

春松客服中，Pugjs 文件使用 4 个空格缩进。
IDEA 中设置 Pug 如下：

设置如上，点击 “保存”。

IDEA 快捷方式

• 减少缩进
  针对一行，减少一个前面的缩进。

Shift + Tab

• 更新前端代码

Fn + Command + F9

Date 格式化

在春松客服中，有很多时间转化的需求，春松客服通过提供 filter 函数，统一为帮助类。
使用 pugHelper.formatDate(String pattern, Date value)

例如：

${user.lastlogintime?string("HH:mm:ss")} -> #{pugHelper.formatDate('HH:mm:ss', user.lastlogintime)}

pattern 语法和原来一致。

获得当前时间戳

pugHelper.currentTimeMillis()

字符串右对齐

使用 pugHelper.padRight(String input,String ch)

例如：

${((agentServicesAvg %(1000*60*60))/(1000*60))?string('00')} -> #{pugHelper.padRight(agentServicesAvg / (1000 * 60 * 60), "00")}

春松客服中的 layout

使用 extends 继承 layout 模板：

和原来用 freemarker 的关系：layout.pug 即原来的 tpl.html，content 即引用 tpl.html 的原 Freemarker 模版，其中，content 中也可以定义属于 body 的script。

script 模版标签处理

<script id="message_tpl" type="text/html"> 类型的标签是前端模版，不需要转换 pug.

处理方式：

1、内容比较长的单独创建 tpl文件，存放标签里的内容，不含标签

然后在pug里引用

2、内容比较短，不会影响IDE工作的

script#attributetext(type="text/html").
    <MeasureExpression>
    <SQL>
    (case when status = 'ready' then 1 else 0 end)
    </SQL>
    </MeasureExpression>

参考 contact-center/app/src/main/resources/templates/apps/agent/index.pug。

Pugjs 文件书写导致格式化错误

格式化：

如果但一行写成 h1.site-h1(style='background-color:#FFFFFF;')= tagType.name + '标签' + '(' + userList.totalElements + ')'，则会导致第二行格式化时，减少了一个单位的缩进。

使用下面则没有格式化问题

h1.site-h1(style='background-color:#FFFFFF;') #{tagType.name} 标签 (#{userList.totalElements})
   span(style='float:right;')

Pugjs 中使用 attributes 注意

Pug 文档里将的 https://pugjs.org/language/attributes.html

input(type='checkbox' checked=true && 'checked')  -转化为-> <input type="checkbox" checked="checked">

在 pug4j 不兼容，需要用如下句式：

input(type='checkbox' checked=(true ?'checked': false)) -->  <input type="checkbox" checked="checked">

不可复用的 mixin 放在文件最上面

这个 mixin 不太可能被其他页面使用的情况下，写在该页面内。
就写在前面，比 extend 优先级低。

生成 range

Pug 文档中 https://pugjs.org/zh-cn/language/code.html 有如下用法：

在 pug4j 的项目中不可用，会报错。需要改为:

  for x in pugHelper.range(1,24)

解决 Plug 文件编辑自动提示错误

如果在 Pugjs 中，IDEA 提示错误，但实际上不是语法错误，参考修改提示规则：
Jetbrains IDEA 中修正 Pugjs 文件编辑自动提示错误 | 春松客服

接下来

Pugjs 官网

Pugjs 中文站点

一山还有一山高，开源智能客服系统春松客服 v7 版本发布 | Chatopera

春松客服开发环境搭建

部署春松客服 v7 版本