Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Calendar 日历
按月显示日期,可以选一天、选一段范围或选多天,还能显示农历和日程标记。用于排班、日程、打卡这类直接把日历摆在页面上的场景;只是要在表单里填一个日期时用 DatePicker。
引入
import { NsCalendar } from '@ns/ui'
基础用法
用 v-model 绑定选中的日期。点日期选中;点标题里的年份、月份可以切到年份视图、月份视图快速跳转。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
const value = ref(new Date())
</script>
<template>
<NsCalendar v-model="value" />
<p style="margin-top: 12px">选中:{{ value.toLocaleDateString() }}</p>
</template>
不绑定 v-model 也能用,组件自己记住选中的日期,通过 select 事件拿到结果。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
const selected = ref('')
</script>
<template>
<NsCalendar @select="(date) => (selected = date.toLocaleDateString())" />
<p style="margin-top: 12px">{{ selected ? `select 事件:${selected}` : '点一个日期试试' }}</p>
</template>
一周从星期几开始
firstDayOfWeek 取 1 到 7,表示周一到周日,默认 7(周日开始)。切换下面的选项看星期标题和日期排列的变化:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar, NsSegmented, NsSpace } from '@ns/ui'
const value = ref(new Date())
const firstDay = ref<string | number>(1)
const options = [
{ label: '周一(1)', value: 1 },
{ label: '周二(2)', value: 2 },
{ label: '周三(3)', value: 3 },
{ label: '周四(4)', value: 4 },
{ label: '周五(5)', value: 5 },
{ label: '周六(6)', value: 6 },
{ label: '周日(7)', value: 7 }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSegmented v-model="firstDay" :options="options" />
<NsCalendar v-model="value" :first-day-of-week="Number(firstDay)" />
</NsSpace>
</template>
禁用日期
disabledDate 是一个函数,返回 true 的日期不能选。一个月(一年)里所有日期都被禁用时,月份视图(年份视图)里对应的格子也不能点。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
const value = ref<Date>()
// 今天以前的日期不能选
const disabledDate = (date: Date) => {
const today = new Date()
today.setHours(0, 0, 0, 0)
return date.getTime() < today.getTime()
}
</script>
<template>
<NsCalendar v-model="value" :disabled-date="disabledDate" />
</template>
再看两种常见的写法:左边周末不能选;右边只能选今年,点标题里的年份切到年份视图,别的年份都是灰的。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar, NsSpace } from '@ns/ui'
const workday = ref<Date>()
const thisYear = ref<Date>()
const isWeekend = (date: Date) => date.getDay() === 0 || date.getDay() === 6
const notThisYear = (date: Date) => date.getFullYear() !== new Date().getFullYear()
</script>
<template>
<NsSpace wrap align="start" size="large">
<NsCalendar v-model="workday" :disabled-date="isWeekend" />
<NsCalendar v-model="thisYear" :disabled-date="notThisYear" />
</NsSpace>
</template>
范围选择
select-mode="range" 时点两次选出一段范围:第一次点的是一端,第二次点的是另一端,先点晚的日期再点早的也可以,结果始终是 [开始, 结束]。范围可以跨月,点完一端后翻到别的月份再点另一端。
用 v-model:range 绑定范围,或者监听 range-change。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
const range = ref<[Date, Date] | null>(null)
</script>
<template>
<NsCalendar v-model:range="range" select-mode="range" />
<p style="margin-top: 12px">
{{
range
? `${range[0].toLocaleDateString()} 至 ${range[1].toLocaleDateString()}`
: '点两个日期选出范围'
}}
</p>
</template>
不绑定 v-model:range 时用 range-change 拿结果。范围选择时不触发 select。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
const days = ref(0)
const onRangeChange = (range: [Date, Date] | null) => {
days.value = range ? Math.round((range[1].getTime() - range[0].getTime()) / 86400000) + 1 : 0
}
</script>
<template>
<NsCalendar select-mode="range" @range-change="onRangeChange" />
<p style="margin-top: 12px">{{ days ? `共 ${days} 天` : '还没选范围' }}</p>
</template>
多选
select-mode="multiple" 时可以选多天,再点一次取消。用 v-model:model-values 绑定。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
const dates = ref<Date[]>([])
</script>
<template>
<NsCalendar v-model:model-values="dates" select-mode="multiple" />
<p style="margin-top: 12px">
已选 {{ dates.length }} 天:{{ dates.map((date) => date.getDate()).join('、') || '无' }}
</p>
</template>
农历
lunar 为 true 时在日期下面显示农历。当天是节气时显示节气,农历初一显示月份(如“正月”“闰二月”),其余显示日期(如“初二”“十五”)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
const value = ref(new Date())
</script>
<template>
<NsCalendar v-model="value" lunar />
</template>
日程标记
events 里的每一项会在对应日期下面显示一个小圆点,color 是圆点颜色(默认主色),title 是鼠标停在圆点上时的提示。同一天可以有多项,每项一个圆点。下面的日程都排在当前这个月:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
import type { CalendarEvent } from '@ns/ui'
const value = ref(new Date())
const year = value.value.getFullYear()
const month = value.value.getMonth()
const events: CalendarEvent[] = [
{ date: new Date(year, month, 3), title: '周会' },
{ date: new Date(year, month, 8), title: '发版', color: 'var(--ns-color-success)' },
{ date: new Date(year, month, 8), title: '评审', color: 'var(--ns-color-warning)' },
{ date: new Date(year, month, 16), title: '故障复盘', color: 'var(--ns-color-danger)' },
{ date: new Date(year, month, 22), title: '团建', color: 'var(--ns-color-help)' },
{ date: new Date(year, month, 22), title: '周会' },
{ date: new Date(year, month, 22), title: '培训', color: 'var(--ns-color-info)' }
]
</script>
<template>
<NsCalendar v-model="value" :events="events" />
</template>
农历和日程标记可以一起用:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
import type { CalendarEvent } from '@ns/ui'
const value = ref(new Date())
const year = value.value.getFullYear()
const month = value.value.getMonth()
const events: CalendarEvent[] = [
{ date: new Date(year, month, 5), title: '交房租', color: 'var(--ns-color-warning)' },
{ date: new Date(year, month, 20), title: '体检', color: 'var(--ns-color-success)' }
]
</script>
<template>
<NsCalendar v-model="value" lunar :events="events" />
</template>
自定义头部
header 插槽替换整个头部,插槽参数里有当前的年、月和翻页方法:prevMonth、nextMonth、prevYear、nextYear、goToToday。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCalendar } from '@ns/ui'
const value = ref(new Date())
</script>
<template>
<NsCalendar v-model="value">
<template #header="{ year, month, prevMonth, nextMonth, goToToday }">
<NsButton size="small" @click="prevMonth">上个月</NsButton>
<span>{{ year }} 年 {{ month }} 月</span>
<NsButton size="small" @click="nextMonth">下个月</NsButton>
<NsButton size="small" @click="goToToday">今天</NsButton>
</template>
</NsCalendar>
</template>
用上全部翻页方法,并把按钮排开:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsButtonGroup, NsCalendar } from '@ns/ui'
const value = ref(new Date())
</script>
<template>
<NsCalendar v-model="value">
<template #header="{ year, month, prevMonth, nextMonth, prevYear, nextYear, goToToday }">
<div class="calendar-header">
<strong>{{ year }} 年 {{ month }} 月</strong>
<NsButtonGroup size="small">
<NsButton icon="double-left" aria-label="上一年" @click="prevYear" />
<NsButton icon="chevron-left" aria-label="上个月" @click="prevMonth" />
<NsButton @click="goToToday">今天</NsButton>
<NsButton icon="chevron-right" aria-label="下个月" @click="nextMonth" />
<NsButton icon="double-right" aria-label="下一年" @click="nextYear" />
</NsButtonGroup>
</div>
</template>
</NsCalendar>
</template>
<style scoped>
.calendar-header {
display: flex;
flex: 1;
align-items: center;
justify-content: space-between;
}
</style>
自定义日期格子
cell 插槽替换格子里的内容,格子本身的选中、禁用样式和点击行为不变。插槽参数有 date、text、type、disabled、selected、events,开了 lunar 时还有 lunar、lunarDisplay,范围选择时有 inRange、isStart、isEnd。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
import type { CalendarEvent } from '@ns/ui'
const value = ref(new Date())
const year = value.value.getFullYear()
const month = value.value.getMonth()
const events: CalendarEvent[] = [
{ date: new Date(year, month, 10), title: '周会' },
{ date: new Date(year, month, 10), title: '评审' },
{ date: new Date(year, month, 18), title: '发版' }
]
</script>
<template>
<NsCalendar v-model="value" :events="events">
<template #cell="{ text, date, events: dayEvents }">
<span>{{ text }}</span>
<small v-if="date.getDay() === 0 || date.getDay() === 6">休</small>
<small v-else-if="dayEvents.length">{{ dayEvents.length }} 项</small>
</template>
</NsCalendar>
</template>
范围选择时用 isStart、isEnd 在两端标出“入住”“离店”,用 lunarDisplay 显示农历:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCalendar } from '@ns/ui'
const range = ref<[Date, Date] | null>(null)
</script>
<template>
<NsCalendar v-model:range="range" select-mode="range" lunar>
<template #cell="{ text, isStart, isEnd, lunarDisplay }">
<div class="cell">
<span>{{ text }}</span>
<small>{{ isStart ? '入住' : isEnd ? '离店' : lunarDisplay }}</small>
</div>
</template>
</NsCalendar>
</template>
<style scoped>
.cell {
display: flex;
flex-direction: column;
align-items: center;
line-height: 1.2;
}
</style>
方法
通过 ref 调用。翻月的 prevMonth、nextMonth 会把绑定值改成那个月的 1 号(见“注意事项”);goToToday 回到今天并选中;selectDate 相当于点了某一天。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCalendar, NsSpace } from '@ns/ui'
import type { CalendarInstance } from '@ns/ui'
const calendarRef = ref<CalendarInstance>()
const value = ref(new Date())
// 选中下个月 15 号
const selectNextMonth15 = () => {
const today = new Date()
calendarRef.value?.selectDate(new Date(today.getFullYear(), today.getMonth() + 1, 15))
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButton size="small" @click="calendarRef?.prevYear()">prevYear</NsButton>
<NsButton size="small" @click="calendarRef?.prevMonth()">prevMonth</NsButton>
<NsButton size="small" @click="calendarRef?.goToToday()">goToToday</NsButton>
<NsButton size="small" @click="calendarRef?.nextMonth()">nextMonth</NsButton>
<NsButton size="small" @click="calendarRef?.nextYear()">nextYear</NsButton>
<NsButton size="small" @click="selectNextMonth15">selectDate(下月 15 号)</NsButton>
</NsSpace>
<NsCalendar ref="calendarRef" v-model="value" />
<span>绑定值:{{ value.toLocaleDateString() }}</span>
</NsSpace>
</template>
键盘操作
| 按键 | 作用 |
|---|---|
Tab | 焦点进入日期区域,落在选中的日期上;没有选中时落在今天或当月 1 号 |
← → | 前一天、后一天 |
↑ ↓ | 上一周、下一周的同一天 |
Enter 空格 | 选中焦点所在的日期 |
方向键移到别的月份时会自动翻页,只翻页,不改绑定值。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | Date | - | 单选时选中的日期,支持 v-model |
| modelValues | Date[] | - | 多选时选中的日期,支持 v-model:model-values |
| range | [Date, Date] | null | - | 范围选择时的范围,支持 v-model:range |
| selectMode | 'single' | 'range' | 'multiple' | 'single' | 选择方式。传了 range(包括 null)而没写 selectMode 时,也按范围选择处理 |
| disabledDate | (date: Date) => boolean | - | 返回 true 的日期不能选 |
| firstDayOfWeek | number | 7 | 一周从星期几开始,1 到 6 是周一到周六,7 或 0 是周日 |
| lunar | boolean | false | 是否显示农历和节气 |
| events | CalendarEvent[] | - | 日程标记 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (date: Date) | 单选时点了日期;另外,点上个月、下个月按钮,在月份视图、年份视图里选了月份、年份,也会触发,值是那个月的 1 号 |
| update:modelValues | (dates: Date[]) | 多选时选中的日期变了,值是新数组 |
| update:range | (range: [Date, Date]) | 范围选择时两端都选好了 |
| range-change | (range: [Date, Date] | null) | 同 update:range,两端都选好时触发 |
| select | (date: Date) | 单选、多选时点了日期,或调用 goToToday 选中了今天。范围选择时不触发 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| header | CalendarHeaderSlotProps:{ year, month, prevMonth, nextMonth, prevYear, nextYear, goToToday } | 替换整个头部。month 从 1 开始 |
| cell | CalendarCellSlotProps:{ date, type, text, disabled, selected, inRange, isStart, isEnd, lunar, lunarDisplay, events } | 替换日期格子里的内容 |
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| prevMonth | - | void | 翻到上个月 |
| nextMonth | - | void | 翻到下个月 |
| prevYear | - | void | 翻到上一年;年份视图里是前十年 |
| nextYear | - | void | 翻到下一年;年份视图里是后十年 |
| goToToday | - | void | 回到今天所在的月份并选中今天;今天被禁用时只翻页 |
| selectDate | (date: Date) | void | 相当于点了这个日期,按当前的选择方式处理;被禁用的日期不处理 |
类型
type CalendarSelectMode = 'single' | 'range' | 'multiple'
interface CalendarEvent {
/** 日程所在的日期,只看年月日 */
date: Date
/** 鼠标停在圆点上时的提示 */
title?: string
/** 圆点颜色,默认主色 */
color?: string
}
interface CalendarCellSlotProps {
/** 这个格子的日期(当天 0 点) */
date: Date
/** normal 当月日期,today 今天,prev-month / next-month 上个月、下个月补位的日期 */
type: 'normal' | 'today' | 'prev-month' | 'next-month'
/** 几号 */
text: number
disabled: boolean
selected: boolean
/** 范围选择时,是否在选中的范围内(含两端) */
inRange: boolean
isStart: boolean
isEnd: boolean
/** 农历信息,lunar 为 true 时才有 */
lunar?: LunarDate
/** 农历显示的文字,lunar 为 true 时才有 */
lunarDisplay?: string
/** 这一天的日程 */
events: CalendarEvent[]
}
interface LunarDate {
year: number
month: number
day: number
/** 是否闰月 */
isLeap: boolean
/** 月份名,如“正”“冬”“腊” */
monthName: string
/** 日期名,如“初一”“十五” */
dayName: string
/** 当天的节气,不是节气时为 null */
solarTerm: string | null
}
interface CalendarInstance {
prevMonth: () => void
nextMonth: () => void
prevYear: () => void
nextYear: () => void
goToToday: () => void
selectDate: (date: Date) => void
}
注意事项
- 翻月会改绑定值:点上个月、下个月按钮,或在月份视图、年份视图里选了月份、年份,
v-model的值会变成那个月的 1 号。翻年(双箭头)和键盘方向键翻页不改值。需要“只翻页不改值”时不要绑定v-model,改用select事件取值。 - 外部把
modelValue或range改成别的日期时,日历会跳到那个日期所在的月份。 - 组件发出的日期都是当天 0 点(本地时间)。传进来的日期带时分秒也可以,比较时只看年月日。
- 日历始终显示 6 行 42 个格子,前后用上个月、下个月的日期补齐。点补位的日期也能选中,单选时视图会跟着切到那个月。
- 农历支持 1900 年 1 月 31 日到 2100 年,超出范围的日期不显示农历。节气按北京时间计算。
disabledDate会对每个格子调用;打开月份视图、年份视图时还会对整月、整年的每一天调用,函数里不要做耗时的计算。- 组件最大宽度是 350px,放在更宽的容器里不会撑满。
优化点
- [x] 支持农历显示
- [x] 支持日程事件标记
- [x] 支持多选日期
- [ ] 支持月份/年份范围选择(待实现)
- [ ] 翻月时不修改绑定值(现在点上个月、下个月会把值改成那个月 1 号)
- [ ] 范围选择时鼠标移动预览范围
- [ ] 星期、月份文字支持国际化