@ivujs/i-utils/dist/es/date/index.d.ts

前端模块化 JavaScript 工具库

/**
 日期配置类型
 @param format 日期格式字符串，支持的占位符如下：
  | 占位符 | 说明 | 示例（2025-01-05 08:05:08 周一） |
  |--------|-----------------------|---------------------------------|
  | yyyy | 4 位年份 | 2025 |
  | yy | 2 位年份 | 25 |
  | MM | 2 位月份（补 0） | 01 |
  | M | 1 位月份（不补 0） | 1 |
  | dd | 2 位日期（补 0） | 05 |
  | d | 1 位日期（不补 0） | 5 |
  | HH | 24 小时制（2 位，补 0） | 08 |
  | H | 24 小时制（1 位，不补 0）| 8 |
  | hh | 12 小时制（2 位，补 0） | 08 |
  | h | 12 小时制（1 位，不补 0）| 8 |
  | mm | 2 位分钟（补 0） | 05 |
  | m | 1 位分钟（不补 0） | 5 |
  | ss | 2 位秒数（补 0） | 08 |
  | s | 1 位秒数（不补 0） | 8 |
  | SSS | 3 位毫秒（补 0） | 123 |
  | S | 1 位毫秒（不补 0） | 1 |
  | E | 周几（迷你名） | 一（zh） / Mon（en） |
  | EE | 周几（短名） | 周一（zh） / Mon（en） |
  | EEE | 周几（全名） | 星期一（zh） / Monday（en） |
  | Q | 季度（迷你名） | 1（zh） / 1（en） |
  | QQ | 季度（短名） | Q1（zh） / Q1（en） |
  | QQQ | 季度（全名） | 第一季度（zh） / Quarter 1（en）|
  | a | 上午 / 下午（小写） | am /pm |
  | A | 上午 / 下午（大写） | AM / PM |
  | aa | 上午 / 下午（中文） | 上午 / 下午 |
  | AA | 上午 / 下午（中文大写） | 上午 / 下午 |
 @example
 yyyy-MM-dd HH:mm:ss → 2025-01-05 08:05:08
 yyyy-M-d h:m:s → 2025-1-5 8:5:8
 yyyy-MM-dd EE → 2025-01-05 周一
 @param lang 语言，可选值：zh（默认）/ en
 */
export interface DateOptions {
    format?: string;
    lang?: string;
}
/**
 * 今天
 *@returns {string} 返回日期字符串
 */
export declare function today(): string;
/**
 * 昨天
 * @returns {string} 返回日期字符串
 */
export declare function yesterday(): string;
/**
 * 明天
 *@returns {string} 返回日期字符串
 */
export declare function tomorrow(): string;
/**
 * 上周（7天前日期）
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function lastWeek(date?: Date): string;
/**
 * 下周（7天后日期）
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function nextWeek(date?: Date): string;
/**
 * 上个月（30天前日期）
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function lastMonth(date?: Date): string;
/**
 * 下个月（30天后日期）
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function nextMonth(date?: Date): string;
/**
 * 上一年（365天前日期）
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function lastYear(date?: Date): string;
/**
 * 下一年（365天后日期）
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function nextYear(date?: Date): string;
/**
 * 是否为上午
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isAM(date?: Date): boolean;
/**
 * 是否为下午
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isPM(date?: Date): boolean;
/**
 * 是否为今天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isToday(date?: Date): boolean;
/**
 * 是否为昨天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isYesterday(date?: Date): boolean;
/**
 * 是否为前天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isBeforeYesterday(date?: Date): boolean;
/**
 * 是否为明天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isTomorrow(date?: Date): boolean;
/**
 * 是否为后天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isAfterTomorrow(date?: Date): boolean;
/**
 * 是否为工作日
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isWorkday(date?: Date): boolean;
/**
 * 是否为周末（周六和周日）
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isWeekend(date?: Date): boolean;
/**
 * 是否为本周第一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isFirstDayOfWeek(date?: Date): boolean;
/**
 * 是否为本周最后一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isLastDayOfWeek(date?: Date): boolean;
/**
 * 是否为本月第一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isFirstDayOfMonth(date?: Date): boolean;
/**
 * 是否为本月最后一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isLastDayOfMonth(date?: Date): boolean;
/**
 * 是否为本年第一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isFirstDayOfYear(date?: Date): boolean;
/**
 * 是否为本年最后一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isLastDayOfYear(date?: Date): boolean;
/**
 * 是否为闰年
 * @description 闰年366天，平年365天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isLeapYear(date?: Date): boolean;
/**
 * 是否为平年
 * @description 闰年366天，平年365天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isCommonYear(date?: Date): boolean;
/**
 * 是否在日期之前
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isBefore(startDate: Date, endDate?: Date): boolean;
/**
 * 是否在日期之后
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期，默认当前日期
 * @returns {boolean} 返回结果
 */
export declare function isAfter(startDate: Date, endDate?: Date): boolean;
/**
 * 是否在两个日期之间
 * @param {Date} date 要比较的日期
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {boolean} 返回结果
 */
export declare function isBetween(date: Date, startDate: Date, endDate: Date): boolean;
/**
 * 两个日期是否为同一天
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {boolean} 返回结果
 */
export declare function isSame(startDate: Date, endDate: Date): boolean;
/**
 * 两个日期是否为同一周
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {boolean} 返回结果
 */
export declare function isSameWeek(startDate: Date, endDate: Date): boolean;
/**
 * 两个日期是否为同一个月
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {boolean} 返回结果
 */
export declare function isSameMonth(startDate: Date, endDate: Date): boolean;
/**
 * 两个日期是否为同一年
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {boolean} 返回结果
 */
export declare function isSameYear(startDate: Date, endDate: Date): boolean;
/**
 * 两个日期是否相同或之前
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {boolean} 返回结果
 */
export declare function isSameOrBefore(startDate: Date, endDate: Date): boolean;
/**
 * 两个日期是否相同或之后
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {boolean} 返回结果
 */
export declare function isSameOrAfter(startDate: Date, endDate: Date): boolean;
/**
 * 获得此刻的日期
 * @returns {Date} 返回日期
 */
export declare function getNow(): Date;
/**
 * 获得当前日期字符串
 * @param {Date} date 日期参数，默认当前日期
 * @param options 配置项 配置项
 * @returns {string} 返回日期字符串
 */
export declare function getDate(date?: Date, options?: DateOptions): string;
/**
 * 获得当前日期时间字符串
 * @param {Date} date 日期参数，默认当前日期
 * @param options 配置项 配置项
 * @returns {string} 返回日期时间字符串
 */
export declare function getDateTime(date?: Date, options?: DateOptions): string;
/**
 * 获取当前时间戳
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回时间戳
 */
export declare function getTimestamp(date?: Date): number;
/**
 * 获取当前Unix时间戳
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回Unix时间戳
 */
export declare function getUnixTimestamp(date?: Date): number;
/**
 * 获得当前日期的对象形式
 * @param {Date} date 日期参数，默认当前日期
 * @returns {Object} 返回日期的对象形式
 */
export declare function getDateObject(date?: Date): {
    year: number;
    month: number;
    date: number;
    hours: number;
    minutes: number;
    seconds: number;
    milliseconds: number;
};
/**
 * 获得当前日期的数组形式
 * @param {Date} date 日期参数，默认当前日期
 * @returns {Object} 返回日期的数组形式
 */
export declare function getDateArray(date?: Date): number[];
/**
 * 获得当前日期是周几
 * @param {Date} date 日期参数，默认当前日期
 * @param options 配置项
 * @returns {number|string} 返回周几，会根据语言返回
 */
export declare function getWeek(date?: Date, options?: DateOptions): number | string;
/**
 * 获得当前日期是第几季度
 * @param {Date} date 日期参数，默认当前日期
 * @param options 配置项
 * @returns {number|string} 返回第几季度，会根据语言返回
 */
export declare function getQuarter(date?: Date, options?: DateOptions): number | string;
/**
 * 获得当前日期是所在周的第几天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number|string} 返回天数
 */
export declare function getDayOfWeek(date?: Date): number | string;
/**
 * 获得当前日期是所在月的第几天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回天数
 */
export declare function getDayOfMonth(date?: Date): number;
/**
 * 获得当前日期是所在年的第几天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回天数
 */
export declare function getDayOfYear(date?: Date): number;
/**
 * 获得当前日期是所在月的第几周
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回周数
 */
export declare function getWeekOfMonth(date?: Date): number;
/**
 * 获得当前日期是所在年的第几周
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回周数
 */
export declare function getWeekOfYear(date?: Date): number;
/**
 * 获得当前日期所在的周共几天
 * @returns {number} 返回天数
 */
export declare function getDaysOfWeek(): number;
/**
 * 获得当前日期所在的月共几天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回天数
 */
export declare function getDaysOfMonth(date?: Date): number;
/**
 * 获得当前日期所在的年共几天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回天数
 */
export declare function getDaysOfYear(date?: Date): number;
/**
 * 获得当前日期是所在月的第几周
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回周数
 */
export declare function getWeeksOfMonth(date?: Date): number;
/**
 * 获得当前日期是所在年的第几周
 * @param {Date} date 日期参数，默认当前日期
 * @returns {number} 返回周数
 */
export declare function getWeeksOfYear(date?: Date): number;
/**
 * 获得当前日期所在周的第一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function getFirstDateOfWeek(date?: Date): string;
/**
 * 获得当前日期所在周的最后一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function getLastDateOfWeek(date?: Date): string;
/**
 * 获取当前日期所在周的所有日期
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string[]} 返回日期数组
 */
export declare function getFullDateOfWeek(date?: Date): string[];
/**
 * 获得当前日期所在月的第一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function getFirstDateOfMonth(date?: Date): string;
/**
 * 获得当前日期所在月的最后一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function getLastDateOfMonth(date?: Date): string;
/**
 * 获取当前日期所在月的所有日期
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string[]} 返回日期数组
 */
export declare function getFullDateOfMonth(date?: Date): string[];
/**
 * 获取当前日期所在年的第一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function getFirstDateOfYear(date?: Date): string;
/**
 * 获取当前日期所在年的最后一天
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function getLastDateOfYear(date?: Date): string;
/**
 * 获取当前日期所在年的所有日期
 * @param {Date} date 日期参数，默认当前日期
 * @returns {string} 返回日期字符串
 */
export declare function getFullDateOfYear(date?: Date): string[];
/**
 * 计算两个日期相差的天数，不满一天为0
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {number} 返回两个日期相差的天数，结果为正数或者负数
 */
export declare function getDiffDay(startDate: Date, endDate: Date): number;
/**
 * 计算两个日期相差的周数，不满一周为0
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {number} 返回两个日期相差的周数，结果为正数或者负数
 */
export declare function getDiffWeek(startDate: Date, endDate: Date): number;
/**
 * 计算两个日期相差的月数，不满一月为0
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {number} 返回两个日期相差的月数，结果为正数或者负数
 */
export declare function getDiffMonth(startDate: Date, endDate: Date): number;
/**
 * 计算两个日期相差的年数，不满一年为0
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {number} 返回两个日期相差的年数，结果为正数或者负数
 */
export declare function getDiffYear(startDate: Date, endDate: Date): number;
/**
 * 获得两个日期之间的年月日数组
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {Array} 返回年月日数组
 */
export declare function getBetweenDates(startDate: Date, endDate: Date): string[];
/**
 * 获得两个日期之间的年月数组
 * @description 支持：日期字符串，日期对象，时间戳，Unix时间戳
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {Array} 返回年月数组
 */
export declare function getBetweenMonths(startDate: Date, endDate: Date): string[];
/**
 * 获得两个日期之间的年数组
 * @param {Date} startDate 开始日期
 * @param {Date} endDate 结束日期
 * @returns {Array} 返回年数组
 */
export declare function getBetweenYears(startDate: Date, endDate: Date): number[];
/**
 * 获得过去时间的字符串显示
 * @description 例如：刚刚，1分钟前，1小时前等
 * @param {Date} date 日期参数
 * @param options 配置项
 * @returns {string} 返回字符串
 */
export declare function getPastTime(date: Date, options?: DateOptions): string;
/**
 * 获得剩余时间的字符串显示
 * @description 例如：1天10小时20分钟30秒
 * @param {Date} date 日期参数
 * @param options 配置项
 * @returns {string} 返回字符串
 */
export declare function getOverTime(date: Date, options?: DateOptions): string;
/**
 * 通过日期获得年龄
 * @param {Date} date 日期参数
 * @returns {number} 返回周岁年龄
 */
export declare function getAge(date: Date): number;
/**
 * 通过日期获得星座
 * @param {Date} date 日期参数
 * @param options 配置项
 * @returns {string} 返回星座
 */
export declare function getZodiac(date: Date, options?: DateOptions): string;
/**
 * 通过日期获得生肖
 * @param {Date} date 日期参数
 * @param options 配置项
 * @returns {string} 返回生肖
 */
export declare function getChineseZodiac(date: Date, options?: DateOptions): string;
/**
 * 日期加减年
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+1
 * @returns {Date} 返回加减后的日期
 */
export declare function addYear(date?: Date, num?: number): Date;
/**
 * 日期加减月
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+1
 * @returns {Date} 返回加减后的日期
 */
export declare function addMonth(date?: Date, num?: number): Date;
/**
 * 日期加减天
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+1
 * @returns {Date} 返回加减后的日期
 */
export declare function addDate(date?: Date, num?: number): Date;
/**
 * 日期加减小时
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+1
 * @returns {Date} 返回加减后的日期
 */
export declare function addHours(date?: Date, num?: number): Date;
/**
 * 日期加减分钟
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+1
 * @returns {Date} 返回加减后的日期
 */
export declare function addMinutes(date?: Date, num?: number): Date;
/**
 * 日期加减秒
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+1
 * @returns {Date} 返回加减后的日期
 */
export declare function addSeconds(date?: Date, num?: number): Date;
/**
 * 日期加减毫秒
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+100
 * @returns {Date} 返回加减后的日期
 */
export declare function addMillisecond(date?: Date, num?: number): Date;
/**
 * 日期加减周
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+1
 * @returns {Date} 返回加减后的日期
 */
export declare function addWeek(date?: Date, num?: number): Date;
/**
 * 日期加减季度
 * @param {Date} date 日期参数，默认当前日期
 * @param {number} num 加减数量，用正数和负数表示；默认+1
 * @returns {Date} 返回加减后的日期
 */
export declare function addQuarter(date?: Date, num?: number): Date;
/**
 * UTC 日期对象转本地时区日期对象
 * @description 将 UTC 时间的 Date 对象转换为本地时间的 Date 对象（时间戳不变，仅调整时区偏移）
 * @param {Date} date UTC 日期对象，默认当前 UTC 时间
 * @returns {Date} 本地时区日期对象（时间戳 = UTC时间戳 + 时区偏移毫秒数）
 * @example
 * // UTC时间：2025-01-26 00:00:00
 * const utcDate = new Date('2025-01-26T00:00:00Z');
 * const localDate = fromDateUTC(utcDate);
 * console.log(toDateString(localDate)); // 2025-01-26 08:00:00（北京本地时间）
 */
export declare function fromDateUTC(date?: Date): Date;
/**
 * 本地时区日期转 UTC 日期对象
 * @description 将本地时间的 Date 对象转换为 UTC 时间的 Date 对象（时间戳不变，仅调整时区偏移）
 * @param {Date} date 本地日期对象，默认当前本地时间
 * @returns {Date} UTC 日期对象（时间戳 = 本地时间戳 - 时区偏移毫秒数）
 * @example
 * // 北京本地时间：2025-01-26 08:00:00（东8区）
 * const localDate = new Date('2025-01-26 08:00:00');
 * const utcDate = toDateUTC(localDate);
 * console.log(utcDate.toISOString()); // 2025-01-26T00:00:00.000Z（UTC时间）
 */
export declare function toDateUTC(date?: Date): Date;
/**
 * 格式化日期为 UTC 字符串（符合 ISO 8601 标准）
 * @description 直接输出 UTC 时间的字符串，无需手动转换时区
 * @param {Date} date 本地日期对象，默认当前本地时间
 * @param {DateOptions} options 格式化配置，默认 yyyy-MM-dd HH:mm:ss
 * @returns {string} UTC 日期字符串
 * @example
 * const localDate = new Date('2025-01-26 08:00:00');
 * console.log(toUTCString(localDate)); // 2025-01-26 00:00:00
 */
export declare function toDateUTCString(date?: Date, options?: DateOptions): string;
/**
 * 日期字符串转为日期对象
 * @description 支持日期字符串，时间戳，Unix时间戳
 * @param {string|number} value 日期参数
 * @returns {Date} 返回日期对象
 */
export declare function toDate(value: string | number): Date;
/**
 * 日期对象转为日期字符串
 * @description 支持日期字符串，日期对象，时间戳，unix时间戳
 * @param {Date} date 日期参数
 * @param options 配置项
 * @returns {string} 返回日期字符串
 */
export declare function toDateString(date: Date, options?: DateOptions): string;