YH-UI

中文

English

中文

English

Appearance

Calendar 日历 ​

为用户提供导航、查看日期或记录日程的功能。支持假期显示、日期范围选择、多选、周数显示等高级特性。

基础用法 ​

设置 v-model 来指定当前选中的日期，默认为今天。日历采用现代化设计，具有精美的动画效果和交互体验。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
基础用法

假期显示 ​

设置 show-holiday 开启中国法定节假日显示。假期会显示 "休" 标记，补班日显示 "班" 标记。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
休
5
休
6
休
7
8
9
10
11
假期显示

自定义内容 ​

通过具名插槽 date-cell 来自定义日历单元格显示的内容。作用域参数 data 包含了丰富的日期信息。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
妇女节
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
自定义内容

日期范围限制 ​

通过 min-date 和 max-date 限制可选择的日期范围。超出范围的日期将被禁用。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
日期范围限制

只读模式 ​

设置 readonly 属性使日历进入只读模式，用户将无法选择日期。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
只读模式

范围选择 ​

设置 selection-mode="range" 开启日期范围选择模式，配合 v-model:range-value 使用。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11

已选择：请选择日期范围

范围选择

显示周数 ​

设置 show-week-number 在日历左侧显示 ISO 周数。

2026年3月
周日一二三四五六
9
1
2
3
4
5
6
7
10
8
9
10
11
12
13
14
11
15
16
17
18
19
20
21
12
22
23
24
25
26
27
28
13
29
30
31
1
2
3
4
14
5
6
7
8
9
10
11
显示周数

禁用指定日期 ​

通过 disabled-date 函数自定义禁用逻辑。以下示例禁用了所有周末。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
禁用指定日期

全屏模式 ​

设置 fullscreen 使日历占满父容器高度，适合用于日程管理页面。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
休
5
休
6
休
7
8
9
10
11
全屏模式

尺寸 ​

提供 small、default、large 三种尺寸。

Small 尺寸

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11

Default 尺寸（默认）

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11

Large 尺寸

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
不同尺寸

在 Nuxt 中使用 ​

Calendar 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，组件会自动导入，无需手动注册。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
休
5
休
6
休
7
8
9
10
11
Nuxt 中使用

SSR 注意事项：

  • ✅ 基础渲染和矩阵计算完全支持 SSR
  • ✅ 假期数据在服务端完成计算
  • ✅ 插槽内容在服务端生成，Hydration 表现优异
  • ⚠️ 范围选择的 hover 效果为客户端行为

SSR 性能

Calendar 内部采用静态日期缓存逻辑，即使在 SSR 环境下频繁刷新，内存占用也极低。

API ​

Props ​

属性名说明类型默认值
v-model绑定值（单选模式）Date—
default-value默认选中的日期Date—
mode视图模式'month' | 'year''month'
first-day-of-week每周的第一天（1-7，1为周一）number7 (周日)
min-date可选择的最小日期Date—
max-date可选择的最大日期Date—
readonly是否只读booleanfalse
disabled是否禁用booleanfalse
disabled-date自定义禁用日期函数(date: Date) => boolean—
show-holiday是否显示节假日标记booleanfalse
holidays自定义假期数据HolidayMap{}
show-week-number是否显示周数booleanfalse
fullscreen是否全屏模式（占满容器）booleanfalse
selection-mode选择模式'single' | 'range' | 'multiple''single'
range-value范围选择值[Date?, Date?]—
multiple-value多选值Date[][]
show-other-months是否显示非当月日期booleantrue
highlight-weekends是否高亮周末booleantrue
size日历尺寸'small' | 'default' | 'large''default'
cell-class-name单元格自定义类名函数(date: Date) => string | string[] | object—
month-header-format标题格式化string'YYYY 年 MM 月'

Events ​

事件名说明回调参数
change选中日期发生变化时触发(date: Date) => void
select点击日期单元格时触发(date: Date, cell: CalendarDateCell) => void
panel-change面板显示的年月或模式发生变化时触发`(date: Date, mode: 'month'
range-change范围选择完成时触发(range: [Date, Date]) => void

Slots ​

插槽名说明参数
header自定义日历头部{ date: string }
date-cell自定义日期单元格内容{ data: CalendarDateCell }
footer自定义日历底部—

Expose ​

通过 ref 可以访问到组件内部暴露的方法和属性：

方法/属性名说明类型
displayDate当前显示的视口日期对象 (Dayjs)Ref<Dayjs>
selectedDate当前选中的日期（单选模式, Dayjs）`Ref<Dayjs
moveMonth切换月份 (参数 delta 为 1 或 -1)(delta: number) => void
goToday组件跳转至今天() => void
selectDate手动选中某个日期单元格(cell: CalendarDateCell) => void

CalendarDateCell 类型 ​

属性说明类型
day格式化的日期字符串（YYYY-MM-DD）string
date原始 Date 对象Date
type日期类型'prev-month' | 'current-month' | 'next-month'
isSelected是否选中boolean
isToday是否今天boolean
isDisabled是否禁用boolean
isWeekend是否周末boolean
isHoliday是否假期boolean
holidayName假期名称string | undefined
isWorkday是否补班日boolean
isInRange是否在范围内boolean
isRangeStart是否范围起始boolean
isRangeEnd是否范围结束boolean

HolidayMap 类型 ​

typescript
type HolidayMap = Record<string, {
  name: string      // 假期名称
  isOffDay: boolean // true=放假, false=补班
}>

主题变量 ​

Calendar 组件支持通过覆盖以下 CSS 变量来自定义局部样式。所有颜色变量已与全局主题系统对接，自动支持暗黑模式：

变量名说明默认值
--yh-calendar-bg日历基础背景var(--yh-bg-color)
--yh-calendar-text默认文字颜色var(--yh-text-color-primary)
--yh-calendar-primary选中/今天主题色var(--yh-color-primary)
--yh-calendar-primary-light范围/悬浮背景色var(--yh-color-primary-light-9)
--yh-calendar-primary-dark选中悬浮加深色var(--yh-color-primary-dark-2)
--yh-calendar-cell-height单元格高度100px
--yh-calendar-cell-radius单元格圆角var(--yh-radius-lg)
--yh-calendar-head-height头部高度80px
--yh-calendar-title-size顶部标题字号22px
--yh-calendar-weekday-color星期表头颜色var(--yh-text-color-secondary)
--yh-calendar-holiday-color假期标记颜色var(--yh-color-danger)
--yh-calendar-week-number-color周数文字颜色var(--yh-text-color-placeholder)

样式兼容性说明 ​

由于 Calendar 内部采用标准 table 布局，如果您在 VitePress、Markdown 或某些具有激进全局 Table 样式的后台系统中使用，可能因为全局样式的斑马纹（Zebra Line）或边框注入导致背景显示异常。

核心样式隔离 ​

YH-UI 遵循源码纯净原则，组件 SCSS 中不包含任何针对特定文档环境的暴力 !important 补丁。如果您在自己的 Markdown 环境中发现背景消失或出现多余边距，可以尝试在项目中添加以下全局样式代码：

css
/* 清理文档环境对日历表格的干扰 */
.your-container-class .yh-calendar__table,
.your-container-class .yh-calendar__table tr,
.your-container-class .yh-calendar__table td {
  background-color: transparent !important;
  border: none !important;
  margin: 0 !important;
  padding: 0 !important;
}

为什么使用 !important?

这是为了压制某些 Markdown 渲染器注入的高权重全局选择器（如 .markdown-body table tr:nth-child(2n)）。在普通的 Vue/Nuxt 业务项目中，您无需添加这些补丁。

高级用法示例 ​

结合日程管理 ​

展示如何在日历单元格中自定义内容，模拟真实的日程安排。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
休
5
休
6
休
7
8
9
10
11
结合日程管理

会议室预约系统 ​

演示利用 selection-mode="range" 实现会议室预定逻辑，并限制不可选日期。

2026年3月
日一二三四五六
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
会议室预约系统

Released under the MIT License.

Copyright © 2024-present YH-UI Team