工具模块
工具模块 util 是由工具类方法和小组件组成的集合。
示例
API
API
描述
var util = layui.util
获得 util 模块。
util.fixbar(options)
固定条组件
util.countdown(options)
倒计时组件
util.timeAgo(time, onlyDate)
某个时间在多久前
util.toDateString(time, format, options)
将毫秒数或日期对象转换成日期格式字符
util.digit(num, length)
数字前置补零
util.escape(str)
转义 HTML 字符
util.unescape(str)
还原 HTML 字符
util.openWin(options) 2.8+
打开浏览器新标签页
util.on(attr, events, options)
批量事件处理
倒计时
util.countdown(options);
参数 options 2.8.9+: 属性选项。可选项详见下表：
属性
描述
date
目标时间值。值可以为毫秒数或 Date 对象
now
当前时间值，一般为当前服务器时间。值可以为毫秒数或 Date 对象
ready
倒计时初始时的回调函数。
clock
倒计时计时中的回调函数，每秒触发一次，直到计时完成。
done
倒计时计时完成的回调函数，即到达目标时间值时触发
注： 2.8.9 之前的版本写法为：util.countdown(date, now, clock);
该方法返回的实例对象成员如下 2.8.9+：
var countdown = util.countdown(options);
countdown.clear(); // 清除当前倒计时
countdown.reload(options); // 重载当前倒计时。
countdown.timer; // 当前倒计时计时器 ID
相关用法可参考：#示例
layui.use('util', function(){
var util = layui.util;
// 示例
util.countdown({
date: '2099-1-1', // 目标时间值
now: new Date(), // 当前时间，一般为服务器时间，此处以本地时间为例
clock: function(obj, countdown){ // 计时中
console.log(obj); // 得到当前计时器的「天、时、分、秒」值
console.log(countdown); // 得到当前实例对象
},
done: function(obj, countdown){ // 计时完成
console.log('time is up');
}
});
});
某个时间在多久前
var result = util.timeAgo(time, onlyDate);
参数 time : 某个时间的毫秒数或日期对象
参数 onlyDate : 是否在超过 30 天后，只返回日期字符，而不返回时分秒
返回结果
若 time 在 3 分钟以内，返回： 刚刚
若 time 在 30 天以内，返回： 若干分钟前、若干小时前、若干天前，如：5 分钟前
若 time 在 30 天以上，返回： 日期字符，如： 2023-01-01
var result = util.timeAgo(1672531200000); // 2023-01-01 00:00:00
相关效果见：#示例
转换日期格式字符
var result = util.toDateString(time, format, options);
参数 time : 毫秒数或日期对象
参数 format : 日期字符格式。默认格式：yyyy-MM-dd HH:mm:ss 。可自定义，如： yyyy年MM月dd日
参数 options 2.8.13+ : 该方法的属性选项，详见下表：
属性名
描述
类型
默认值
customMeridiem
自定义 meridiem 格式
Function
-
var result = util.toDateString(1672531200000, 'yyyy-MM-dd'); // 2023-01-01
// 中括号中的字符会原样保留 2.8.13+
var result2 = util.toDateString(new Date('2023-01-01 11:35:25'), 'ss[s]'); // 25s
// 自定义 meridiem
var result3 = util.toDateString(
'2023-01-01 11:35:25',
'hh:mm:ss A',
{
customMeridiem: function(hours, minutes){
return (hours < 12 ? 'AM' : 'PM')
//.split('').join('.') // 有句点，A.M.
//.toLowerCase() // 小写，a.m.
}
}
); // 11:35:25 AM
参数 format 所有可用的格式列表 :
格式
示例
描述
yy 2.8.13+
23
年，两位数
yyyy
2023
年，四位数
M 2.8.13+
1-12
月
MM
01-12
月，两位数
d 2.8.13+
1-31
日
dd
01-31
日，两位数
H 2.8.13+
0-23
小时
HH
00-23
小时，两位数
h 2.8.13+
1-12
小时，12 小时制
hh 2.8.13+
01-12
小时，12 小时制，两位数
A 2.8.13+
凌晨/早上/上午/中午/下午/晚上
meridiem
m 2.8.13+
0-59
分钟
mm
00-59
分钟，两位数
s 2.8.13+
0-59
秒
ss
00-59
秒，两位数
SSS 2.8.13+
000-999
毫秒，三位数
数字前置补零
util.digit(num, length);
参数 num : 原始数字
参数 length : 数字长度，如果原始数字长度小于 length，则前面补零
该方法返回一个 string 类型的结果，如：
var rs1 = util.digit(6, 2); // "06"
var rs2 = util.digit(7, 3); // "007"
转义和还原 HTML
util.escape(str); 转义 HTML
util.unescape(str); 还原被转义的 HTML
参数 str : 任意 HTML 字符
var str1 = util.escape('
var str2 = util.unescape('<div>123</div>'); // 返回：
打开浏览器新标签页 2.8+
util.openWin(options);
参数 options : 属性选项。可选项详见下表
属性
描述
url
要打开页面 URL
target
打开页面的方式或窗口 name
content
打开的页面内容。若设置了 url 属性，则该属性无效
specs
窗口的相关配置，同 window.open() 的 specs
window
当前所在的窗口对象，默认 self
该方法基于原生 window.open() 的二次封装，以提升打开浏览器窗口的灵活性。
// 打开一个 url
util.openWin({
url: 'https://cn.bing.com'
});
// 打开一个自定义内容窗口
util.openWin({
content: 'Hello World.'
});
批量事件处理
util.on(attr, events, options);
参数
描述
类型
默认值
attr
触发事件的元素属性名。可省略2.9+
string
lay-on
events
事件集合。包含 attr 对应的属性值和事件回调函数的键值对
object
-
options 2.9+
参数的更多选项。详见下表。
object
-
参数 options 可选项:
options
描述
类型
默认值
elem
触发事件的委托元素
string | HTMLElement | JQuery
-
trigger
事件触发的方式
string
click