前言

日期格式化是开发中的高频需求，将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 安装依赖

ohpm install @pura/harmony-utils

2.2 格式化当前时间

import { DateUtil } from '@pura/harmony-utils';

Button('格式化当前时间')
  .width('100%')
  .onClick(() => {
    try {
      let dateStr = DateUtil.formatNow('yyyy-MM-dd HH:mm:ss');
      this.result = `当前时间: ${dateStr}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 格式化指定日期

Button('格式化指定日期')
  .width('100%')
  .onClick(() => {
    try {
      let date = new Date(2024, 0, 15, 14, 30, 0);
      let formatted = DateUtil.format(date, 'yyyy年MM月dd日 EEEE');
      this.result = `格式化: ${formatted}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { DateUtil } from '@pura/harmony-utils';

@Entry
@Component
struct DateFormatDemo {
  @State result: 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';

function logWithTimestamp(message: string): void {
  let timestamp = DateUtil.formatNow('yyyy-MM-dd HH:mm:ss.SSS');
  console.log(`[${timestamp}] ${message}`);
}

4.2 文件名日期

function generateDatedFilename(prefix: string, ext: string): string {
  let dateStr = DateUtil.formatNow('yyyyMMdd_HHmmss');
  return `${prefix}_${dateStr}.${ext}`;
}

五、注意事项

1. 模板大小写：MM是月，mm是分，HH是24时，hh是12时
2. 月份从0开始：JavaScript Date的月份是0-11
3. 时区问题：格式化使用本地时区
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 解析格式：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 工具库，更多功能请参考官方文档与后续系列文章。