日期 date

好用的日期库应当保持足够简洁的 api, 保证可读性, 性能. 从前端角度来讲，日期库最大的作用就是生成一个用户易读的文本，次要作用就是转化成一个后端容易接收的数据格式（通常是一个时间戳或者日期字符串）

TC39 有个提案Temporal, 是目前 Date 构造函数的替代， 这意味着，将来某个版本该库会被取缔，但是此刻此日期库仍然是最好的选择（之一）

快速使用

12345678

<template>
 <!-- 对此刻的日期默认使用yyyy-MM-dd格式化 -->
 <div>{{ date().format() }}</div>
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'
</script>

格式化 format

前端关于日期格式化最常用的 api

1234567891011121314

<template>
  <!-- 对此刻的日期默认使用yyyy-MM-dd格式化 -->
  <div>{{ date().format() }}</div>

  <!-- 可以传入一个日期， 日期对象， 时间戳或者由date()生成的对象 -->
  <div>{{ date('2022-02-14').format('yyyy/MM/dd')}}</div>
  <div>{{ date(1644796800000).format('yyyy/MM/dd')}}</div>
  <div>{{ date(1644796800000).format('yyyy-MM-dd hh:mm:ss')}}</div>
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'
</script>

格式化匹配器

matchers 是 date 所返回的构造函数上的一个静态属性，数据是一个对象， 对象的键是需要替换的格式化的文本， 同时也是 RegExp 构造函数的参数。大多数情况下你用不到这个 api。

默认的格式化匹配器

占位符	描述	示例
yyyy	表示完整的年份	2022
M	表示月份	M -> 9, MM -> 09
D	表示日期	D -> 9, DD -> 09
h	小时(12 小时制)	h -> 2, hh -> 02
H	小时(24 小时制)	H -> 9, HH -> 09, HH -> 14
m	分	m -> 9, mm -> 09
s	秒	s -> 9, ss -> 09

你也可以自己添加格式化匹配器。

123456789101112131415161718

<template>
  <div>今天是周{{ date('2022-02-14').format('w')}}</div>
  <div>WeekDay:{{ date('2022-02-14').format('ww')}}</div>
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'

// 这是一个增加了周几替换的匹配器
date.setMatcher('w+', (date: Date, len: number) => {
  if (len === 1) {
    return '' + date.getDay()
  } else {
    return '0' + date.getDay()
  }
})
</script>

获取时间戳

时间戳是一个属性，在你第一次访问它时用原生 date 的 getTime()方法获取，后续的获取方式则直接是从缓存中获取。

12345678

<template>
<!-- 时间戳（毫秒） -->
{{(date().timestamp)}}
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'
</script>

日期计算

有时候，你需要计算相对某个时间的相对天数或者月数的日期，你可以使用 calc api.

12345678910111213141516

<template>
  <div>2022-02-14加上10天是: {{ d.calc(10, 'days').format() }}</div>

  <div>2022-02-14减去10天是: {{ d.calc(-10, 'days').format() }}</div>

  <div>2022-02-14加上1个月是: {{ d.calc(1, 'months').format() }}</div>

  <div>2022-02-14加上一个星期是: {{ d.calc(1, 'weeks').format() }}</div>
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'

const d = date('2022-02-14')
</script>

日期比较

如果你想知道两个日期之间差了多少天， 你可以使用 compare api

默认情况下compare函数传一个参数即另外一个日期时返回的是天数, 你也可以传入第二个参数, 该参数是一个函数, 改函数有三个参数year, month, day分别代表年月日

12345678910111213141516

<template>
  <div>2022-02-14 ~ 2022-03-14相差: {{date('2022-02-14').compare('2022-03-14')}}天</div>

  <div>到明年高考还有 {{date().compare(date(`${date().year + 1}-06-07`))}} 天</div>

  <div>2022-02-14 ~ 2025-03-10相差: {{dis}}</div>
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'

// 可以使用第二个参数来达到更加个性化的需求
const dis = date('2022-02-14').compare('2025-03-10', (y, m, d) => {
  return `${y}年${m}个月${d}天`
})
</script>

跳转至月末

有时候你想要获取某个月一共有多少天, 你可以进行月份跳转

也许做万年历的时候挺有用的

123456789101112131415

<template>
  <!-- 31 -->
  <div>2022-10这个月的最后一天是: {{ date('2022-10').toEndOfMonth().day }}</div>
  <div>2022-10-15这个月的最后一天是:{{ date('2022-10-15').toEndOfMonth().day }}</div>

  <div>本月最后一天是: {{ date().toEndOfMonth().day }}</div>
  <div>10个月后的最后一天是: {{ date().toEndOfMonth(10).day }}</div>

  <div>3个月前的最后一天是: {{ date().calc(-3, 'months').toEndOfMonth().day }}</div>
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'
</script>

获取年月日时分秒

提供了年月日时分秒的快捷写法

处理了月份从 0 开始的问题

12345678910111213141516171819202122

<template>
  <div>
    {{ d.year }} 年 {{ d.month }} 月 {{ d.day }} 日 {{ d.hour }} 时
    {{ d.minute }} 分 {{ d.second }} 秒
  </div>
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'
import { onBeforeUnmount, shallowRef } from 'vue'

let d = shallowRef(date())

let timer = setInterval(() => {
  d.value = date()
}, 1000)

onBeforeUnmount(() => {
  clearInterval(timer)
})
</script>

反向格式化

根据提供的被格式化的数据和格式化字符串来反推日期

1234567891011

<template>
  <div>
    <div>{{ date.from('20230727', 'yyyyMMdd').format('yyyy-MM-dd') }}</div>
    <div>{{ date.from('2023^07^27', 'YYYY^MM^dd').format('yyyy-MM-dd') }}</div>
  </div>
</template>

<script lang="ts" setup>
import { date } from '@cat-kit/fe'
</script>

插件

一个插件就是一个函数， 该函数接受一个 Date 上下文参数, 可以用来设置匹配器等等 虽然可以直接操作 Dater 的 api，但可以使用插件机制来更好的组织你的代码

123456789101112131415161718192021222324

<template>
  <div>
    今天是 {{date().format('ww')}}
  </div>
  <div>
    今天是 {{date().format('WW')}}
  </div>
</template>

<script lang="ts" setup>
import { date, type Dater } from '@cat-kit/fe'

const pluginMatcher = (dater: typeof Dater) => {
  dater.setMatcher('w+', (date: Date, len: number) => {
    return '周' + date.getDay()
  })
  dater.setMatcher('W+', (date: Date, len: number) => {
    return '星期' + date.getDay()
  })
}

date.use(pluginMatcher)
</script>