Calendar 日历
新粗野主义风格的日历组件，基于 v-calendar DatePicker 构建，支持单日期和日期范围选择。提供粗边框 + 硬质阴影的标志性 brutal 风格，以及选中态、范围态、今天高亮等视觉反馈。
预览
基础用法
v-model 绑定（选中日期：未选择）
日期范围选择（isRange）
禁用状态
安装
pnpm dlx brutx-vue@latest add calendar需要额外安装依赖：
pnpm add v-calendar用法
单日期选择
<script setup>
import { ref } from 'vue'
import { Calendar } from 'brutx-ui-vue/calendar'
const date = ref(null)
</script>
<template>
<Calendar v-model="date" />
</template>日期范围选择
<script setup>
import { ref } from 'vue'
import { Calendar } from 'brutx-ui-vue/calendar'
const dateRange = ref(null)
</script>
<template>
<Calendar v-model="dateRange" :is-range="true" />
</template>禁用状态
<template>
<Calendar :disabled="true" />
</template>语言
日历默认读取 provideLocale 注入语言包的 code；语言包未提供代码时使用 zh-CN。可通过 locale 为单个日历指定 v-calendar 支持的语言代码：
<Calendar locale="en-US" />API 参考
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue可空 | Date | Date[] | null | undefined | undefined | 当前选中的日期，通过 v-model 更新；单日模式为 Date，范围模式为包含起止日期的 Date 数组，未选择时为 null。 |
详情声明类型Date | Date[] | null | undefined 字面量
默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
isRange | boolean | undefined | false | 启用日期范围选择；modelValue 应表示起止日期范围。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
disabled | boolean | undefined | false | 禁用日历日期选择交互。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
class | string | undefined | undefined | 追加到日历根容器的 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
events | CalendarEvent[] | undefined | []按实例调用工厂函数 | 提供需要标记的日历事件；每项包含日期和标题，并可携带自定义字段。 |
详情声明类型CalendarEvent[] | undefined 关联类型 CalendarEvent 类型定义 — CalendarEventexport interface CalendarEvent {
date: Date | string
title: string
[key: string]: unknown
}默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
eventRenderer | ((event: CalendarEvent) => unknown) | undefined | undefined | 自定义事件展示文本的回调；接收一个 CalendarEvent 并返回可渲染内容。 |
详情声明类型((event: CalendarEvent) => unknown) | undefined 关联类型 CalendarEvent 类型定义 — CalendarEventexport interface CalendarEvent {
date: Date | string
title: string
[key: string]: unknown
}默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
mode | "default" | "card" | undefined | "default" | 设置事件标记呈现方式：default 使用圆点和提示框，card 使用日历卡片和徽章。 |
详情声明类型"default" | "card" | undefined 字面量
默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
locale | string | undefined | undefined | v-calendar 的语言代码；未指定时使用 useLocale() 当前语言包的代码，缺省回退为 zh-CN。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
retroHeader | boolean | undefined | false | 显示复古挂历头部装饰；装饰内容不参与无障碍语义。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/calendar/Calendar.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@update:modelValue | [value: Date | Date[] | null] | 用户选择日期或范围变化时发出新的日期值。 |
详情声明类型[value: Date | Date[] | null] 字面量
来源packages/ui/src/components/calendar/Calendar.vue | ||
插槽
以下插槽由底层 v-calendar DatePicker 支持，并经 Calendar 透传，可用于自定义头部和日期单元格：
| 插槽 | 作用域 | 说明 |
|---|---|---|
header-prev-button | — | 自定义上一月导航按钮（默认显示 ChevronLeft 图标） |
header-title | { title: string } | 自定义头部标题（默认加粗大写显示） |
header-next-button | — | 自定义下一月导航按钮（默认显示 ChevronRight 图标） |
day-content | { day: object, dayProps: object, dayEvents: object } | 自定义日期单元格内容 |
事件标记
通过 events 属性在日历上标记事件，支持两种显示模式。
数据类型
interface CalendarEvent {
date: Date | string // 事件日期
title: string // 事件标题
[key: string]: unknown // 其他自定义字段
}事件日期如果传入 YYYY-MM-DD 字符串，会按本地日期解析为当天，不经过原生 Date 对纯日期字符串的 UTC/时区推断。完整 datetime 字符串仍按浏览器原生 Date / ISO datetime 语义解析；需要跨时区一致性时，推荐直接传入 Date 对象或带时区偏移的完整 ISO 字符串。
default 模式
圆点指示器 + Tooltip，适合事件较少的场景：
<script setup>
import { Calendar } from 'brutx-ui-vue/calendar'
const events = [
{ date: '2025-07-15', title: '团队会议' },
{ date: '2025-07-20', title: '产品发布' },
{ date: '2025-07-20', title: '代码审查' },
]
</script>
<template>
<Calendar :events="events" />
</template>card 模式
自适应高度卡片 + 胶囊徽章，适合事件较多的场景：
<script setup>
import { Calendar } from 'brutx-ui-vue/calendar'
const events = [
{ date: '2025-07-15', title: '团队会议' },
{ date: '2025-07-20', title: '产品发布' },
{ date: '2025-07-20', title: '代码审查' },
]
</script>
<template>
<Calendar :events="events" mode="card" />
</template>自定义事件渲染
通过 eventRenderer 自定义事件的渲染内容：
<script setup>
import { Calendar } from 'brutx-ui-vue/calendar'
import { h } from 'vue'
const events = [
{ date: '2025-07-15', title: '团队会议', color: 'red' },
{ date: '2025-07-20', title: '产品发布', color: 'blue' },
]
function renderEvent(event) {
return h('span', { style: { color: event.color } }, event.title)
}
</script>
<template>
<Calendar :events="events" :event-renderer="renderEvent" />
</template>可访问性
- 键盘操作：通过 v-calendar 内置支持，可使用方向键在日期间导航，
Enter/Space选择日期，Escape关闭弹出面板（如有） - ARIA 属性：v-calendar 自动为日期网格管理
role="grid"、role="gridcell"等语义化属性 - 焦点管理：导航按钮可通过
Tab键聚焦，日期单元格支持方向键导航