dayjs 源码解析(一)(api)
前言
作为一个程序员,阅读别人优秀代码是提升自己技术能力的一个很好的方法。下面,我将自己阅读 dayjs(v1.6.10)的源码的过程记录下来。
阅读库的代码,首先先要知道这个库的作用
dayjs 是一个轻量的 JavaScript 时间日期处理库,其用法(api)和 Moment.js 完全一样。
特点
- 和 Moment.js 相同的 api 和用法
- 不可变数据(Immutable)
- 支持链式操作(Chainable)
- l18n国际化
- 仅 2kb 大小
- 全浏览器兼容
因为其 api 和 Moment.js 完全相同,所以你可以将之前使用 Moment.js 的项目无痛的迁移使用 dayjs。
API 介绍(v1.6.10)
首先,阅读 dayjs 的源码,我们应该从 dayjs 的 api 入手。
Day.js 没有修改原生的 Date.prototype,而是在 Date 对象基础上包装了一层,叫做 Dayjs 对象。Dayjs 对象是不可变的,即所有改变 Dayjs 的操作都会返回一个新的实例。
其中,api 分为 6 类:
解析
- 构造 dayjs(existing?:string | number | Date | Dayjs):构造一个 Dayjs 实例对象
- 克隆 .clone() | dayjs(original: Dayjs):在已有 Dayjs 实例对象的基础上克隆返回一个新的 Dayjs 实例对象
- 验证 .isValid():验证该 Dayjs 实例对象是否有效
获取和设置
- 年 .year()
- 月 .month()
- 日 .date()
- 星期几 .day()
- 时 .hour()
- 分 .minute()
- 秒 .second()
- 毫秒 .millisecond()
- 设置 .set(unit: string, value: number)
操作
- 添加 .add(value: number, unit: string)
- 减少 .subtract(value: number, unit: string)
- 开始的时间 .startOf(unit: string)
- 结束的时间 .endOf(unit: string)
展示
- 格式化 .format(stringWithTokens: string)
- 差别 .diff(compared: Dayjs, unit: string (default: 'milliseconds'), float?: boolean)
- Unix 时间戳(毫秒) .valueOf()
- Unix 时间戳(秒) .unix()
- 某月的天数 .daysInMonth()
- 转换为 JavaScript Date 对象 .toDate
- 转换为数组 .toArray()
- 转换为 JSON .toJSON()
- 转换为 ISO 8601 标准格式的字符串 .toISOString()
- 转换为对象 .toObject()
- 转换为字符串 .toString()
查询
- 是否在之前 .isBefore(compared: Dayjs)
- 是否相同 .isSame(compared: Dayjs)
- 是否在之后 .isAfter(compared: Dayjs)
- 是否是 Dayjs 实例对象 isDayjs()
插件
- 相对时间
- 是否是闰年
API 详解(v1.6.10)
解析
构造器 dayjs(existing?: string | number | Date | Dayjs)
1.当没有参数时,会返回一个新的 Dayjs 实例对象,且为当前日期和时间
dayjs()
2.当参数为 ISO 8601 标准的字符串时
dayjs('2018-07-01T12:00:00.000Z')
3.当参数为 unix 时间戳时
dayjs(1318781876406);
4.当参数为一个原生的 JavaScript Date 对象时
dayjs(new Date(2018, 7, 1));
dayjs() 构造函数会返回一个 Dayjs 实例对象
克隆 .clone() | dayjs(original: Dayjs)
会克隆返回一个新的 Dayjs 对象,有两种方法
// 1.使用 .clone() 方法 dayjs().clone() // 2.使用 dayjs 构造函数,且传入的参数为被克隆的 Dayjs 实例对象 dayjs(dayjs('2018-7-1'))
验证 .isValid()
返回一个布尔值,表示该 Dayjs 实例对象是否有效
dayjs().isValid()
获取和设置
获取(年,月,日,星期几,时,分,秒,毫秒)
// 年 dayjs().year() // 月 dayjs().month() // 日 dayjs().date() // 星期几 dayjs().day() // 时 dayjs().hour() // 分 dayjs().minute() // 秒 dayjs().second() // 毫秒 dayjs().millisecond()
上面返回的值与用原生 Date.prototype 对象下的方法获取 “年月日...” 的值是一样的,其实在源码中,就是使用的 Date 的原生方法获取的 “年月日...”
设置 .set(unit: string, value: number)
返回一个新的日期时间被改变的 Dayjs 实例对象
dayjs().set('date', 1) // 设置 “日” 为 1 日 dayjs().set('month', 3) // 设置 “月” 为 4 月 dayjs().set('second', 30) // 设置 “秒” 为 30 秒
操作
Dayjs 实例对象可以使用很多方法操作
dayjs('2018-7-1') .add(1, 'day') .substract(1, 'year').toString() // 在 2018-7-1 基础上添加 1 天,然后减少 1 年,最后转换为字符串
添加 .add(value: number, unit: string)
dayjs().add(7. 'day')
减少 .subtract(value: number, unit: string)
dayjs().subtract(7. 'year')
开始的时间
返回克隆的以传入的单位开始时间的 Dayjs 实例对象
dayjs().startOf('week') // 本周开始的时间
结束的时间
返回克隆的以传入的单位结束时间的 Dayjs 实例对象
dayjs().endOf('month') // 本月的结束时间
展示
格式化 .format(stringWidthTokens: string)
返回一个按照你规定好的格式化后的字符串
dayjs().format(); // current date in ISO6801, without fraction seconds e.g. '2020-04-02T08:02:17-05:00' dayjs('2019-01-25').format('{YYYY} MM-DDTHH:mm:ssZ[Z]'); // '{2019} 01-25T00:00:00-02:00Z' dayjs('2019-01-25').format('DD/MM/YYYY'); // '25/01/2019'
差别 .diff(compared: Dayjs, unit: string (default: 'milliseconds'), float?: boolean)
返回两个 Dayjs 实例对象的时间差
const date1 = dayjs('2019-01-25'); const date2 = dayjs('2018-06-05'); date1.diff(date2); // 20214000000 date1.diff(date2, 'months'); // 7 date1.diff(date2, 'months', true); // 7.645161290322581 date1.diff(date2, 'days'); // 233
unix 时间戳(毫秒) .valueOf()
dayjs('2019-01-25').valueOf(); // 1548381600000
unix 时间戳(秒) .unix()
dayjs('2019-01-25').unix(); // 1548381600
某月的天数 .daysInMonth()
dayjs('2018-7-1').daysInMonth() // 31
转换为(原生 Date 对象 | 数组 | json | ISO 8601 字符串 | 对象 | 字符串)
// 1.转换为 原生 Date 对象 dayjs('2019-01-25').toDate() // 2.转换为 数组 dayjs('2019-01-25').toArray() // [ 2019, 0, 25, 0, 0, 0, 0 ] // 3.转换为 json dayjs('2019-01-25').toJSON() // '2019-01-25T02:00:00.000Z' // 4.转换为 ISO 8601 字符串 dayjs('2019-01-25').toISOString() // '2019-01-25T02:00:00.000Z' // 5.转换为 ISO 8601 字符串 dayjs('2019-01-25').toObject() /* { years: 2019, months: 0, date: 25, hours: 0, minutes: 0, seconds: 0, milliseconds: 0 } */ // 6.转换为 字符串 dayjs('2019-01-25').toString() // 'Fri, 25 Jan 2019 02:00:00 GMT'
查询
是否在之前 .isBefore(compared: Dayjs)
dayjs().isBefore(dayjs()); // false
是否相同
dayjs().isSame(dayjs()); // true
是否在之后
dayjs().isAfter(dayjs()); // false
是否是 Dayjs 实例对象
dayjs.isDayjs(dayjs()); // true dayjs.isDayjs(new Date()); // false
是否是闰年(在 1.7.0 版本被弃用,请使用 IsLeapYear plugin 插件替代)
dayjs('2000-01-01').isLeapYear(); // true
插件
相对时间
使用 .from .to .fromNow .toNow 方法来获得相对时间
是否是闰年
使用 .from .to .fromNow .toNow 方法来获得相对时间
下一篇,dayjs 源码解析(二)(目录结构)