README-ZH.md

utils-date

使用typescript为前端打造的轻量实用的日期工具函数

English | 简体中文

安装

# npm
npm install utils-date
#yarn
yarn add utils-date
#pnpm
pnpm add utils-date

使用

import { format } from 'utils-date';
format('2023-01-01 12:12:12', {
  format: 'yyyy/mm/dd',
  padZero: false,
});
// 2023/1/1

API

• format
• Week
• offset
• min
• max
• diff
• clone
• daysInMonth
• weekOfMonth
• weekOfYear
• getTime
• getUnixTime
• toDate
• toObject
• toArray
• toTraditionalHour
• isDate
• isSame
• isBefore
• isAfter
• isLeap
• isPast
• isFuture
• isToday
• isBetween

types

type Time = Date | string | number;
type WeekName = 'Sunday' | 'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday';
type TimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
interface DateFormatOption {
  format?: string;
  padZero?: boolean;
}
interface DateObject {
  year: number;
  month: number;
  week: number;
  day: number;
  hour: number;
  minute: number;
  second: number;
  millisecond: number;
}

format

格式化日期。默认格式为yyyy-mm-dd hh:mm:ss，默认日期补零，如果不需要补零显示，请参考DateFormatOption配置。
signature:

function format(date: Time, option?: string | DateFormatOption): string;

example:

format(new Date(1642479132000)); // 2022-01-18 12:12:12
format(new Date(1642479132000), false); // 2022-1-18 12:12:12
format(new Date(1642479132000), 'yyyy/mm/dd'); // 2022/01/18
format(new Date(1642479132000), 'yyyy年mm月dd日'); // 2022年01月18日
format(new Date(1642479132000), {
  format: 'yyyy/mm/dd HH:MM:SS',
  padZero: false,
}); // 2022/1/18 12:12:12

⬆️ back

Week

获取星期的静态类。

signature:

class Week {
  // 获取指定日期的星期索引，省略参数则获取当前日期的星期索引
  static index(date?: Time): number;
  // 获取指定日期的中文星期名称，省略参数则获取当前日期的中文星期名称
  static zh(date?: Time): string;
  // 获取指定日期的英文星期名称，省略参数则获取当前日期的英文星期名称
  static en(date?: Time): string;
  // 获取指定日期的英文星期名称简写，省略参数则获取当前日期的英文星期简写
  static abbr(date?: Time): string;
  // 指定的日期是否为工作日(周一到周五)
  static isWorkDay(date?: Time): boolean;
  // 指定的日期是否为周末
  static isWeekend(date?: Time): boolean;
  // 指定的日期是否为指定的星期
  static isWeek(date: Time, weekName: WeekName): boolean;
}

example:

// 假设当前日期为2023-11-8 12:12:12
Week.index(); // 2
Week.zh('2023-11-8 12:12:12'); // 二
Week.zh('2023-11-8 12:12:12', '周'); // 周二
Week.en('2023-11-8 12:12:12'); // Tuesday
Week.abbr('2023-11-8'); // Tue.

⬆️ back

offset

日期偏移。等价于对日期进行加减操作。支持对年、月、日、周、时、分、秒、毫秒进行偏移计算。

signature:

function offset(date: Time, amount: number, timeUnit: TimeUnit): Date;

example:

const date = new Date('2023-05-01T00:00:00');
offset(date, 3, 'month'); // 2023-08-01T00:00:00.000Z
offset(date, -3, 'day'); // 2023-04-27T16:00:00.000Z

⬆️ back

min

计算日期数组中的最小值。
signature:

function min(dates: Time[]): Date;

example:

const dates = [new Date('2022-1-1 12:12:12'), '2022-1-1 14:12:12', '2021-12-31 12:12:12'];
min(dates); // 2021-12-31T12:12:12.000Z

⬆️ back

max

计算日期数组中的最大值。

signature:

function max(dates: Time[]): Date;

example:

const dates = [new Date('2022-1-1 12:12:12'), '2022-1-1 14:12:12', '2021-12-31 12:12:12'];
max(dates); // 2022-01-01T14:12:12.000Z

⬆️ back

diff

计算两个日期之间的差值。支持计算年、月、日、周、时、分、秒、毫秒为单位的差值。

signature:

function diff(first: Time, second: Time, unit: TimeUnit): number;

example:

diff('2022-12-1 12:12:12', '2022-1-1 12:12:12', 'day'); // 334p
diff('2022-12-1 12:12:12', '2022-12-1 22:12:12', 'hour'); // -10

⬆️ back

clone

克隆一个日期。

signature:

const old = new Date('2022-1-1 00:00:00');
const cloned = clone(old);
Object.is(old, cloned); // false

⬆️ back

daysInMonth

计算指定日期月份天数。

signature:

function daysInMonth(date: Time): number;

example:

daysInMonth('2022-1-1 00:00:00'); // 31

⬆️ back

weekOfMonth

计算指定日期是本月的第几周。

signature:

function weekOfMonth(date: Time): number;

example:

weekOfMonth('2023-11-8 12:12:12'); // 2

⬆️ back

weekOfYear

计算指定日期是本年的第几周。

signature:

function weekOfYear(date: Time): number;

example:

weekOfYear('2023-11-8 12:12:12'); // 45

⬆️ back

getTime

获取指定日期的毫秒时间戳。

signature:

function getTime(date: Time): number;

example:

getTime('2023-11-8 12:12:12'); // 1699416732000

⬆️ back

getUnixTime

获取指定日期的Unix时间戳。

signature:

function getUnixTime(date: Time): number;

example:

getUnixTime('2023-11-8 12:12:12'); // 1699416732

⬆️ back

toDate

将指定时间转为Date对象。

signature:

function toDate(date: Time): Date;

example:

toDate('2023-11-8 12:12:12'); // 2023-11-08T12:12:12.000Z
toDate(1699416732000); // 2023-11-08T12:12:12.000Z

⬆️ back

toObject

将指定时间转为对象。

signature:

function toObject(date: Time): DateObject;

example:

toObject('2023-11-8 12:12:12');
// output
{
  year: 2023,
  month: 10,
  day: 8,
  week: 3,
  hour: 12,
  minute: 12,
  second: 12,
  millisecond: 0
}

⬆️ back

toArray

将指定时间转为数组。

signature:

function toArray(date: Time): number[];

example:

toArray('2023-11-8 12:12:12'); // [2023, 10, 8, 12, 12, 12, 0]

⬆️ back

toTraditionalHour

将标准时间小时转换为中国传统对应时辰

signature:

function toTraditionalHour(hour: number): string;

example:

toTraditionalHour(12); // 午
toTraditionalHour(23); // 子

⬆️ back

isDate

判断指定时间是否为有效日期。 如：Date对象，合法的ISO时间字符串，Unix时间戳等。

signature:

isDate(date: any): boolean;

example:

isDate(new Date()); // true
isDate('2022-1-1'); // true
isDate({}); // false

⬆️ back

isSame

判断两个时间值是否相等。

signature:

function isSame(first: Time, second: Time): boolean;

example:

isSame('2022-1-1 12:12:12', new Date('2022-1-1 12:12:12')); // true

⬆️ back

isBefore

判断第一个日期是否在第二个日期之前。

signature:

function isBefore(first: Time, second: Time): boolean;

example:

isBefore('2022-1-1 12:12:12', '2022-1-3 12:12:12'); // true

⬆️ back

isAfter

判断第一个日期是否在第二个日期之后。

signature:

function isAfter(first: Time, second: Time): boolean;

example:

isAfter('2022-1-1 12:12:12', '2022-1-3 12:12:12'); // false

⬆️ back

isLeap

判断指定年份是否为闰年。

signature:

function isLeap(year: number): boolean;

example:

isLeap(2000); // true

⬆️ back

isPast

指定的日期是否已经过去(和当前时间比较)。signature:

function isPast(date: Time): boolean;

example:

isPast(new Date('1990-1-1 12:12:12')); // true

⬆️ back

isFuture

指定的日期是否在将来(和当前时间比较)。

signature:

function isFuture(date: Time): boolean;

example:

isFuture(new Date('2999-1-1 12:12:12')); // true

⬆️ back

isToday

判断指定日期是否为今天。

signature:

function isToday(date: Time): boolean;

example:

const date = new Date('1900-01-23T00:00:00Z');
isToday(date); // false

⬆️ back

isBetween

指定的时间是否在start和end时间之间。

signature:

function isBetween(date: Time, start: Time, end: Time): boolean;

example:

isBetween(new Date('2022-1-18 12:12:12'), '2022-01-01', '2022-12-31'); // true

⬆️ back