引言
前端 CSS 框架选用 BootStrap3 和 AdminLTE 作为管理框架为基础，JS 库采用 jQuery3 为核心框架，前端视图采用目前比较流行简单的 Beetl 模板引擎（使用 JS 语法，是我用过最好用，速度最快的后端模板引擎），取消了之前的JSP视图，为了减少耦合，并将所有视图文件分布到各个工程模块的资源目录下（如：/modules/core/src/main/resources/views/），JeeSite4 对 Beetl 做了一个强化，主要包括如下几点：
- 常用函数库，如：字符串工具类，集合工具类，映射转换工具类，配置工具类，权限用户工具类等；
- 封装常用表单控件参考Spring MVC的form标签，实现更便捷的输入框、下拉框等，自动进行数据绑定；
- 封装常用表单组件，如：多级树结构选择组件，列表选择组件，文件上传组件，验证码生成组件等等；
- 封装常用JS类库，如：动态加载，对话框，消息框，加载框，JS模板，Ajax，格式化，动态Tab等等；
- 封装JS数据表格DataGrid，分页，排序，多表头，分组，子表，冻结，小计，合计，编辑行，树表表格等；
- 提供丰富例子，如：Box盒子、表单布局、栅格布局、图表等等
更多资料：beetl 官方文档
模板语言界定符选择
Beetl模板语言类似JS语言和习俗，只需要将Beetl语言放入定界符号里即可，JeeSite使用jsp标准定界符<% %>来作为模板语言的定界符，一方同比较容易被理解，并明确是后端运行的语法，另一方面冲突少，比较好界定边界
举例一个通用布局的页面
<% layout('/layouts/default.html', {title: '菜单管理', libs: ['validate'], bodyClass: ''}){ %>
<div class="main-content">
<div class="box box-main">
<div class="box-header with-border">
<div class="box-title">
<i class="fa icon-book-open"></i> 菜单管理
</div>
<div class="box-tools pull-right">
<button type="button" class="btn btn-box-tool" data-widget="collapse"><i class="fa fa-minus"></i></button>
</div>
</div>
<div class="box-body">
</div>
<div class="box-footer">
</div>
</div>
</div>
<% } %>
调用默认布局 /layouts/default.html，自动引入页面头部和尾部内容，通过参数设置要加载的css和js类库，参数如下：
title参数： 设置页面的标题名字
libs参数： 设置页面要引入的css和js类库，支持类库如下：
默认引入：layer、laydate、select2
- zTree：树结构控件
- tabPage：动态页签插件
- dataGrid：数据表格组件
- validate：表单验证组件
- inputmask：表单格式化工具
- fileupload：文件上传插件
- ueditor：富文本编辑器控件
bodyClass参数： 设置body的class属性值
定义常用函数库
常用工具类导入
以下工具类可通过@类型快速调用，如：${@Global.getConfig(‘key’)}
- Global：全局配置类，全局常量，读取属性文件参数值等
- EncodeUtils：封装各种格式的编码解码工具类，HEX、Base64、HTML、URL、XSS过滤、SQL过滤等
- ListUtils：List常用工具类，继承Apache的ListUtils，New工具、快速提取属性值、类型转换等
- MapUtils：Map常用工具类，继承Apache的MapUtils，New工具、Map与Bean互转等
- SetUtils：Set常用工具类，继承Apache的SetUtils，New工具等
- IdGenerate：封装各种生成唯一性ID算法的工具类，生成LongUUID，StringUUID，Code生成等
- ByteUtils：字节转换工具
- DateUtils：日期工具类，继承Apache的DateUtils
- NumberUtils：BigDecimal工具类，继承Apache的NumberUtils类
- ObjectUtils：对象操作工具类，继承Apache的ObjectUtils类
- StringUtils：字符串工具类，继承Apache的StringUtils类
- TimeUtils：时间计算工具类，xx天xx时xx分xx秒，刚刚，xx秒，xx分钟，xx小时前、xx天前
- WorkDayUtils：工作日计算工具类，计算日期直接的工作日等
- BeanMapper：简单封装Dozer，对象数据映射
- JaxbMapper：Jaxb实现XML与Java Object的转换
- JsonMapper：简单封装Jackson，实现Json与Java Object的转换
- ClassUtils：Class扫描工具类，根据接口查询类，根据继承查询类等
- ReflectUtils：反射工具类，方便进行getter/setter方法, 访问私有变量, 调用私有方法
- ModuleUtils：模块工具类，方便获取系统模块信息，例如 ${@ModuleUtils.getModule(‘core’)}
- DictUtils：字典工具类，例如 ${@DictUtils.getDictListJson(‘sys_menu_type’)}
- UserUtils：用户工具类，方便获取进行用户及相关信息，例如 ${@UserUtils.getUser()}
- EmpUtils：员工工具类，获取当前用户员工信息、所在部门、公司，${@EmpUtils.getEmployee()}
- RoleUtils：角色工具类，判断当前或某用户是否包含某角色，${@RoleUtils.hasUserRole(‘user’,’role’)}
以下是Beetl函数及扩展函数
- date：返回一个java.util.Date类型的变量，如 date() 返回一个当前时间(对应java的java.util.Date); ${date( “2011-1-1” , “yyyy-MM-dd” )} 返回指定日期
- print：打印一个对象 print(user.name);
- println：打印一个对象以及回车换行符号，回车换号符号使用的是模板本身的，而不是本地系统的.如果仅仅打印一个换行符，则直接调用println() 即可
- nvl：函数nvl，如果对象为null，则返回第二个参数，否则，返回自己 nvl(user,”不存在”)
- isEmpty：判断变量或者表达式是否为空，变量不存在，变量为null，变量是空字符串，变量是空集合，变量是空数组，此函数都将返回true
- isNotEmpty：同上，判断对象是否不为空
- has：变量名为参数，判断是否存在此全局变量，如 has(userList),类似于1.x版本的exist(“userList”),但不需要输入引号了
- assert：如果表达式为false，则抛出异常
- trim：截取数字或者日期，返回字符,如trim(12.456,2)返回”12.45”,trim(date,’yyyyy’)返回”2017”
- trunc：截取数字，保留指定的小数位，如trunc(12.456,2) 输出是12.45.不推荐使用，因为处理float有问题，兼容原因保留了
- decode：一个简化的if else 结构，如 decode(a,1,”a=1”,2,”a=2”,”不知道了”)},如果a是1，这decode输出”a=1”,如果a是2，则输出”a==2”, 如果是其他值，则输出”不知道了”
- debug：在控制台输出debug指定的对象以及所在模板文件以及模板中的行数，如debug(1),则输出1 [在3行@/org/beetl/core/lab/hello.txt],也可以输出多个，如debug(“hi”,a),则输出hi,a=123,[在3行@/org/beetl/core/lab/hello.txt]
- range：接收三个参数，初始值，结束值，还有步增（可以不需要，则默认为1），返回一个Iterator，常用于循环中，如for(var i in range(1,5)) {print(i)},将依次打印1234.
- flush：强制io输出。
- pageCtx：仅仅在web开发中，设置一个变量，然后可以在页面渲染过程中，调用此api获取，如pageCtx(“title”,”用户添加页面”)，在其后任何地方，可以pageCtx(“title”) 获取该变量
- cookie：返回指定的cookie对象 ，如var userCook = cookie(“user”), allCookies = cookie();
- isBlank：判断对象是否是一个空字符串，${isBlank(‘str’)}
- isNotBlank：判断对象是否不是一个空字符串，${isBlank(‘str’)}
- toJson：将对象转Json字符串，${toJson(Object)}
- fromJson：将Json字符串转换为对象，${fromJson(Object)}
- hasPermi：判断是否有改权限；单个权限验证：${hasPermi(‘sys:user:edit’)}；多个AND关系：${hasPermi(‘sys:user:view,sys:user:edit’, ‘and’)}; 多个OR关系：${hasPermi(‘sys:user:view,sys:user:edit’, ‘or’)}
- cookie：获取cookie值，${cookie(name, isRemove)}
- lang: 获取当前国际化语言名称，例如：lang()，返回：zh_CN、en、等
- text: 获取当前国际化代码译文，例如：text(‘中国’)，当前语言英文状态下，返回：China；支持格式化参数，如:text(‘第{0}天’, 3)
数据类型格式化
日期格式化：
Today is ${date,dateFormat='yyyy-MM-dd'}
Today is ${date,dateFormat}
如果date为日期类型可简写：
${date,'yyyy-MM-dd'}
数值格式化：
Salary is ${salary,numberFormat='##.##'}
基本表单控件应用（类似 Spring MVC 表单标签)
form 表单标签
生成一个form标签，支持指定model属性，类似SpringMVC的<form:form modelAttribute=""/>标签的属性，自动给表单内的控件绑定属性值
<#form:form id="inputForm" model="${user}" action="${ctx}/sys/user" method="POST" class="form-horizontal">
表单内容
</#form:form>
支持上传文件：
<#form:form id="inputForm" model="${user}" action="${ctx}/sys/user" method="POST" enctype="multipart/form-data" class="form-horizontal">
表单内容
</#form:form>
控件属性：
var p = {
// 标签参数
id: id!, // 表单ID
model: model!, // 绑定Model对象，例如：${user!}
action: action!, // 表单请求地址
method: method!, // 请求方法，默认 post
enctype: enctype!, // 发送之前进行数据编码，上传文件时指定：multipart/form-data
// 以下3个属性是 path 属性的自动绑定参数，以下 form 组件只要包含 path 属性的都可以使用
xss: xss!false, // 是否对输出 value 进行 XSS 过滤
encodeHtml: encodeHtml!false, // 是否对输出 value 进行 HTML 编码
defaultValue: defaultValue!, // 如果未获得绑定值，则采用这个默认值输出到 value
};
input 输入框标签
自动绑定form:form上指定的model下的userName属性，类似SpringMVC的<form:input path=""/>标签的属性
<#form:input path="userName" maxlength="100" class="form-control required "/>
日期格式化：
<#form:input path="createDate" dataFormat="date" class="form-control "/>
数值格式化：
<#form:input path="createDate" dataFormat="number" class="form-control "/>
数值格式化（保留2位）：
<#form:input path="createDate" dataFormat="number2" class="form-control "/>
自定义格式化：
<#form:input name="field" value="${@DateUtils.formatDate(model.field,'yyyyMMdd')}" class="form-control "/>
<#form:input name="field" value="${${@NumberUtils.formatNumber(model.field,'0.0')}}" class="form-control "/>
不自动绑定，把 path 改为 name 就可以：
<#form:input name="field" value="${model.field}" class="form-control "/>
控件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
type: type!'text', // 元素的类型，默认text
dataFormat: dataFormat!'', // 数据格式化，支持如下值：
// date: 日期；默认值设置：defaultValue="${date()}"
// yyyy: 年；默认值设置：defaultValue="${date('2019','yyyy')}"
// yyyy-MM: 年月；默认值设置：defaultValue="${date('2019-11','yyyy-MM')}"
// datetime: 日期时间 yyyy-MM-dd HH:mm 格式化
// datetime2: 日期时间，带秒 yyyy-MM-dd HH:mm:ss 格式化
// 自定义日期 path 改为 name 加 value="${@DateUtils.formatDate(model.field,'yyyyMMdd')}}"
// number: 数值类型 #.## 格式化，默认值设置：defaultValue="${0}"
// number2: 数值类型 0.00 格式化，默认值设置：defaultValue="${0}"
// 自定义数值 path 改为 name 加 value="${@NumberUtils.formatNumber(model.field,'0.0')}}"
};
laydate 日期选择控件：
日期格式化（带日期选择控件）：
<#form:input path="createDate" dataFormat="date"
class="form-control laydate" data-type="date" data-format="yyyy-MM-dd"/>
<#form:input path="createDate" dataFormat="date"
class="form-control laydate" data-type="date" data-format="yyyy-MM-dd" />
日期范围选择（开始日期、结束日期）：
<#form:input path="testDate_gte" readonly="true" maxlength="20" class="form-control laydate width-date"
dataFormat="date" data-type="date" data-format="yyyy-MM-dd" data-done="testDate_lte.click()"/>
-
<#form:input path="testDate_lte" readonly="true" maxlength="20" class="form-control laydate width-date"
dataFormat="date" data-type="date" data-format="yyyy-MM-dd"/>
1、增加日期选择控件，class 增加 laydate
2、data-type 是格式化类型支持：year、month、date、time、datetime
3、data-format 是前端日期控件格式化参数，dataFormat 是后端实体属性格式化参数
4、data-done 相当于 laydate 的 done 选择日期完成后的一些操作
5、更多文档示例：https://www.layui.com/laydate/
使用 jquery.inputmask 格式化：
<% layout('/layouts/default.html', {libs: ['inputmask']}){ %>
<#form:input path="testInput_money" maxlength="200" class="form-control inputmask"
data-inputmask-alias="money" data-inputmask="'digits':'2'"/>
<% } %>
<script>
$("#inputForm").validate({
submitHandler: function(form){
// 数据格式化恢复（表单提交之前调用）
$('.inputmask').inputmask('remove');
// 提交表单
js.ajaxSubmitForm($(form), function(data){
js.showMessage(data.message);
if(data.result == Global.TRUE){
js.closeCurrentTabPage(function(contentWindow){
contentWindow.page();
});
}
}, "json");
// 数据格式化（初始化完成表单后调用）
$(".inputmask").inputmask();
}
});
//数据格式化（初始化完成表单后调用）
$(".inputmask").inputmask();
</script>
更多文档示例：https://www.baidu.com/s?wd=jquery.inputmask
select 下拉框标签
根据字典类型设置下拉数据：
<#form:select path="userType" dictType="sys_user_type" class="form-control required " />
增加一个空白选项：
<#form:select path="roleType" dictType="sys_role_type" blankOption="true" class="form-control " />
<#form:select path="roleType" dictType="sys_role_type" blankOption="true" blankOptionLabel="请选择" class="form-control " />
多选下拉列表：
<#form:select path="roleType" dictType="sys_role_type" multiple="true" class="form-control " />
后台赋值：model.addAttribute("moduleList", new List<Module>())，类似SrpingMVC的<form:options items="" />：
<#form:select path="moduleCodes" items="${moduleList}" itemLabel="moduleName" itemValue="moduleCode" class="form-control required" />
在视图上直接赋值：
<% var items = [{label:'是',value:'1'},{label:'否',value:'0'},{label:'禁用选项',value:'2',status:'2'}]; %>
<#form:select path="field" items="${items}" itemLabel="label" itemValue="value" class="form-control required" />
该组件使用 jQuery Select2 美化，常用操作举例如下：
$('#userType').val(); // 取值方式1
$('#userType').select2('val'); // 取值方式2
$('#userType').val('employee').trigger('change'); // 赋值方式1
$('#userType').select2('val', 'employee'); // 赋值方式2
$('#userType').select2(); // 重新初始化
更多文档详见：https://jeesite.gitee.io/front/jquery-select2/4.0/options.htm
控件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
dictType: dictType!, // 字典类型，从字典里获取，自动设置items、itemLabel、itemValue
// 字典类型加 __all（双下划线+all） 后缀，则显示停用的字典 v4.2.0
items: items![], // 列表数据，可接受对象集合，如：List<DictData>
itemLabel: itemLabel!'', // 指定列表数据中的什么属性名作为option的标签名
itemValue: itemValue!'', // 指定列表数据中的什么属性名作为option的value值
itemStatus: itemStatus!'', // option 的 disabled，如果是字符串类型（0正常,!0禁用）v4.2.0
multiple: multiple!'false', // 是否为多选框
readonly: toBoolean(readonly!false), // 是否只读模式 v4.1.7
blankOption: toBoolean(blankOption!false), // 是否默认有个空白选择项目
blankOptionValue: blankOptionValue!'', // 给空白选择项目设置一个值，默认：空字符串 v4.2.0
blankOptionLabel: blankOptionLabel!' ', // 给空白选择项目设置一个标签，如：请选择、全部
// data-placeholder: '请选择人员信息', // 下拉选择框的提示信息
};
radio 单选框标签
类似<#form:select/>标签的使用方法
<#form:radio path="menuType" dictType="sys_menu_type" class="form-control required" />
该组件使用 iCheck 美化，常用操作举例如下：
$('#menuType').iCheck('check'); // 修改为选择状态
$('#menuType').iCheck('uncheck'); // 修改为非选择状态
$('#menuType').iCheck('toggle'); // 选择和非选择状态之间切换
$('#menuType').iCheck('disable'); // 禁用选择框
$('#menuType').iCheck('enable'); // 启用选择框
$('#menuType').iCheck('update'); // 刷新选择状态
$('#menuType input:radio:checked').val();// 取值
// 选中事件
$('#menuType').on('ifChecked', function(){ });
// 取消选中事件
$('#menuType').on('ifUnchecked', function(){ });
// 单击选择框事件
$('#menuType').on('ifClicked', function(){ });
更多文档详见：https://jeesite.gitee.io/front/icheck/demo/index.html
控件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
dictType: dictType!, // 字典类型，从字典里获取，自动设置items、itemLabel、itemValue
items: items!([]), // 列表数据，可接受对象集合，如：List<DictData>
itemLabel: itemLabel!'', // 指定列表数据中的什么属性名作为option的标签名
itemValue: itemValue!'', // 指定列表数据中的什么属性名作为option的value值
readonly: toBoolean(readonly!false), // 是否只读模式 v4.2.0
blankOption: toBoolean(blankOption!false), // 是否默认有个空白选择项目 v4.2.0
blankOptionValue: blankOptionValue!'', // 给空白选择项目设置一个值，默认：空字符串 v4.2.0
blankOptionLabel: blankOptionLabel!'全部', // 给空白选择项目设置一个标签，如：请选择、全部 v4.2.0
};
checkbox 复选框标签
类似<#form:select/>标签的使用方法
<#form:checkbox path="menuType" dictType="sys_menu_type" class="form-control required" />
后台接受moduleCodes为字符串，选择多个自动使用“,”分隔，相比SpringMVC必须是List方便的多
<#form:checkbox path="moduleCodes" items="${moduleList}" itemLabel="moduleName" itemValue="moduleCode" class="form-control required" />
生成一个复选框按钮，后台接受 replaceFile 为 Global.YES 或 Global.NO 字符串类型的值
<#form:checkbox path="replaceFile" label="是否替换现有文件" class="form-control"/>
该组件使用 iCheck 美化，常用操作举例如下：
$('#menuType').iCheck('check'); // 修改为选择状态
$('#menuType').iCheck('uncheck'); // 修改为非选择状态
$('#menuType').iCheck('toggle'); // 选择和非选择状态之间切换
$('#menuType').iCheck('disable'); // 禁用选择框
$('#menuType').iCheck('enable'); // 启用选择框
$('#menuType').iCheck('update'); // 刷新选择状态
$('#menuType input:checkbox:checked').each(function(i,v){
log($(this).val()) // 取值
});
// 选中事件
$('#menuType').on('ifChecked', function(){ });
// 取消选中事件
$('#menuType').on('ifUnchecked', function(){ });
// 单击选择框事件
$('#menuType').on('ifClicked', function(){ });
更多文档详见：https://jeesite.gitee.io/front/icheck/demo/index.html
控件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
dictType: dictType!'', // 字典类型，从字典里获取，自动设置items、itemLabel、itemValue
items: items!([]), // 列表数据，可接受对象集合，如：List<DictData>
itemLabel: itemLabel!'', // 指定列表数据中的什么属性名作为option的标签名
itemValue: itemValue!'', // 指定列表数据中的什么属性名作为option的value值
label: label!, // 只有一个复选按钮的情况下设置
readonly: toBoolean(readonly!false), // 是否只读模式 v4.2.0
};
textarea 文本域标签
<#form:textarea path="remarks" rows="3" maxlength="200" class="form-control"/>
控件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
};
hidden 隐藏域标签
<#form:hidden path="menuCode" />
控件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
type: type!'hidden', // 元素的类型，默认hidden
};
高级表单组件封装应用
treeselect 树结构选择
封装layer+zTree实现树结构选择组件，使用场景如：部门选择，行政区划选择，栏目列表选择等
用户选择：
<#form:treeselect id="testUser" title="用户选择" path="testUser.userCode" labelPath="testUser.userName"
url="${ctx}/sys/office/treeData?isLoadUser=true" class="" allowClear="true"/>
用户多选：
<#form:treeselect id="testUser2" title="用户选择" path="testUser.userCode" labelPath="testUser.userName"
url="${ctx}/sys/office/treeData?isLoadUser=true" class="" allowClear="true" checkbox="true"/>
机构选择：
<#form:treeselect id="testOffice" title="机构选择"
path="testOffice.officeCode" labelPath="testOffice.officeName"
url="${ctx}/sys/office/treeData" class="" allowClear="true"/>
区域选择（异步加载）：
<#form:treeselect id="testAreaCode" title="区域选择" path="testAreaCode" labelPath="testAreaName"
url="${ctx}/sys/area/treeData?parentCode=0" class="" allowClear="true"/>
字典树选择：
<#form:treeselect id="parent" title="选择字典" path="userCode" labelPath="userName"
url="${ctx}/sys/dictData/treeData?dictType=字典类型" class="" allowClear="true"/>
菜单选择（允许清理、允许选择根节点、允许选择父节点）：
<#form:treeselect id="parent" title="菜单选择" path="parent.id" labelPath="parent.menuNameOrig"
url="${ctx}/sys/menu/treeData?excludeCode=${menu.menuCode}&sysCode=${menu.sysCode}&isShowNameOrig=true"
class="" allowClear="true" canSelectRoot="true" canSelectParent="true"/>
组件属性：
var p = {
// 标签参数
id: id!, // 元素ID
path: path!, // 绑定form上model中属性的值
name: name!, // 隐藏域名称
value: value!, // 隐藏域值
defaultValue: defaultValue!,// 隐藏域默认值 v4.1.5
labelPath: labelPath!, // 绑定form上model中属性的值
labelName: labelName!, // 标签框名称
labelValue: labelValue!, // 标签框值
defaultLabel: defaultLabel!,// 标签框默认值 v4.1.5
class: class!'', // 标签框的CSS类名
placeholder: placeholder!, // 标签框的预期值的提示信息
dataMsgRequired: thisTag.attrs['data-msg-required'], // 必填错误提示信息
btnClass: btnClass!, // 标签框后面的按钮CSS类名
title: title!text('选项选择'), // 对话框标题
boxWidth: boxWidth!300, // 对话框宽度，默认300像素
boxHeight: boxHeight!400, // 对话框高度，默认400像素
url: url!, // 树结构，数据源地址 [{id, pid, name}]
readonly: toBoolean(readonly!false), // 是否只读模式
allowInput: toBoolean(allowInput!false), // 是否允许label框输入
allowClear: toBoolean(allowClear!true), // 是否允许清空选择内容
checkbox: toBoolean(checkbox!false), // 是否显示复选框，是否支持多选，如果设置canSelectParent=true则返回父节点数据
chkboxType: chkboxType!'', // 复选框级联选择规则 v4.0.6，默认：{'Y':'ps','N':'ps'}
expandLevel: @ObjectUtils.toInteger(expandLevel!(-1)), // 默认展开层次级别（默认:如果有1个根节点，则展开一级节点，否则不展开）
canSelectRoot: toBoolean(canSelectRoot!false), // 可以选择跟节点
canSelectParent: toBoolean(canSelectParent!false), // 可以选择父级节点
isReturnValue: isReturnValue!'false', // 是否返回树结构的value值，而不是返回id（默认id）
returnFullName: toBoolean(returnFullName!false), // 是否返回全路径，包含所有上级信息，以 returnFullNameSplit 参数分隔
returnFullNameSplit: returnFullNameSplit!'/', // 是否返回全路径，的分隔符，默认“/”
openFuncName: openFuncName!'treeselectOpen', // 可自定义弹窗前调用的函数名 v4.2.0
checkFuncName: checkFuncName!'treeselectCheck', // 可自定义验证方法的函数名 v4.1.5
callbackFuncName: callbackFuncName!'treeselectCallback', // 可自定义回调方法的函数名 v4.1.0
};
JS回调事件：
/**
* 选择前调用，数据验证函数，返回false代表验证失败
* @param id 标签的id
* @param node 验证的数据
* @return true 验证成功，false 验证失败
*/
function treeselectCheck(id, nodes){
if (id == 'parent'){
log(nodes); // 选择的节点数据
js.showMessage('验证失败提醒！');
return false; // 验证失败，阻止关闭
}
return true; // 验证成功
}
/**
* 选择回调方法
* @param id 标签的id
* @param act 动作事件：ok、clear、cancel
* @param index layer的索引号
* @param layero layer内容的jQuery对象
* @param nodes 当前选择的树节点数组
*/
function treeselectCallback(id, act, index, layero, nodes){
if (id == 'parent' && (act == 'ok' || act == 'clear')){
var win = layero.iframeWindow();
log(win); // 选择框内容的window对象
log(act); // 回调活动事件（ok、clear、cancel）
log(index); // layer的index
log(layero); // layer实例对象
log(selectData); // 选择的节点数据
log(nodes); // 选择的节点数据
}
}
/**
* 弹出对话框前调用 v4.2.0
* @param id 标签的id
* @param options 弹窗选项
* @return 返回 false 则不弹框，直接返回
*/
function treeselectOpen(id, options){
if (id == 'parent'){
log(options);
}
}
listselect 列表选择
用户列表选择：
<#form:listselect id="testUser3" title="用户选择"
path="testUser.userCode" labelPath="testUser.userName"
url="${ctx}/sys/empUser/empUserSelect" allowClear="false"
checkbox="false" itemCode="userCode" itemName="userName"/>
用户列表多选：
<#form:listselect id="testUser4" title="用户选择"
path="testUser.userCode" labelPath="testUser.userName"
url="${ctx}/sys/empUser/empUserSelect" allowClear="false"
checkbox="true" itemCode="userCode" itemName="userName"/>
用户选择（不含组织机构）：
<#form:listselect id="userSelect" title="用户"
path="testUser.userCode" labelPath="testUser.userName"
url="${ctx}/sys/user/userSelect?userType=employee" allowClear="false"
checkbox="false" itemCode="userCode" itemName="userName"/>
组件属性：
var p = {
// 标签参数
id: id!, // 元素ID
path: path!, // 绑定form上model中属性的值
name: name!, // 隐藏域名称
value: value!, // 隐藏域值
defaultValue: defaultValue!,// 隐藏域默认值 v4.1.5
labelPath: labelPath!, // 绑定form上model中属性的值
labelName: labelName!, // 标签框名称
labelValue: labelValue!, // 标签框值
defaultLabel: defaultLabel!,// 标签框默认值 v4.1.5
class: class!'', // 标签框的CSS类名
placeholder: placeholder!, // 标签框的预期值的提示信息
dataMsgRequired: thisTag.attrs['data-msg-required'], // 必填错误提示信息
btnClass: btnClass!, // 标签框后面的按钮CSS类名
title: title!'选项', // 对话框标题
boxWidth: boxWidth!'$(top.window).width() - 100', // 对话框宽度
boxHeight: boxHeight!'$(top.window).height() - 100', // 对话框高度
url: url!, // 列表地址，参考EmpUserController的empUserSelect方法
readonly: toBoolean(readonly!false), // 是否只读模式
allowInput: toBoolean(allowInput!false), // 是否允许label框输入
allowClear: toBoolean(allowClear!true), // 是否允许清空选择内容
checkbox: toBoolean(checkbox!false), // 是否显示复选框，是否支持多选，如果设置canSelectParent=true则返回父节点数据
itemCode: itemCode!, // 选择后结果集中的Code属性名，返回到隐藏域的值
itemName: itemName!, // 选择后结果集中的Name属性名，返回到输入框的值
getSelectDataFuncName: getSelectDataFuncName!'listselectGetSelectData', // 选择页面，获取已经选择的数据，回显到选择页面 v4.1.5
setSelectDataFuncName: setSelectDataFuncName!'listselectSetSelectData', // 选择之后，点击确定，将选择数据设置到业务表单 v4.2.0
openFuncName: openFuncName!'listselectOpen', // 可自定义弹窗前调用的函数名 v4.2.0
checkFuncName: checkFuncName!'listselectCheck', // 可自定义验证方法的函数名 v4.2.0
callbackFuncName: callbackFuncName!'listselectCallback', // 可自定义回调方法的函数名 v4.1.5
};
JS回调事件：
/**
* 选择前调用，数据验证函数，返回false代表验证失败
* @param id 标签的id
* @param selectData 当前选择列表的数据MAP
* @return true 验证成功，false 验证失败
*/
function listselectCheck(id, selectData){
if (id == 'parent'){
log(selectData); // 选择的节点数据
js.showMessage('验证失败提醒！');
return false; // 验证失败，阻止关闭
}
return true; // 验证成功
}
/**
* 选择框回调方法
* @param id 标签的id
* @param act 动作事件：ok、cloear、cancel
* @param index layer的索引号
* @param layero layer内容的jQuery对象
* @param selectData 当前选择列表的数据MAP
*/
function listselectCallback(id, act, index, layero, selectData){
if (id == 'parent' && (act == 'ok' || act == 'clear')){
var win = layero.iframeWindow();
log(win); // 选择框内容的window对象
log(act); // 回调活动事件（ok、clear、cancel）
log(index); // layer的index
log(layero); // layer实例对象
log(selectData); // 选择的节点数据
}
}
/**
* 弹出对话框，列表数据回显调用方法
* @param id 标签的id
* @return selectData 当前选择列表的数据MAP
*/
function listselectGetSelectData(id){
var selectData = {};
if (id == 'parent' && (act == 'ok' || act == 'clear')){
selectData['主键字段值'] = {行数据};
}
return selectData;
}
/**
* 选择后，设置到业务表单调用方法 v4.2.0
* @param id 标签的id
* @param selectData 当前选择列表的数据MAP
*/
function listselectSetSelectData(id, selectData){
if (id == 'parent'){
log(selectData);
}
}
/**
* 弹出对话框前调用 v4.2.0
* @param id 标签的id
* @param options 弹窗选项
* @return 返回 false 则不弹框，直接返回
*/
function listselectOpen(id, options){
if (id == 'parent'){
log(options);
}
}
iconselect 图标选择
<#form:iconselect path="menuIcon" class=""/>
组件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
class: class!'', // 隐藏域和标签框的CSS类名
};
validcode 验证码
<#form:validcode name="validCode" isRequired="true" isRemote="true" />
组件属性：
var p = {
id: id!name, // 验证码输入框ID
name: name!, // 验证码输入框名称（必填）
isRequired: toBoolean(isRequired!true), // 是否必填，默认必填
dataMsgRequired: thisTag.attrs['data-msg-required'], // 必填错误提示信息
isRemote: toBoolean(isRemote!true), // 是否支持实时远程验证
dataMsgRemote: thisTag.attrs['data-msg-remote'], // 必填错误提示信息
isLazy: toBoolean(isLazy!false), // 是否懒加载验证码图片，原noRefresh参数
isShowLabel: toBoolean(isShowLabel!true), // 是否显示“验证码”标签，默认true（V4.0.5）
};
fileupload 文件上传
<% layout(... libs: ['fileupload'] ...}){ %>
1、文件上传：
<#form:fileupload id="upload1" bizKey="${user.id}" bizType="user_upload1"
uploadType="all" class="required" readonly="false"/>
后台代码：FileUploadUtils.saveFileUpload(user.getId(), "user_upload1");
2、图片上传：
<#form:fileupload id="upload2" bizKey="${user.id}" bizType="user_upload2"
uploadType="image" class="required" readonly="false"/>
后台代码：FileUploadUtils.saveFileUpload(user.getId(), "user_upload2");
3、返回路径：
<#form:fileupload id="upload3" returnPath="true"
filePathInputId="upload3Path" fileNameInputId="upload3Name"
uploadType="image" readonly="false" maxUploadNum="3" isMini="false"/>
<#form:input path="upload3Path" class="form-control"/>
<#form:input path="upload3Name" class="form-control"/>
4、在线文件预览（增加 preview="true" 属性, 4.2之前版本：preview="weboffice"）：
<#form:fileupload id="upload4" bizKey="${user.id}" bizType="user_upload4"
uploadType="all" class="required" readonly="false" preview="true"/>
5、支持指定文件查询地址，如 bizKey 右模糊查询数据，适应 parentBizKey 的场景（v4.1.5）：
<#form:fileupload id="upload5" bizKey="${entity.parentCode}_" bizType="upload5"
uploadType="all" class="" readonly="true" preview="true"
serviceFileList="${ctxAdmin}/file/fileList?bizKeyIsLike=true"/>
注意：为什么没有保存 bizKey 和 bizType 值到后台，因为在上传文件的时候，新增的表单还没有生成主键，当你点击表单保存后，后台代码调用 FileUploadUtils.saveFileUpload 更新这两个值，才会真正建立文件和业务数据的关系。
若出现上传文件按钮点击无效的情况，可能是因为你的fileupload控件隐藏或控件的top位置改变造成的， 你只需在显示隐藏控件后或onload事件后执行如下代码刷新按钮位置即可：
if (typeof window.webuploaderRefresh == 'function'){
window.webuploaderRefresh();
}
举例：Bootstrap Tab 切换代码
$(function(){
$('a[data-toggle="tab"]').on('shown.bs.tab', function (e) {
if(typeof window.webuploaderRefresh == 'function'){
window.webuploaderRefresh();
}
});
});
重载文件数据
// 刷新文件列表（重载“业务关联”的文件列表）
$('#upload1Uploader').webuploader('refreshFileListByBizData');
// 刷新文件列表（重载“返回路径”方式指定的input文件列表）
$('#upload1Uploader').webuploader('refreshFileListByPath');
注意：upload1Uploader 格式为 id+Uploader。别忘加 Uploader 后缀。
组件属性：
var p = {
// 标签参数
id: id!, // 元素ID
bizKey: bizKey!, // 业务表的主键值（与附件关联的业务数据）
bizType: bizType!, // 业务表的上传类型（全网唯一，推荐格式：实体名_上传类型，例如，文章图片：article_photo）
returnPath: toBoolean(returnPath!false), // 是否是返回文件路径到输入框（默认false），可将路径直接保存到某个字段里
filePathInputId: filePathInputId!, // 设置文件URL存放的输入框的ID，当returnPath为true的时候，返回文件URL到这个输入框
fileNameInputId: fileNameInputId!, // 设置文件名称存放的输入框的ID，当returnPath为true的时候，返回文件名称到这个输入框
uploadType: uploadType!'', // 上传文件类型：all、file、image、media，若不设置，则自动根据上传文件后缀获取
class: class!'', // 标签框的CSS类名，设置 required 加入必填验证
readonly: toBoolean(readonly!false), // 是否只读模式，只读模式下为查看模式，只允许下载
allowSuffixes: allowSuffixes!'', // 允许上传的后缀，前台的限制，不能超越file.*AllowSuffixes的设置，例如：.jpg,.png,
maxFileSize: maxFileSize!'', // 当前控件的文件上传大小设置（500*1024*1024）单位字节，不可超过配置文件设置的文件大小
maxUploadNum: @ObjectUtils.toInteger(maxUploadNum!300), // 多文件下允许最多上传几个，默认300个，设置-1代表不限制
cueWords: cueWords!'', // 提示语，默认：或将照片(文件)拖到这里，最多可选 maxUploadNum 张(个) v4.1.5
imageMaxWidth: @ObjectUtils.toInteger(imageMaxWidth!1024), // 图片压缩，最大宽度（uploadType为image生效），设置-1代表不做任何处理
imageMaxHeight: @ObjectUtils.toInteger(imageMaxHeight!768), // 图片压缩，最大宽度（uploadType为image生效），设置-1代表不做任何处理
serviceUpload: serviceUpload!(ctxAdmin+'/file/upload'), // 上传文件后台服务 v4.1.5
serviceDownload: serviceDownload!(ctxAdmin+'/file/download/'), // 下载文件后台服务 v4.1.5
serviceFileList: serviceFileList!(ctxAdmin+'/file/fileList'), // 查询文件后台服务 v4.1.5
extendParams: extendParams!'', // 提交的上传扩展参数，例如：n1:'v1',n2:'v2'，后台接受：fileEntity.getFileUploadParams().getExtend() v4.1.3
isLazy: toBoolean(isLazy!false), // 设置为ture需要点击上传按钮才上传文件，否则选择后就直接上传
isMini: toBoolean(isMini!false), // 是否是精简上传窗口，无边距，无边框
preview: preview!'', // 是否显示预览按钮，接受参数：v4.2.0 之前版本为 weboffice，之后版本为 true，可根据需要扩展预览引擎
callbackFuncName: callbackFuncName!'fileuploadCallback', // 可自定义回调方法的函数名 v4.1.8+ v4.2.0+
};
后台 FileUploadUtils API：
/**
* 保存上传附件与业务的关系
* @param bizKey 业务主键
* @param bizType 业务类型
* @example
* // 保存上传的附件
* FileUploadUtils.saveFileUpload(testData.getId(), "test_data_field1");
*/
public static void saveFileUpload(String bizKey, String bizType);
/**
* 保存上传附件与业务的关系
* @param bizKey 业务主键
* @param bizType 业务类型
* @param fileUploadIds 对应的上传文件编码
* @param delFileUploadIds 对应的上传文件需要删除的编码
*/
public static void saveFileUpload(String bizKey, String bizType,
String fileUploadIds, String delFileUploadIds);
/**
* 查询业务关系的上传附件
* @param bizKey 业务主键
* @param bizType 业务类型
*/
public static List<FileUpload> findFileUpload(String bizKey, String bizType);
WebUploader 支持事件绑定，可用于回调。
$(function(){
var uploader = window.webuploader[0];
uploader.on('all', function(type, file) {
log(type)
log(file)
});
});
/**
* 上传组件回调 v4.2.0
* @param id 标签的id
* @param act 动作事件：create、ready、addFile、delFile
* @param $this webuploader 组件对象
* @param fileUpload 添加文件时的数据 v4.2.2
* /
function fileuploadCallback(id, act, $this, fileUploadId, fileUrl, fileName, fileUpload){
log(id + ' ' + act + ' ' + fileUploadId + ' ' + fileUrl + ' ' + fileName)
if (act == 'addFile') { log(fileUpload); }
log($this)
}
手机端上传附件：如果你采用html5混合模式开发，你可解压 jeesite-framework.jar 并将 /static/webuploader 文件夹拷贝到你的手机端APP里面，可删掉 swf 和其它用不到的文件。然后在你的对应页面引入 webuploader.css、webuploader.extend.css、webuploader.extend.js、webuploader.js（v4.1.1下可引入webuploader.mobile.js）等文件，其它依赖文件也要引入，如：jquery-3.5.0.min.js、bootstrap.min.css、jeesite.js、jeesite_zh_CN.js。接下来，随便在PC后端beetl视图页面里加入如下代码：
<#form:fileupload id="uploadImage" bizKey="当前业务主键" bizType="当前业务类型_image" uploadType="image"
class="" readonly="false" isMini="true"/>
通过Chrome浏览器访问这个控制器视图，空白处右键“查看当前框架页面的源代码”，搜索 class="wup_container 拷贝该div和紧挨着下方的script标签内容到你的手机页面，修改对应fileupload接受参数即可。
若你是原生开发： 还请参照此控件自己实现上传UI即可，参照方法： 浏览器 F12 打开 network 监控，监控请求路径及数据，共分为2次请求：
- 第一次发送文件的MD5码（10M部分，不足10M取全部），后台返回result结果。生成MD5方法，例如：Md5Utils.md5File(file, 0, 10 * 1024 * 1024);
- result为true，则代表已经上传过，并返回 fileUpload 数据，并放到 bizType 命名的隐藏域中。
- result为false，则待办未上传过，还请你根据F12监控到的数据，需要你第二次发送上传文件请求。
- 提交表单时，请将 bizType 隐藏域和 bizType__del 隐藏域提交到后台。（重要）
- 后台通过 FileUplandUtils 接受到该值并文件与当前表单主键建立关系。
- 接口测试（可以导入Postman）：https://gitee.com/thinkgem/jeesite4/attach_files/249363/download
如何将文件上传到云存储？
请看对象存储专题：对象存储 MinIO、阿里云、腾讯云、七牛云
imageclip 图片裁剪
<img id="avatarImg" class="profile-user-img img-responsive img-circle"
src="${@user.getAvatarUrl().replaceFirst('/ctxPath', ctxPath)}">
<#form:imageclip name="imageBase64" btnText="修改头像" btnClass="btn-block"
imageId="avatarImg" imageDefaultSrc="${ctxStatic+'/images/user1.jpg'}"
circle="true"/>
后台代码：
// 如果设置了头像，则保存头像
if (StringUtils.isNotBlank(imageBase64)){
if ("EMPTY".equals(imageBase64)){
user.setAvatar(StringUtils.EMPTY);
}else{
String imageUrl = "avatar/"+user.getUserCode()
+"."+FileUtils.getFileExtensionByImageBase64(imageBase64);
String fileName = Global.getUserfilesBaseDir(imageUrl);
FileUtils.writeToFileByImageBase64(fileName, imageBase64);
user.setAvatar(Global.USERFILES_BASE_URL + imageUrl);
}
}
组件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
class: class!'', // 隐藏域的CSS类名
btnText: btnText!text('选择图片'), // 按钮的名字
btnClass: btnClass!'', // 按钮的CSS类名
imageId: imageId!'', // 裁剪后base64返回到img的id
imageDefaultSrc: imageDefaultSrc!'', // 图片默认地址，清除后使用地址
ratio: ratio!'1/1', // 图片裁剪比例 v4.1.7
circle: circle!'false', // 是否圆形图片
};
ueditor 富文本在线编辑器
<% layout(... libs: ['ueditor'] ...}){ %>
<#form:ueditor name="text" maxlength="10000" height="200" class="required"
simpleToolbars="false" readonly="false" outline="false"/>
组件属性：
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
class: class!'', // 标签框的CSS类名，设置 required 加入必填验证
maxlength: maxlength!'', // 编辑器最大输入字数，为空代表无限制
height: height!'200', // 编辑器的高度，默认200
simpleToolbars: toBoolean(simpleToolbars!false), // 是否是简单的工具条
readonly: toBoolean(readonly!false), // 是否只读模式
outline: toBoolean(outline!false), // 大纲视图
options: options!'', // UE附加选项，逗号隔开。
};
注意：如果需要将文件上传到其它文件服务，重写 jeesite-common 项目下的 StorageManager 类 uploadFileSuccess 方法即可。
自定义 form 标签组件
标签都需要放到指定目录下：
/src/main/resources/views/htmltags/
举例一个 form:input 组件的实现:
/src/main/resources/views/htmltags/form/input.html
组件内容如下：
<%/* Copyright (c) 2013-Now http://jeesite.com All rights reserved. */
/**
* 表单控件：输入框
* @author ThinkGem
* @version 2017-3-5
*/
var p = {
// 标签参数
id: id!, // 元素ID，如果不填写，则与name相同
path: path!, // 绑定form上model中属性的值
name: name!, // 元素名称，不填写
value: value!, // 元素值
defaultValue: defaultValue!,// 默认值 v4.1.5
type: type!'text', // 元素的类型，默认text
dataFormat: dataFormat!'', // 数据格式化
// 内置参数
thisTag: thisTag,
exclAttrs: ['id', 'path', 'name', 'value', 'defaultValue', 'type', 'dataFormat']
};
// 编译绑定参数
form.path(p);
// 数据格式化
var df = '';
if (p.dataFormat == 'date'){
df = { %> value="${p.value,dateFormat='yyyy-MM-dd'}"<% };
}else if (p.dataFormat == 'datetime'){
df = { %> value="${p.value,dateFormat='yyyy-MM-dd HH:mm'}"<% };
}else if (p.dataFormat == 'number'){
df = { %> value="${p.value,numberFormat='#.##'}"<% };
}else{
df = { %> value="${p.value}"<% };
}
p.attrs = p.attrs!'' + df;
// 编译属性参数
form.attrs(p);
%><input type="${p.type}" id="${p.id}" name="${p.name}"${p.attrs}/>
表单内置验证名称
(function ($) {
$.extend($.validator.messages, {
required: "必填信息",
remote: "请修正该信息",
email: "请输入正确格式的电子邮件",
url: "请输入合法的网址",
date: "请输入合法的日期",
dateISO: "请输入合法的日期 (YYYY-MM-DD).",
number: "请输入合法的数值",
digits: "请输入一个正整数",
equalTo: "请再次输入相同的值",
maxlength: $.validator.format("最多可以输入 {0} 个字符"),
minlength: $.validator.format("最少要输入 {0} 个字符"),
rangelength: $.validator.format("请输入长度在 {0} 到 {1} 之间的字符串"),
range: $.validator.format("请输入范围在 {0} 到 {1} 之间的数值"),
max: $.validator.format("请输入不大于 {0} 的数值"),
min: $.validator.format("请输入不小于 {0} 的数值"),
errorMessage: "您填写的信息有误，请根据提示修正。",
userName: "登录账号只能包括中文字、英文字母、数字和下划线",
realName: "姓名只能为2-30个汉字",
abc: "请输入字母数字或下划线",
noEqualTo: "请再次输入不同的值",
mobile: "请正确填写您的手机号码，只能是13,14,15,16,17,18,19号段",
simplePhone: "请正确填写您的电话号码，固话为区号(3-4位)号码(7-9位)",
phone: "请正确填写您的电话号码，固话为区号(3-4位)号码(7-9位),手机为13,14,15,16,17,18,19号段",
zipCode: "请正确填写您的邮政编码",
integer: "请输入一个整数",
ipv4: "请输入一个有效的 IP v4 地址",
ipv6: "请输入一个有效的 IP v6 地址",
qq: "请正确填写您的QQ号码",
idcard: "请输入正确的身份证号码(15-18位)"
});
}(jQuery));
扩展自定义验证：
// 手机号码验证
jQuery.validator.addMethod("mobile", function(value, element) {
var tel = /^1[3,4,5,6,7,8,9]\d{9}$/g;
return this.optional(element) || (tel.test(value));
}, $.validator.messages.mobile);
