Date和Time工具类

Date & Time ISO 格式转换与渲染工具函数

痛点来源

在实际项目中，日期与时间的存储、传输与展示常常使用不同格式，导致大量重复且易出错的转换代码散落在各处：

• 后端通常返回或要求 ISO 日期（如 "2025-12-19"）与时间字符串（如 "14:30"）
• 前端展示需要中文日期（如 “2025年12月19日”）与时间（如 “14:30”）
• 年份范围、仅年份、仅年月、时间解析等变体需求频繁出现
• 直接操作字符串容易出现补零遗漏、类型判断缺失、NaN 传播、格式不统一等问题
• 不同组件（如 DatePicker、TimePicker、Timeline、Card 元信息）对日期时间渲染规则不一致，视觉体验参差

若每个组件或页面都自行拼接与解析，不仅代码冗余，还极易引入格式错误或国际化障碍。

设计目标

这组工具函数旨在统一所有日期与时间的 ISO/标准格式 ↔ 显示格式转换逻辑，提供一套简洁、安全、语义明确的日期时间处理方案，让组件与业务代码只需关心“使用日期时间”，而无需关心“如何格式化与解析”。

核心工具函数

函数	职责	返回值/特性
toISOYear	根据年份生成当年第一天的 ISO 字符串	"YYYY-01-01"
toISOYMD	根据年月日生成完整 ISO 日期字符串	"YYYY-MM-DD"，自动补零
isoToYMD	将 ISO 日期字符串解析为年月日对象	{ year, month, day }，非法输入返回 NaN
renderDate	渲染完整中文日期，可选仅显示到月份	“2025年12月19日” 或 “2025年12月”
renderYear	渲染仅年份	“2025年”
renderYearRange	渲染年份范围	“2025年 至 2030年”
toTimeStr	根据时分生成标准时间字符串	"HH:MM"，自动补零
parseTimeStr	将时间字符串解析为时分对象	{ h, m }，自动转换为数字

设计亮点

• 严格标准格式：日期产出标准 "YYYY-MM-DD"，时间产出 "HH:MM"，便于后端交互、排序、比较。
• 自动补零统一：年月日时分均使用 padStart 确保两位显示，杜绝 “2025-1-1” 或 “9:5” 等非标准格式。
• 安全解析：isoToYMD 与 parseTimeStr 对非法输入返回明确 NaN 或可判断结构，便于上游降级处理。
• 纯函数无副作用：不依赖 Vue 或 DOM，可在任意环境安全调用。
• 语义化中文展示：日期统一使用 “年”“月”“日”，提升中文场景阅读友好度。
• 高复用性：覆盖从单一日期/时间到范围的所有常见展示与解析需求。

典型使用方式

import { 
  toISOYMD, 
  isoToYMD, 
  renderDate, 
  renderYearRange,
  toTimeStr,
  parseTimeStr 
} from '@/utils/datetime';

// 日期
const todayISO = toISOYMD(2025, 12, 19); // "2025-12-19"
const { year, month, day } = isoToYMD(todayISO);
renderDate(todayISO);              // "2025年12月19日"
renderDate(todayISO, true);        // "2025年12月"
renderYearRange('2023-01-01', '2025-12-31'); // "2023年 至 2025年"

// 时间
const timeStr = toTimeStr(9, 5);    // "09:05"
const { h, m } = parseTimeStr('14:30'); // { h: 14, m: 30 }

设计价值

这组工具函数是组件库时间表达一致性的隐形守护者：

彻底消除各处零散的日期时间拼接与解析代码 确保所有日期时间展示格式全局统一，避免斜杠、横线、补零不一致等问题 为后续国际化（i18n）预留切换空间（只需替换 render 系列函数） 与 DatePicker、TimePicker、Timeline、Form 等组件无缝协作，无需额外适配 极大提升代码可读性：renderDate(iso) + ' ' + toTimeStr(h, m) 比手动拼接更具语义