鸿蒙三方库 | harmony-utils之DateUtil日期格式化详解
前言
日期格式化是开发中的高频需求，将Date对象转换为指定格式的字符串。@pura/harmony-utils的DateUtil封装了日期格式化方法，支持多种格式模板。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。
一、DateUtil格式化核心API
DateUtil提供了以下日期格式化方法：
| 方法 | 说明 | 返回类型 | 使用场景 |
|---|---|---|---|
format(date, pattern) | 格式化日期 | string | 日期展示 |
formatNow(pattern) | 格式化当前时间 | string | 时间戳 |
parse(str, pattern) | 解析日期字符串 | Date | 日期解析 |
1.1 格式化模板符号
| 符号 | 说明 | 示例 |
|---|---|---|
| yyyy | 年 | 2024 |
| MM | 月 | 01-12 |
| dd | 日 | 01-31 |
| HH | 时(24) | 00-23 |
| mm | 分 | 00-59 |
| ss | 秒 | 00-59 |
| EEEE | 星期 | 星期一 |
1.2 核心特性
- 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
- 类型安全：完整的TypeScript类型定义，编译期即可发现错误
- 异常处理：内置异常捕获机制，避免运行时崩溃
- 灵活模板：支持自定义格式模板
1.3 常用格式模板
| 模板 | 输出示例 | 说明 |
|---|---|---|
| yyyy-MM-dd | 2024-01-15 | 日期 |
| HH:mm:ss | 14:30:00 | 时间 |
| yyyy-MM-dd HH:mm:ss | 2024-01-15 14:30:00 | 日期时间 |
| yyyy年MM月dd日 | 2024年01月15日 | 中文日期 |
二、完整使用步骤
2.1 安装依赖
ohpminstall@pura/harmony-utils2.2 格式化当前时间
import{DateUtil}from'@pura/harmony-utils';Button('格式化当前时间').width('100%').onClick(()=>{try{letdateStr=DateUtil.formatNow('yyyy-MM-dd HH:mm:ss');this.result=`当前时间:${dateStr}`;}catch(e){this.result='异常: '+e;}})2.3 格式化指定日期
Button('格式化指定日期').width('100%').onClick(()=>{try{letdate=newDate(2024,0,15,14,30,0);letformatted=DateUtil.format(date,'yyyy年MM月dd日 EEEE');this.result=`格式化:${formatted}`;}catch(e){this.result='异常: '+e;}})三、完整页面示例
import{DateUtil}from'@pura/harmony-utils';@Entry@Componentstruct DateFormatDemo{@Stateresult:string='';build(){Column({space:12}){Button('当前时间').width('100%').onClick(()=>{this.result=DateUtil.formatNow('yyyy-MM-dd HH:mm:ss');});Button('中文格式').width('100%').onClick(()=>{this.result=DateUtil.formatNow('yyyy年MM月dd日 EEEE');});Text(this.result).fontSize(14).fontColor('#333333')}.padding(16)}}四、进阶用法
4.1 日志时间戳
import{DateUtil}from'@pura/harmony-utils';functionlogWithTimestamp(message:string):void{lettimestamp=DateUtil.formatNow('yyyy-MM-dd HH:mm:ss.SSS');console.log(`[${timestamp}]${message}`);}4.2 文件名日期
functiongenerateDatedFilename(prefix:string,ext:string):string{letdateStr=DateUtil.formatNow('yyyyMMdd_HHmmss');return`${prefix}_${dateStr}.${ext}`;}五、注意事项
- 模板大小写：MM是月，mm是分，HH是24时，hh是12时
- 月份从0开始：JavaScript Date的月份是0-11
- 时区问题：格式化使用本地时区
- 初始化依赖：使用前需确保
AppUtil.init()已调用 - 解析格式：parse需要与format使用相同的模板
六、常见问题
Q1: MM和mm有什么区别？
MM是月份（01-12），mm是分钟（00-59），注意大小写。
Q2: 如何获取12小时制时间？
使用hh代替HH，如 hh:mm:ss。
Q3: formatNow每次调用都获取最新时间吗？
是的，formatNow内部获取当前时间再格式化。
Q4: parse解析失败返回什么？
解析失败通常返回null或Invalid Date。
总结
DateUtil的日期格式化方法为时间展示提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法灵活地格式化日期时间。
本文基于
@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。