鸿蒙三方库 | harmony-utils之DateUtil日期计算详解

前言

日期计算在排班、计时、日历等场景中非常常用，如计算两个日期的差值、日期加减天数等。@pura/harmony-utils 的 DateUtil 封装了日期计算方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、DateUtil计算核心API

DateUtil 提供了以下日期计算方法：

方法	说明	返回类型	使用场景
`addDays(date, days)`	加减天数	Date	日期推算
`addMonths(date, months)`	加减月份	Date	月份推算
`addYears(date, years)`	加减年份	Date	年份推算
`daysBetween(date1, date2)`	天数差	number	倒计时
`isSameDay(date1, date2)`	是否同一天	boolean	日期比较
`isLeapYear(year)`	是否闰年	boolean	日历功能
`getDaysInMonth(year, month)`	获取月份天数	number	日历展示

1.1 核心特性

简洁易用：封装复杂逻辑为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
灵活计算：支持天、月、年的加减和差值计算

1.2 计算方法对照

方法	输入	输出	说明
addDays	今天+1	明天	天数加减
addMonths	1月+1	2月	月份加减
daysBetween	1月1日~6月15日	166	天数差值
isLeapYear	2024	true	闰年判断

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 日期加减

typescript 复制代码

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

Button('日期加减')
  .width('100%')
  .onClick(() => {
    try {
      let today = new Date();
      let tomorrow = DateUtil.addDays(today, 1);
      let nextMonth = DateUtil.addMonths(today, 1);
      this.result = `明天: ${DateUtil.format(tomorrow, 'yyyy-MM-dd')}\n下月: ${DateUtil.format(nextMonth, 'yyyy-MM-dd')}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 日期差值

typescript 复制代码

Button('日期差值')
  .width('100%')
  .onClick(() => {
    try {
      let d1 = new Date(2024, 0, 1);
      let d2 = new Date(2024, 5, 15);
      let days = DateUtil.daysBetween(d1, d2);
      this.result = `相差: ${days}天`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

typescript 复制代码

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

@Entry
@Component
struct DateCalcDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('日期加减').width('100%').onClick(() => {
        let today = new Date();
        this.result = `明天: ${DateUtil.format(DateUtil.addDays(today, 1), 'yyyy-MM-dd')}`;
      });
      Button('天数差').width('100%').onClick(() => {
        let d1 = new Date(2024, 0, 1);
        let d2 = new Date();
        this.result = `相差: ${DateUtil.daysBetween(d1, d2)}天`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 倒计时计算

typescript 复制代码

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

function getDaysUntil(targetDate: Date): number {
  return DateUtil.daysBetween(new Date(), targetDate);
}

4.2 会员到期日

typescript 复制代码

function calculateExpiry(startDate: Date, months: number): string {
  let expiry = DateUtil.addMonths(startDate, months);
  return DateUtil.format(expiry, 'yyyy-MM-dd');
}

五、注意事项

负数加减：传入负数可以向前推算日期
月份溢出：1月31日+1个月可能变为3月2日或3月3日
时区影响：计算基于本地时区
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
精度限制：daysBetween返回整数天

六、常见问题

Q1: addDays传入负数有效吗？

有效，addDays(today, -1)返回昨天。

Q2: daysBetween的顺序影响结果吗？

影响，结果可能为负数，建议用Math.abs取绝对值。

Q3: isLeapYear对1900年返回什么？

1900年不是闰年（能被100整除但不能被400整除），返回false。

Q4: getDaysInMonth的月份从0还是1开始？

取决于实现，通常1-12表示1月到12月。

总结

DateUtil 的日期计算方法为日期推算和差值计算提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法实现倒计时、到期日等功能。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。