更新记录

1.0.5（2024-06-27） 下载此版本

• 修复时区偏移量计算bug。

1.0.4（2024-06-02） 下载此版本

• 修复 isBefore、isSame、isAfter、isSameOrBefore、isSameOrAfter 和 isBetween 等比较方法时总是以当前时间为基准比较的bug。
• 修复安卓部分方法指定日期参数无效的bug。

1.0.3（2024-05-06） 下载此版本

• 【重要】不再支持编译器 4.1 以下版本，请及时更新编译器为 4.1 以上版本以更好兼容后续更新迭代。
• 【重要】适配支持 app-js 引擎版本。(即目前ios的js引擎版本)。
• 【重要】diff api 默认单位调整为毫秒，和 dayjs 实现保持一致。

• diff 方法支持传入构造的 Dayjs 对象，示例如下：

  import { dayjs } from '@/uni_modules/kux-dayjs';
  
  const date1 = dayjs('2024-05-06 12:23:53');
  console.log(date1.diff(dayjs('2024-05-06'), 'M')); // 结果为743

• 修复 startOf 和 endOf 时间基准总是为当前时间的问题。
• 调整函数签名，解决编译器4.1以上版本不兼容的问题。
• 优化其他已知问题。

平台兼容性

kux-dayjs

KuxDayjs 是一个极简的 uts 库，API 设计完全参考 dayjs 的设计、所以上手该库基本零成本了，方便开发者们验证、操作和显示日期和时间。

开源地址：https://gitcode.com/kviewui/kux-dayjs

目录结构

导入插件

import { dayjs } from '@/uni_modules/kux-dayjs';

解析

实例

代替修改本地Date.prototype，KuxDayjs 对 Date 对象进行了封装，只需要调用 dayjs() 即可

KuxDayjs 对象是不可变的，也就是说，以某种方式改变 KuxDayjs 对象的所有API操作都将返回它的一个新实例。

当前时间

直接调用 dayjs() 将返回一个包含当前日期和时间的 KuxDayjs 对象。

const now = dayjs();

目前仅支持传入 YYYY-MM-DD HH:mm:ss.S 格式的日期时间字符串

1.0.2 及以上版本支持字符串解析。请看 字符串

字符串

1.0.2 及以上版本开始支持字符串解析，支持各种主流字符串格式，具体如下：

• YYYY-MM-DD
• YYYY/MM/DD
• YYYY-MM-DD HH
• YYYY-MM-DD HH:MM
• YYYY-MM-DD HH:MM:SS
• YYYY-MM-DD HH:MM:SS.millis
• YYYY/MM/DD HH
• YYYY/MM/DD HH:MM
• YYYY/MM/DD HH:MM:SS
• YYYY/MM/DD HH:MM:SS.millis
• ISO 8601 格式（包括 UTC 时间）

示例代码

console.log(dayjs('2023-12-13').format('YYYY-MM-DD'));
console.log(dayjs('2024/01/01').format('YYYY-MM-DD'));
console.log(dayjs('2023-12-13 12:23').format('YYYY-MM-DD HH:mm'));
console.log(dayjs('2023-12-13 12:23:45').format('YYYY-MM-DD HH:mm:ss'));
console.log(dayjs('2023-12-12 19:35:35.123').format('YYYY-MM-DD HH:mm:ss.SSS'));
console.log(dayjs('2023-12-13T10:16:18.000Z').format('YYYY-MM-DD HH:mm:ss'));
console.log(dayjs('2023-12-13T12:25:36.567+08:00').format('YYYY-MM-DD HH:mm:ss.SSS'));
console.log(dayjs(`${dayjs().valueOf()}`, true).format('YYYY-MM-DD HH:mm:ss'));
console.log(dayjs('1683234305000', true).format('YY-MM-DD HH:mm:ss'));

参数说明

初始化参数目前为三个，见下面表格

参数名	类型	必填	默认值	说明
date	string	否		日期时间字符串，支持字符串格式的时间戳解析
isTimestamp	boolean	否	false	是否为时间戳，是的话内部会自动转为整数作为时间戳解析
isCST	boolean	否	true	是否是中国标准时间，既UTC时间+8小时，isTimestamp 为 true 时生效，默认为 true

克隆复制

所有的 KuxDayjs 对象都是不可变的。 但如果有必要，使用 dayjs().clone() 可以复制出一个当前对象。

const a = dayjs();
const b = a.clone();
// a 和 b 是两个独立的 KuxDayjs 对象

取值/赋值

毫秒

获取或设置毫秒。
传入0到999的数字。 如果超出这个范围，它会进位到秒。

dayjs().millisecond()
dayjs().millisecond(1)

秒

获取或设置秒。
传入0到59的数字。 如果超出这个范围，它会进位到分钟。

dayjs().second()
dayjs().second(1)

分钟

获取或设置分钟。
传入0到59的数字。 如果超出这个范围，它会进位到小时。

dayjs().minute()
dayjs().minute(59)

小时

获取或设置小时。
传入0到23的数字。 如果超出这个范围，它会进位到天数。

dayjs().hour()
dayjs().hour(12)

日期

获取或设置日期。
传入1到31的数字。 如果超出这个范围，它会进位到月份。

dayjs().date()
dayjs().date(1)

注意
dayjs().date() 是该月的日期。dayjs().day() 是星期几。

星期

获取或设置星期几。
传入 number 从0(星期天)到6(星期六)。 如果超出这个范围，它会进位到其他周。

dayjs().day()
dayjs().day(0)

注意
dayjs().date() 是该月的日期。dayjs().day() 是星期几。

时间

获取或设置时间。
传入一个整数，表示从 1970-1-1 00:00:00 UTC 开始计时的毫秒数。 传入参数就是设置操作，否则为获取操作。

dayjs().time()
dayjs().time(1)

月

获取或设置月份。
传入0到11的 number。 如果超出这个范围，它会进位到年份。

dayjs().month()
dayjs().month(0)

注意
月份是从 0 开始计算的，即 1 月是 0。

年

获取或设置年份。

dayjs().year()
dayjs().year(2000)

操作

您可能需要一些方法来操作 KuxDayjs 对象。
KuxDayjs 支持像这样的链式调用。

dayjs('2019-01-25').add(1, 'day').subtract(1, 'year').year(2009);

增加

返回增加一定时间的复制的 KuxDayjs 对象。

dayjs().add(7, 'day')

支持配合单位操作。缩写要区分大小写。
支持的单位列表如下：

• week 周，缩写 w
• month 月份，缩写 M
• year 年，缩写 y
• hour 小时，缩写 h
• minute 分钟，缩写 m
• second 秒，缩写 s
• millisecond 毫秒，缩写 ms

减去

返回减去一定时间的复制的 KuxDayjs 对象。

dayjs().subtract(7, 'day')

支持配合单位操作。缩写要区分大小写。
支持的单位列表如下：

• week 周，缩写 w
• month 月份，缩写 M
• year 年，缩写 y
• hour 小时，缩写 h
• minute 分钟，缩写 m
• second 秒，缩写 s
• millisecond 毫秒，缩写 ms

今天

返回设置时间为今天的复制的 KuxDayjs 对象。

dayjs().today()

时间的开始

返回复制的 KuxDayjs 对象，并设置到一个时间的开始。

dayjs().startOf('year')

支持配合单位操作。缩写要区分大小写。
支持的单位列表如下：

• week 周，缩写 w
• month 月份，缩写 M
• year 年，缩写 y
• hour 小时，缩写 h
• minute 分钟，缩写 m
• second 秒，缩写 s
• millisecond 毫秒，缩写 ms

注意
暂时不支持跨年操作。

时间的结束

返回复制的 KuxDayjs 对象，并设置到一个时间的末尾。

dayjs().endOf('month')

支持配合单位操作。缩写要区分大小写。
支持的单位列表如下：

• week 周，缩写 w
• month 月份，缩写 M
• year 年，缩写 y
• hour 小时，缩写 h
• minute 分钟，缩写 m
• second 秒，缩写 s
• millisecond 毫秒，缩写 ms

注意
暂时不支持跨年操作。

显示

当解析和操作完成后，您需要一些方式来展示 KuxDayjs 对象。

格式化

根据传入的占位符返回格式化后的日期。

dayjs().format('YYYY-MM-DD HH:mm:ss')
dayjs().format('YYYY-MM-DD a HH:mm:ss')
dayjs().format('YYYY-MM-DD HH:mm:ss A')

支持的格式占位符列表：

相对当前时间（前）

返回现在到当前实例的相对时间。

dayjs('2021-12-12').fromNow(); // 1年前

支持传入配置项自定义输出格式以及显示隐藏后缀，配置项定义如下：

RelativeTime 说明

相对指定时间（前）

返回 X 到当前实例的相对时间。

const datetime = dayjs('2021-12-12 15:43:58');
const a = dayjs('2022-12-12');
datetime.from(a); // 1年前

支持传入配置项自定义输出格式以及显示隐藏后缀，配置项定义如下：

RelativeTime 说明

相对当前时间（后）

返回当前实例到现在的相对时间。

dayjs('2021-12-12').toNow(); // 1年后

支持传入配置项自定义输出格式以及显示隐藏后缀，配置项定义如下：

RelativeTime 说明

相对指定时间（后）

返回当前实例到现在的相对时间。

const datetime = dayjs('2021-12-12 15:43:58');
const a = dayjs('2022-12-12');
console.log(datetime.to(a)); // 输出 1年后

支持传入配置项自定义输出格式以及显示隐藏后缀，配置项定义如下：

RelativeTime 说明

日历时间

传入指定年月获取指定年月的日历面板数据，指定年月省略时默认获取当年年月的数据。返回 DateFormat[]，DateFormat 见下方说明。

dayjs().calendar(); 

传入参数

DateFormat 说明

LunarType 说明

InfoType 说明

差异（Diff）

返回指定单位下两个日期时间之间的差异。

const date1 = dayjs('2019-01-25');
const date2 = dayjs('2018-06-05');
date1.diff(date2) // 20214000000 默认单位是毫秒

要获取其他单位下的差异，则在第二个参数传入相应的单位。

const date1 = dayjs('2019-01-25');
date1.diff('2018-06-05', 'month') // 7;

默认情况下会将结果进位成整数。 如果要得到一个浮点数，将 true 作为第三个参数传入。

const date1 = dayjs('2019-01-25');
date1.diff('2018-06-05', 'month', true) // 7.645161290322581;

支持的单位列表：

• week 周，缩写 w
• day 天，缩写 d
• month 月份，缩写 M
• year 年，缩写 y
• hour 小时，缩写 h
• minute 分钟，缩写 m
• second 秒，缩写 s
• millisecond 毫秒，缩写 ms

Unix时间戳（毫秒）

返回当前实例的 UNIX 时间戳，13位数字，毫秒

dayjs('2019-01-25').valueOf() // 1548381600000

Unix时间戳

返回当前实例的 UNIX 时间戳，10位数字，秒

dayjs('2019-01-25').valueOf() // 1548381600

此值不包含毫秒信息，会进位到秒。

获取月天数

获取当前月份包含的天数。

const date = dayjs('2023-12-12'); // 31

转Date

从 KuxDayjs 中获取原生的Date对象。

dayjs('2023-12-12').toDate();

转数组

返回一个包含各个时间信息的 Array。

const datetime = dayjs('2023-12-13 10:16:18');// [2023,12,13,10,16,18,0]

转JSON

序列化为 ISO 8601 格式的字符串。

dayjs('2023-12-13 10:16:18').toJSON(); // 2023-12-13T10:16:18.000Z

转对象

返回包含时间信息的 Object。

dayjs('2023-12-13 10:16:18').toObject(); // {"date":13,"hours":10,"milliseconds":0,"minutes":16,"months":12,"seconds":18,"years":2023}

转字符串

返回包含时间信息的 RFC 822 或 RFC 5322 格式字符串。

dayjs('2023-12-13 10:16:18').toRFCString(); // Wed, 13 Dec 2023 10:16:18 GMT

查询

KuxDayjs 对象还有很多查询的方法。

是否之前

表示 KuxDayjs 对象是否在另一个提供的日期时间之前。

dayjs('2023-12-13 10:16:18').isBefore('2024-12-12'); // true

如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。

dayjs('2023-12-13 10:16:18').isBefore('2024-12-12', 'year'); // true

支持的单位列表如下：

• year - 年，缩写为 y
• month - 月，缩写为 M
• day - 日，缩写为 d
• hour - 小时，缩写为 h
• minute - 分钟，缩写为 m
• second - 秒，缩写为 s
• millisecond - 毫秒，缩写为 ms

是否相同

表示 KuxDayjs 对象是否和另一个提供的日期时间相同。

dayjs('2023-12-13 10:16:18').isBefore('2023-12-12'); // false

如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。

dayjs('2023-12-13 10:16:18').isBefore('2023-12-12', 'year'); // true

支持的单位列表如下：

• year - 年，缩写为 y
• month - 月，缩写为 M
• day - 日，缩写为 d
• hour - 小时，缩写为 h
• minute - 分钟，缩写为 m
• second - 秒，缩写为 s
• millisecond - 毫秒，缩写为 ms

是否之后

表示 KuxDayjs 对象是否在另一个提供的日期时间之后。

dayjs('2023-12-13 10:16:18').isAfter('2023-12-12'); // true

如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。

dayjs('2023-12-13 10:16:18').isAfter('2023-12-12', 'year'); // true

支持的单位列表如下：

• year - 年，缩写为 y
• month - 月，缩写为 M
• day - 日，缩写为 d
• hour - 小时，缩写为 h
• minute - 分钟，缩写为 m
• second - 秒，缩写为 s
• millisecond - 毫秒，缩写为 ms

是否相同或之前

表示 KuxDayjs 对象是和另一个提供的日期时间相同或在其之前。

dayjs('2023-12-13 10:16:18').isSameOrBefore('2023-12-12'); // false

如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。

dayjs('2023-12-13 10:16:18').isSameOrBefore('2023-12-12', 'year'); // true

支持的单位列表如下：

• year - 年，缩写为 y
• month - 月，缩写为 M
• day - 日，缩写为 d
• hour - 小时，缩写为 h
• minute - 分钟，缩写为 m
• second - 秒，缩写为 s
• millisecond - 毫秒，缩写为 ms

是否相同或之后

表示 KuxDayjs 对象是和另一个提供的日期时间相同或在其之前。

dayjs('2023-12-13 10:16:18').isSameOrAfter('2023-12-12'); // true

如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。

dayjs('2023-12-13 10:16:18').isSameOrAfter('2023-12-12', 'year'); // true

支持的单位列表如下：

• year - 年，缩写为 y
• month - 月，缩写为 M
• day - 日，缩写为 d
• hour - 小时，缩写为 h
• minute - 分钟，缩写为 m
• second - 秒，缩写为 s
• millisecond - 毫秒，缩写为 ms

是否两者之间

表示 KuxDayjs 对象是否在其他两个的日期时间之间。

dayjs('2023-12-13').isBetween('2023-12-13', '2023-12-14'); // 默认毫秒

如果想使用除了毫秒以外的单位进行比较，则将单位作为第三个参数传入。

dayjs('2023-12-13').isBetween('2023-12-13', '2023-12-14', 'year');

支持的单位列表如下：

• year - 年，缩写为 y
• month - 月，缩写为 M
• day - 日，缩写为 d
• hour - 小时，缩写为 h
• minute - 分钟，缩写为 m
• second - 秒，缩写为 s
• millisecond - 毫秒，缩写为 ms

如果想自定义包含关系进行比较，则将包含关系作为第四个参数传入。

dayjs('2023-12-13').isBetween('2023-12-13', '2023-12-14', 'day', '[');

包含关系列表如下：

• [ - 向前包含，等同于 <=
• ] - 向后包含，等同于 >=
• [] - 前后都包含

是否是KuxDayjs

这表示一个变量是否为 KuxDayjs 对象。

dayjs().isDayjs(dayjs()); // true
dayjs().isDayjs(new Date()); // false

是否闰年

查询 KuxDayjs 对象的年份是否是闰年。

dayjs('2000-01-01').isLeapYear(); // true

自定义类型

因为 uts 强类型，所以有些 API 参数需要指定参数类型，以上所有 API 涉及的自定义类型都在下面列出，如果有需要可以自己手动导入类型使用。

InfoType

export type InfoType = {
    lunarY : number;
    lunarM : number;
    lunarD : number;
    isLeap : boolean;
}

LunarType

export type LunarType = {
    month: string;
    date: string;
};

DatetimeUnit

export type DatetimeUnit = 
| 'day'
| 'd'
| 'month'
| 'M'
| 'year'
| 'y'
| 'hour'
| 'h'
| 'minute'
| 'm'
| 'second'
| 's'
| 'millisecond'
| 'ms'

DiffUnit

export type DiffUnit = 
| 'week'
| 'w'
| 'day'
| 'd'
| 'month'
| 'M'
| 'year'
| 'y'
| 'hour'
| 'h'
| 'minute'
| 'm'
| 'second'
| 's'
| 'millisecond'
| 'ms'

DateFormat

export type DateFormat = {
    year: number;
    month: number;
    date: number;
    render: any;
    lunar: LunarType;
    fullLunar: InfoType;
    diffDays: number;
    isToday: boolean;
    fullDate: string;
};

RelativeTime

export type RelativeTime = {
    s?: string;
    m?: string;
    mm?: string;
    h?: string;
    hh?: string;
    d?: string;
    dd?: string;
    mon?: string;
    mons?: string;
    y?: string;
    yy?: string;
};

FromToOptions

export type FromToOptions = {
    isSuffix?: boolean;
    relativeTime?: RelativeTime;
};

DatetimeOptions

export type DatetimeOptions = {
    years: number;
    months: number;
    date: number;
    hours: number;
    minutes: number;
    seconds: number;
    milliseconds: number;
};

IsBetweenContains

export type IsBetweenContains = 
| '['
| ']'
| '[]'
| ''

结语

kux 不生产代码，只做代码的搬运工，致力于提供uts 的 js 生态轮子实现，欢迎各位大佬在插件市场搜索使用 kux 生态插件：https://ext.dcloud.net.cn/search?q=kux

友情推荐

• GVIM即时通讯模版：GVIM即时通讯模版，基于uni-app x开发的一款即时通讯模版
• t-uvue-ui：T-UVUE-UI是基于UNI-APP X开发的前端UI框架
• UxFrame 低代码高性能UI框架：【F2图表、双滑块slider、炫酷效果tabbar、拖拽排序、日历拖拽选择、签名...】UniAppX 高质量UI库
• wx-ui 基于uni-app x开发的高性能混合UI库：基于uni-app x开发的高性能混合UI库，集成 uts api 和 uts component，提供了一套完整、高效且易于使用的UI组件和API，让您以更少的时间成本，轻松完成高性能应用开发。
• firstui-uvue：FirstUI（unix）组件库，一款适配 uni-app x 的轻量、简洁、高效、全面的移动端组件库。
• easyXUI 不仅仅是UI 更是为UniApp X设计的电商模板库：easyX 不仅仅是UI库，更是一个轻量、可定制的UniAPP X电商业务模板库，可作为官方组件库的补充,始终坚持简单好用、易上手