# kux-dayjs `KuxDayjs` 是一个极简的 `uts` 库，API 设计完全参考 `dayjs` 的设计、所以上手该库基本零成本了，方便开发者们验证、操作和显示日期和时间。 ## 目录结构
  1. 导入插件
  2. 解析
    1. 实例
    2. 当前时间
    3. 克隆复制
  3. 取值/赋值
    1. 毫秒
    2. 秒
    3. 分钟
    4. 小时
    5. 日期
    6. 星期
    7. 时间
    8. 月
    9. 年
  4. 操作
    1. 增加
    2. 减去
    3. 今天
    4. 时间的开始
    5. 时间的结束
  5. 显示
    1. 格式化
    2. 相对当前时间（前）
    3. 相对指定时间（前）
    4. 相对当前时间（后）
    5. 相对指定时间（后）
    6. 日历时间
    7. 差异（Diff）
    8. Unix时间戳（毫秒）
    9. Unix时间戳
    10. 获取月天数
    11. 转Date
    12. 转数组
    13. 转JSON
    14. 转对象
    15. 转字符串
  6. 查询
    1. 是否之前
    2. 是否相同
    3. 是否之后
    4. 是否相同或之前
    5. 是否相同或之后
    6. 是否两者之间
    7. 是否是KuxDayjs
    8. 是否闰年
### 导入插件 ```ts import { dayjs } from '@/uni_modules/kux-dayjs'; ``` ### 解析 #### 实例 代替修改本地Date.prototype，`KuxDayjs` 对 `Date` 对象进行了封装，只需要调用 `dayjs()` 即可 `KuxDayjs` 对象是不可变的，也就是说，以某种方式改变 `KuxDayjs` 对象的所有API操作都将返回它的一个新实例。 #### 当前时间 直接调用 `dayjs()` 将返回一个包含当前日期和时间的 `KuxDayjs` 对象。 ```ts const now = dayjs(); ``` >目前仅支持传入 `YYYY-MM-DD HH:mm:ss.S` 格式的日期时间字符串 #### 克隆复制 所有的 `KuxDayjs` 对象都是不可变的。 但如果有必要，使用 `dayjs().clone()` 可以复制出一个当前对象。 ```ts const a = dayjs(); const b = a.clone(); // a 和 b 是两个独立的 KuxDayjs 对象 ``` ### 取值/赋值 #### 毫秒 获取或设置毫秒。
传入0到999的数字。 如果超出这个范围，它会进位到秒。 ```ts dayjs().millisecond() dayjs().millisecond(1) ``` #### 秒 获取或设置秒。
传入0到59的数字。 如果超出这个范围，它会进位到分钟。 ```ts dayjs().second() dayjs().second(1) ``` #### 分钟 获取或设置分钟。
传入0到59的数字。 如果超出这个范围，它会进位到小时。 ```ts dayjs().minute() dayjs().minute(59) ``` #### 小时 获取或设置小时。
传入0到23的数字。 如果超出这个范围，它会进位到天数。 ```ts dayjs().hour() dayjs().hour(12) ``` #### 日期 获取或设置日期。
传入1到31的数字。 如果超出这个范围，它会进位到月份。 ```ts dayjs().date() dayjs().date(1) ``` > ****注意****
`dayjs().date()` 是该月的日期。`dayjs().day()` 是星期几。 #### 星期 获取或设置星期几。
传入 number 从0(星期天)到6(星期六)。 如果超出这个范围，它会进位到其他周。 ```ts dayjs().day() dayjs().day(0) ``` > ****注意****
`dayjs().date()` 是该月的日期。`dayjs().day()` 是星期几。 #### 时间 获取或设置时间。
传入一个整数，表示从 1970-1-1 00:00:00 UTC 开始计时的毫秒数。 传入参数就是设置操作，否则为获取操作。 ```ts dayjs().time() dayjs().time(1) ``` #### 月 获取或设置月份。
传入0到11的 number。 如果超出这个范围，它会进位到年份。 ```ts dayjs().month() dayjs().month(0) ``` > ****注意****
月份是从 0 开始计算的，即 1 月是 0。 #### 年 获取或设置年份。
```ts dayjs().year() dayjs().year(2000) ``` ### 操作 您可能需要一些方法来操作 `KuxDayjs` 对象。
`KuxDayjs` 支持像这样的链式调用。 ```ts dayjs('2019-01-25').add(1, 'day').subtract(1, 'year').year(2009); ``` #### 增加 返回增加一定时间的复制的 `KuxDayjs` 对象。 ```ts dayjs().add(7, 'day') ``` 支持配合单位操作。缩写要区分大小写。
支持的单位列表如下：
+ week 周，缩写 `w` + month 月份，缩写 `M` + year 年，缩写 `y` + hour 小时，缩写 `h` + minute 分钟，缩写 `m` + second 秒，缩写 `s` + millisecond 毫秒，缩写 `ms` #### 减去 返回减去一定时间的复制的 `KuxDayjs` 对象。 ```ts dayjs().subtract(7, 'day') ``` 支持配合单位操作。缩写要区分大小写。
支持的单位列表如下：
+ week 周，缩写 `w` + month 月份，缩写 `M` + year 年，缩写 `y` + hour 小时，缩写 `h` + minute 分钟，缩写 `m` + second 秒，缩写 `s` + millisecond 毫秒，缩写 `ms` #### 今天 返回设置时间为今天的复制的 `KuxDayjs` 对象。 ```ts dayjs().today() ``` #### 时间的开始 返回复制的 `KuxDayjs` 对象，并设置到一个时间的开始。 ```ts dayjs().startOf('year') ``` 支持配合单位操作。缩写要区分大小写。
支持的单位列表如下：
+ week 周，缩写 `w` + month 月份，缩写 `M` + year 年，缩写 `y` + hour 小时，缩写 `h` + minute 分钟，缩写 `m` + second 秒，缩写 `s` + millisecond 毫秒，缩写 `ms` >****注意****
暂时不支持跨年操作。 #### 时间的结束 返回复制的 `KuxDayjs` 对象，并设置到一个时间的末尾。 ```ts dayjs().endOf('month') ``` 支持配合单位操作。缩写要区分大小写。
支持的单位列表如下：
+ week 周，缩写 `w` + month 月份，缩写 `M` + year 年，缩写 `y` + hour 小时，缩写 `h` + minute 分钟，缩写 `m` + second 秒，缩写 `s` + millisecond 毫秒，缩写 `ms` >****注意****
暂时不支持跨年操作。 ### 显示 当解析和操作完成后，您需要一些方式来展示 `KuxDayjs` 对象。 #### 格式化 根据传入的占位符返回格式化后的日期。 ```ts 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') ``` 支持的格式占位符列表：
| 标识 | 示例 | 描述 | | --- | --- | --- | | YYYY | 2023 | 年份，四位数 | | MM | 12 | 月份 | | DD | 01 | 日，两位数 | | HH | 22 | 小时，两位数 | | mm | 59 | 分钟，两位数 | | ss | 01 | 秒，两位数 | | SSS | 999 | 毫秒，三位数 | | A | AM/PM | 上/下午，大写 | | a | am/pm | 上/下午，小写 | | AA | 上/下午 | 上/下午 | #### 相对当前时间（前） 返回现在到当前实例的相对时间。 ```ts dayjs('2021-12-12').fromNow(); // 1年前 ``` 支持传入配置项自定义输出格式以及显示隐藏后缀，配置项定义如下：
| 参数名 | 默认值 | 说明 | | --- | --- | --- | | isSuffix | `false` | 是否自动携带后缀，为 `true` 的时候会自动添加 `'前'` 后缀，如 1年前；手动指定 `relativeTime` 时该项不生效 | relativeTime | `{s: '', m: '', mm: '', h: '', hh: '', d: '', dd: '', mon: '', mons: '', y: '', yy: ''}` | 自定义格式，变量说明见下方说明 | #### RelativeTime 说明 | 范围 | 键量 | 使用变量 | 说明 | 示例 | | --- | --- | --- | --- | --- | | 0 to 44seconds | s | %s | 几秒前 | %s seconds ago | | 45 to 89 seconds | m | %m | 1分钟前 | %m minute ago | | 90 seconds to 44 minutes | mm | %mm | 几分钟前 | %mm minutes ago | | 45 to 89 minutes | h | %h | 1小时前 | %h hour ago | | 90 minutes to 21 hours | hh | %hh | 几小时前 | %hh hours ago | | 22 to 35 hours | d | d | %d | 1天前 | %d day ago | | 36 hours to 25 days | dd | %dd | 几天前 | %dd days ago | | 26 to 45 days | mon | %mon | 1个月前 | %mon month ago | | 46 days to 10 months | mons | %mons | 几个月前 | %mons months ago | | 11 months to 17 months | y | %y | 1年前 | %y year ago | | 18 months + | yy | %yy | 几年前 | %yy years ago | #### 相对指定时间（前） 返回 X 到当前实例的相对时间。 ```ts const datetime = dayjs('2021-12-12 15:43:58'); const a = dayjs('2022-12-12'); datetime.from(a); // 1年前 ``` 支持传入配置项自定义输出格式以及显示隐藏后缀，配置项定义如下：
| 参数名 | 默认值 | 说明 | | --- | --- | --- | | isSuffix | `false` | 是否自动携带后缀，为 `true` 的时候会自动添加 `'前'` 后缀，如 1年前；手动指定 `relativeTime` 时该项不生效 | relativeTime | `{s: '', m: '', mm: '', h: '', hh: '', d: '', dd: '', mon: '', mons: '', y: '', yy: ''}` | 自定义格式，变量说明见下方说明 | #### RelativeTime 说明 | 范围 | 键量 | 使用变量 | 说明 | 示例 | | --- | --- | --- | --- | --- | | 0 to 44seconds | s | %s | 几秒前 | %s seconds ago | | 45 to 89 seconds | m | %m | 1分钟前 | %m minute ago | | 90 seconds to 44 minutes | mm | %mm | 几分钟前 | %mm minutes ago | | 45 to 89 minutes | h | %h | 1小时前 | %h hour ago | | 90 minutes to 21 hours | hh | %hh | 几小时前 | %hh hours ago | | 22 to 35 hours | d | d | %d | 1天前 | %d day ago | | 36 hours to 25 days | dd | %dd | 几天前 | %dd days ago | | 26 to 45 days | mon | %mon | 1个月前 | %mon month ago | | 46 days to 10 months | mons | %mons | 几个月前 | %mons months ago | | 11 months to 17 months | y | %y | 1年前 | %y year ago | | 18 months + | yy | %yy | 几年前 | %yy years ago | #### 相对当前时间（后） 返回当前实例到现在的相对时间。 ```ts dayjs('2021-12-12').toNow(); // 1年后 ``` 支持传入配置项自定义输出格式以及显示隐藏后缀，配置项定义如下：
| 参数名 | 默认值 | 说明 | | --- | --- | --- | | isSuffix | `false` | 是否自动携带后缀，为 `true` 的时候会自动添加 `'后'` 后缀，如 1年前；手动指定 `relativeTime` 时该项不生效 | relativeTime | `{s: '', m: '', mm: '', h: '', hh: '', d: '', dd: '', mon: '', mons: '', y: '', yy: ''}` | 自定义格式，变量说明见下方说明 | #### RelativeTime 说明 | 范围 | 键量 | 使用变量 | 说明 | 示例 | | --- | --- | --- | --- | --- | | 0 to 44seconds | s | %s | 几秒后 | %s seconds after | | 45 to 89 seconds | m | %m | 1分钟后 | %m minute after | | 90 seconds to 44 minutes | mm | %mm | 几分钟后 | %mm minutes after | | 45 to 89 minutes | h | %h | 1小时后 | %h hour after | | 90 minutes to 21 hours | hh | %hh | 几小时后 | %hh hours after | | 22 to 35 hours | d | d | %d | 1天后 | %d day after | | 36 hours to 25 days | dd | %dd | 几天后 | %dd days after | | 26 to 45 days | mon | %mon | 1个月后 | %mon month after | | 46 days to 10 months | mons | %mons | 几个月后 | %mons months after | | 11 months to 17 months | y | %y | 1年后 | %y year after | | 18 months + | yy | %yy | 几年后 | %yy years after | #### 相对指定时间（后） 返回当前实例到现在的相对时间。 ```ts const datetime = dayjs('2021-12-12 15:43:58'); const a = dayjs('2022-12-12'); console.log(datetime.to(a)); // 输出 1年后 ``` 支持传入配置项自定义输出格式以及显示隐藏后缀，配置项定义如下：
| 参数名 | 默认值 | 说明 | | --- | --- | --- | | isSuffix | `false` | 是否自动携带后缀，为 `true` 的时候会自动添加 `'后'` 后缀，如 1年前；手动指定 `relativeTime` 时该项不生效 | relativeTime | `{s: '', m: '', mm: '', h: '', hh: '', d: '', dd: '', mon: '', mons: '', y: '', yy: ''}` | 自定义格式，变量说明见下方说明 | #### RelativeTime 说明 | 范围 | 键量 | 使用变量 | 说明 | 示例 | | --- | --- | --- | --- | --- | | 0 to 44seconds | s | %s | 几秒后 | %s seconds after | | 45 to 89 seconds | m | %m | 1分钟后 | %m minute after | | 90 seconds to 44 minutes | mm | %mm | 几分钟后 | %mm minutes after | | 45 to 89 minutes | h | %h | 1小时后 | %h hour after | | 90 minutes to 21 hours | hh | %hh | 几小时后 | %hh hours after | | 22 to 35 hours | d | d | %d | 1天后 | %d day after | | 36 hours to 25 days | dd | %dd | 几天后 | %dd days after | | 26 to 45 days | mon | %mon | 1个月后 | %mon month after | | 46 days to 10 months | mons | %mons | 几个月后 | %mons months after | | 11 months to 17 months | y | %y | 1年后 | %y year after | | 18 months + | yy | %yy | 几年后 | %yy years after | #### 日历时间 传入指定年月获取指定年月的日历面板数据，指定年月省略时默认获取当年年月的数据。返回 `DateFormat[]`，`DateFormat` 见下方说明。 ```ts dayjs().calendar(); ``` ##### 传入参数
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | year | `number` | 否 | `0` | 指定年份，默认值为 0 | month | `number` | 否 | `0` | 指定月份，默认值为 0 ##### DateFormat 说明
| 参数名 | 类型 | 说明 | | --- | --- | --- | | year | `number` | 年份 | month | `number` | 月份 | render | `any` | 留存字段 | lunar | `LunarType` | 农历信息，见下方说明 | fullLunar | `InfoType` | 农历完整数据信息，见下方说明 | diffDays | `number` | 距离今天的差值，正数表示多少天后，负数表示多少天前，`0` 表示今天时间 | isToday | `boolean` | 农历中是否为今天 | fullDate | `string` | 完整日期 ##### LunarType 说明
| 参数名 | 类型 | 说明 | | --- | --- | --- | | month | `string` | 农历月份大写 | date | `string` | 农历日期大写 ##### InfoType 说明
| 参数名 | 类型 | 说明 | | --- | --- | --- | | lunarY | `number` | 农历年份数字 | lunarM | `number` | 农历月份数字 | lunarD | `number` | 农历日期数字 | isLeap | `boolean` | 是否闰月 #### 差异（Diff） 返回指定单位下两个日期时间之间的差异。 ```ts const date1 = dayjs('2019-01-25'); const date2 = dayjs('2018-06-05'); date1.diff(date2) // 20214000000 默认单位是毫秒 ``` 要获取其他单位下的差异，则在第二个参数传入相应的单位。 ```ts const date1 = dayjs('2019-01-25'); date1.diff('2018-06-05', 'month') // 7; ``` 默认情况下会将结果进位成整数。 如果要得到一个浮点数，将 `true` 作为第三个参数传入。 ```ts 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位数字，毫秒 ```ts dayjs('2019-01-25').valueOf() // 1548381600000 ``` #### Unix时间戳 返回当前实例的 UNIX 时间戳，10位数字，秒 ```ts dayjs('2019-01-25').valueOf() // 1548381600 ``` 此值不包含毫秒信息，会进位到秒。 #### 获取月天数 获取当前月份包含的天数。 ```ts const date = dayjs('2023-12-12'); // 31 ``` #### 转Date 从 `KuxDayjs` 中获取原生的Date对象。 ```ts dayjs('2023-12-12').toDate(); ``` #### 转数组 返回一个包含各个时间信息的 Array。 ```ts const datetime = dayjs('2023-12-13 10:16:18');// [2023,12,13,10,16,18,0] ``` #### 转JSON 序列化为 `ISO 8601` 格式的字符串。 ```ts dayjs('2023-12-13 10:16:18').toJSON(); // 2023-12-13T10:16:18.000Z ``` #### 转对象 返回包含时间信息的 Object。 ```ts 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` 格式字符串。 ```ts dayjs('2023-12-13 10:16:18').toRFCString(); // Wed, 13 Dec 2023 10:16:18 GMT ``` ### 查询 `KuxDayjs` 对象还有很多查询的方法。 #### 是否之前 表示 `KuxDayjs` 对象是否在另一个提供的日期时间之前。 ```ts dayjs('2023-12-13 10:16:18').isBefore('2024-12-12'); // true ``` 如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。 ```ts 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` 对象是否和另一个提供的日期时间相同。 ```ts dayjs('2023-12-13 10:16:18').isBefore('2023-12-12'); // false ``` 如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。 ```ts 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` 对象是否在另一个提供的日期时间之后。 ```ts dayjs('2023-12-13 10:16:18').isAfter('2023-12-12'); // true ``` 如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。 ```ts 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` 对象是和另一个提供的日期时间相同或在其之前。 ```ts dayjs('2023-12-13 10:16:18').isSameOrBefore('2023-12-12'); // false ``` 如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。 ```ts 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` 对象是和另一个提供的日期时间相同或在其之前。 ```ts dayjs('2023-12-13 10:16:18').isSameOrAfter('2023-12-12'); // true ``` 如果想使用除了毫秒以外的单位进行比较，则将单位作为第二个参数传入。 ```ts 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` 对象是否在其他两个的日期时间之间。 ```ts dayjs('2023-12-13').isBetween('2023-12-13', '2023-12-14'); // 默认毫秒 ``` 如果想使用除了毫秒以外的单位进行比较，则将单位作为第三个参数传入。 ```ts 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` 如果想自定义包含关系进行比较，则将包含关系作为第四个参数传入。 ```ts dayjs('2023-12-13').isBetween('2023-12-13', '2023-12-14', 'day', '['); ``` 包含关系列表如下：
+ `[` - 向前包含，等同于 `<=` + `]` - 向后包含，等同于 `>=` + `[]` - 前后都包含 #### 是否是KuxDayjs 这表示一个变量是否为 `KuxDayjs` 对象。 ```ts dayjs().isDayjs(dayjs()); // true dayjs().isDayjs(new Date()); // false ``` #### 是否闰年 查询 `KuxDayjs` 对象的年份是否是闰年。 ```ts dayjs('2000-01-01').isLeapYear(); // true ```