Appearance
formatTime转换时间
Hidden Title
基础用法：
formatTime(new Date())基础用法
说明
formatTime 用于把 Date、时间戳或日期字符串格式化成指定模板的时间文本。它支持秒级时间戳、毫秒级时间戳、ISO 字符串、普通日期字符串，并提供非法日期兜底返回值。
调用形式
ts
formatTime()
formatTime(time)
formatTime(time, format)
formatTime(time, format, fallback)formatTime()
formatTime(time)
formatTime(time, format)
formatTime(time, format, fallback)参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
time | Date | string | number | 否 | new Date() | 要格式化的时间值。10 位数字按秒级时间戳处理；13 位数字按毫秒级时间戳处理；带小数的数字字符串按秒级时间戳处理。 |
format | string | 否 | '{y}-{m}-{d} {h}:{i}:{s}' | 输出模板。支持 {y} 年、{m} 月、{d} 日、{h} 时、{i} 分、{s} 秒、{a} 星期。 |
fallback | string | (time) => string | 否 | (value) => String(value) | 传入非法日期时的兜底返回值。可以传固定字符串，也可以传函数根据原始值生成文案。 |
返回值
返回格式化后的时间字符串。非法日期不会抛错，会返回 fallback 的结果。
常用场景
ts
formatTime(new Date())
// '2026-06-10 09:30:00'
formatTime(1713926400, '{y}/{m}/{d}')
// '2024/04/24'
formatTime('2022-03-04', '{m}-{d} 星期{a}')
// '03-04 星期五'
formatTime(1541927611, '{y}/{m}/{d} {h}:{m}:{s}')
// 2018/11/11 17:11:31
formatTime('--', '{y}-{m}-{d}', 'Invalid Date')
// 'Invalid Date'formatTime(new Date())
// '2026-06-10 09:30:00'
formatTime(1713926400, '{y}/{m}/{d}')
// '2024/04/24'
formatTime('2022-03-04', '{m}-{d} 星期{a}')
// '03-04 星期五'
formatTime(1541927611, '{y}/{m}/{d} {h}:{m}:{s}')
// 2018/11/11 17:11:31
formatTime('--', '{y}-{m}-{d}', 'Invalid Date')
// 'Invalid Date'注意事项
分钟占位符是 {i}，不是 {m}；{m} 表示月份。纯日期字符串如 2022-03-04 会按本地时区当天 00:00:00 解析。
函数源码
formatTime
来源：packages/utils/src/format.ts
/**
* 将时间值格式化为指定模板字符串。
*
* 支持 `Date`、毫秒时间戳、秒级时间戳、ISO 字符串和普通日期字符串。
* 纯日期字符串（如 `2022-03-04`）会按本地时区的 `00:00:00` 解析。
*
* @param time 时间值，默认当前时间。
* @param cFormat 格式模板，默认 `{y}-{m}-{d} {h}:{i}:{s}`。
* @param fallback 非法日期时的兜底返回值，默认返回原始输入。
* @returns 格式化后的时间字符串。
*
* @example
* formatTime(new Date(), '{y}-{m}-{d} {h}:{i}:{s}')
*
* @example
* formatTime(1713926400, '{y}/{m}/{d}')
* // => '2024/04/24'
*/
export function formatTime(
time: FormatTimeInput = new Date(),
cFormat = '{y}-{m}-{d} {h}:{i}:{s}',
fallback: FormatTimeFallback = (value) => String(value),
): string {
let date: Date
const timeStr = String(time)
if (typeof time === 'object' && time instanceof Date) {
date = time
} else {
const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?$/
const dateOnlyRegex = /^(\d{4})-(\d{2})-(\d{2})$/
if (isoRegex.test(timeStr)) {
date = new Date(time)
} else if (dateOnlyRegex.test(timeStr)) {
const [, year, month, day] = timeStr.match(dateOnlyRegex)!
date = new Date(Number(year), Number(month) - 1, Number(day))
} else if (timeStr.includes('.') && !isNaN(parseFloat(timeStr))) {
date = new Date(parseFloat(timeStr) * 1000)
} else if (/^\d{10}$/.test(timeStr)) {
date = new Date(parseInt(timeStr) * 1000)
} else {
date = new Date(time)
}
}
if (isNaN(date.getTime())) {
return typeof fallback === 'function' ? fallback(time) : fallback
}
const formatObj = {
y: date.getFullYear(),
m: date.getMonth() + 1,
d: date.getDate(),
h: date.getHours(),
i: date.getMinutes(),
s: date.getSeconds(),
a: date.getDay(),
}
return cFormat.replace(/{(y|m|d|h|i|s|a)+}/g, (result, key) => {
const value = formatObj[key as keyof typeof formatObj]
if (key === 'a') {
return ['日', '一', '二', '三', '四', '五', '六'][value]
}
if (result.length > 0 && value < 10) {
return '0' + value
}
return String(value)
})
}