引言
前端 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);